Heureka Marketplace – API

The method returns up-to-date data on the requested products.

URL

[https://www.example.com/api/1/products/availability](https://www.example.com/api/1/products/availability)

Input Parameters

Response Structure

HTTP Request

The cURL tool is used to call the URL.

curl https://www.example.com/api/1/products/availability?products[0][id]=ABC123&products[0][count]=1&products[1][id]=ABC124&products[1][count]=2

Response

{
  "products": [
    {
      "id": "ABC123",
      "available": true,
      "count": 1,
      "delivery": 0,
      "name": "Kryt na mobil Apple Silikonový kryt s MagSafe na iPhone 16 Pro černý",
      "price": 1272,
      "priceTotal": 1272
    },
    {
      "id": "ABC124",
      "available": true,
      "count": 1,
      "delivery": 0,
      "name": "Mobilní telefon APPLE iPhone 16 Pro 128GB černý titan",
      "price": 29882,
      "priceTotal": 29882
    }
  ],
  "priceSum": 31154
}

The store no longer sells the product. What should the response look like?

Return false in the available parameter.

The store sells the product, but does not know how long delivery will take. What should the response look like?

available must be set to true and delivery to -1 or another appropriate text description. As a general rule, whatever is listed in the XML feed must also be available for purchase on Heureka.

The customer requests 3 items, but the store only has two. What should the response look like?

Specify 2 in the count parameter. The customer will be notified of this restriction.

The customer requests 3 items; the store has 2 in stock and 1 arriving in 5 days. What should the delivery value be?

The delivery value must reflect the worst-case scenario—if the store is able to deliver all 3 items, the value will be 5.

The customer requests 1 item, but the store has 10 available. Should the store specify 10 in count?

No. The count value must be at most the number of items requested by the customer.

Returns shipping and payment options—for example, that goods can be delivered via Czech Post or PPL with the option of cash on delivery (COD).

Each participating store submits via the API how it dispatches goods to the customer. The customer then selects one of these methods.

Card payments are processed by Heureka using the Adyen service. This option cannot be removed or surcharged, regardless of whether the store natively supports such payment methods.

For cash on delivery (COD), where payment is handled on the store’s side, the situation is different. Here, Heureka fully respects the store’s settings and displays them to the customer accordingly. This means that if the store does not support cash on delivery, it will not be offered to the customer.

In the binding parameter, the store specifies how a specific payment method is linked to a delivery method. For example, “cash upon pickup” is linked to the delivery method “personal pickup at the Prague branch”.

It is assumed that once the order is paid for, the store is capable of delivering the items using any of the offered options.

Branch Identification

The store parameter serves to clearly identify the branch where the order can be picked up. A distinction is made between two types: own branches / store pickup points.

Own branches must have the correct ID. This ID is also used within the XML Availability Feed (optional). You can find it in the branch administration panel. For own branches, this is the Depot ID used for the availability XML file.

The store parameter is only relevant for personal pickups at branches or pickup points. Do not send it for other shipping options.

URL

GET [https://www.example.com/api/1/payment/delivery](https://www.example.com/api/1/payment/delivery)

Input Parameters

Response Structure

HTTP Request

The cURL tool is used to call the URL.

curl https://www.example.com/api/1/payment/delivery?products[0][id]=ABC123&products[0][count]=1&products[1]
[id]=ABC124&products[1][count]=2

Response

{
   "transport": [
   {
       "id": 1,
       "type": 3,
       "name": "PPL",
       "price": 120.00,
       "description": "Do 1 - 2 pracovních dní."
   },
   {
       "id": 2,
       "type": 9,
       "name": "Z-Box",
       "price": 100.00,
       "description": "Do 2 - 3 pracovních dní."
       "store": {
       "type": 3,
       "id": 10     
  },
   },
   {
       "id": 4,
       "type": 1,
       "name": "Osobní odběr Ostrava",
       "price": 0.00,
       "description": "O tom, že je zboží připraveno k odběru Vás bu...",
       "store":
        {
           "id": 2020,
           "type": 1
        }
   }],
   "payment":[
   {
       "id": 400,
       "type":4,
       "price": 0.00,
       "name": "Bankovní převod"
   },
   {
       "id": 200,
       "type":1,
       "price": 33.00,
       "name": "Dobírka PPL"
   },
   {
       "id": 300,
       "type": 3,
       "price": 0.00,
       "name": "Platba kartou"
   },
   {
       "id": 100,
       "type": 2,
       "price": 10.00,
       "name": "Platba při převzetí"
   }],
   "binding": [
   {
       "id": 1,
       "transportId": 1,
       "paymentId": 200
   },
   {
       "id": 5,
       "transportId": 1,
       "paymentId": 300
   },
   {
       "id": 2,
       "transportId": 2,
       "paymentId": 400
   },
   {
       "id": 6,
       "transportId": 2,
       "paymentId": 300
   },
   {
       "id": 4,
       "transportId": 4,
       "paymentId": 300
   },
   {
       "id": 7,
       "transportId": 4,
       "paymentId": 100
   }]
}

What are bindings used for?

Bindings are important so that we can correctly display the available shipping options to the customer for the selected payment method.

Does the store need to send card payments and their shipping bindings if they are managed by you?

Card payments (and other online payments) are handled by Heureka via Adyen, so it might seem that information from you about card payments is not needed. To some extent, it isn’t. If you don’t send it, nothing happens—we will generate the relevant bindings ourselves. However, if you do send them, we will send you the specific payment and shipping IDs selected by the buyer when an order is placed. The store can then correctly pair them in its shop system.

The store has two items in stock and can deliver them immediately, but the customer wants three items, and the third item won’t be available to the store for five days. What should the delivery value look like?

The delivery value must reflect the timeframe in which the store is able to deliver the complete order. In this case, that value is five.

How should Czech Post be sent with and without cash on delivery (COD)?

Two things must be distinguished here: Czech Post is a shipping option, and cash on delivery is a payment method. These two must be linked using bindings. It would be an error to differentiate payment methods (such as cash on delivery or payment in advance) within transport.

Example of the correct procedure:

{
	"transport": [
	{
	    "id": 1,
	    "type": 1,
	    "name": "Česká pošta",
	    "price": 100.00,
	    "description": "Do 1 - 2 pracovních dní."
	}],
	"payment": [
	{
		"id": 1,
		"type": 1,
		"name": "Dobírka"
		"price": 30.00
	},
	{
		"id": 2,
		"type": 3,
		"name": "Platební karta",
		"price": 0.00
	}],
	"binding": [
	{
		"id": 1,
		"transportId": 1,
		"paymentId": 1
	},
	{
		"id": 2,
		"transportId": 1,
		"paymentId": 2
	}]
}
           

Returns the order status in the store.

URL

[https://www.example.com/api/1/order/status](https://www.example.com/api/1/order/status)

Input Parameters

Response Structure

HTTP Request

The cURL tool is used to call the URL.

{
    
"order_id":
 
2011101001
,
    
"status":
 
0

}           	

How often is this request used?

We automatically query the order status several times a day. Usually, this happens in the morning, around noon, and in the afternoon.

Sending the order to the store.

After sending, the store should reserve the goods and begin the dispatch process (if the order is paid or is cash on delivery).

In the case of personal pickup, we strictly require only the first name, last name, email, and phone number fields from the customer. The customer has the option to fill in their billing address, but if they do not, we send the following address in the billing details via the API:

• Name: Osobní odběr (Personal pickup)
• Street & House No.: Osobní odběr 1
• City: Praha
• ZIP Code: 11000
• Country: Česká republika

Note – Meaning of deliveryId and paymentId

To allow the store to identify which payment and shipping method the customer selected, their corresponding IDs—which were provided by the store in the payment/delivery method—are sent.

It may happen that the store does not send (does not support) a payment method such as credit/debit card in the payment/delivery method. Nevertheless, the user can still select it because this payment option is independent of the store (it is handled directly by Heureka). In this case, no value is available for paymentId. Heureka will attempt to replace this value with the ID for bank transfer. If the store does not support bank transfers either, a value of 0 will be sent in paymentId. However, if a payment with paymentId 0 already exists, the highest available paymentId increased by 1 will be used.

Example:

Branches Provided via DepotAPI

If the customer selects delivery to a branch provided via DepotAPI, the delivery address is populated with the address of the selected branch.

Note on the Meaning of the eLicence Parameter

The eLicence parameter indicates that the order contains a product with an electronic license—these products use electronic distribution, rather than traditional shipping. In the event that the order does not contain a product with traditional shipping, deliveryId is selected as the highest deliveryId from the GET payment/delivery method, incremented by 1 (e.g., if the highest deliveryId is 5, it will be 6 for eLicence).

URL

Input Parameters

Response Structure

HTTP Request

The cURL tool is used to call the URL.

curl -d "products[0][id]=ABC123&products[0][count]=1&products[0][price]=100&products[0][totalPrice]=100&products[0][gifts][0][name]=darek&products[0][gifts][0][shopGiftId]=drk1&customer[firstname]=Jan&customer[lastname]=Novak&customer[street]=Jiraskova%209&customer[phone]=728000000&customer[city]=Jablonec&customer[company]=&customer[postCode]=46601&customer[state]=%C4%8Cesk%C3%A1%20republika&customer[email][email protected]&deliveryAddress[firstname]=Jan&deliveryAddress[lastname]=Kos&deliveryAddress[street]=Liberecka%20999&deliveryAddress[city]=Jablonec&deliveryAddress[company]=&deliveryAddress[postCode]=46601&deliveryAddress[state]=%C4%8Cesk%C3%A1%20republika&deliveryAddress[note]=Poznámka%20TEST%20Heureka&deliveryId=100&paymentId=203&productsTotalPrice=500&paymentOnlineType[title]=Testovací%20online%20platba&paymentOnlineType[id]=1&deliveryPrice=100&paymentPrice=30.20&heureka_id=7864287" https://www.example.com/api/1/order/send

Response

{
    
"order_id":
 
2011101001
,
    
"internal_id":
 
"HRK-2012-0001"
,
    
"variableSymbol":
 
1234567890

}            	

What happens if an order fails to send?

Orders are sent via a queue. This means that after creation by the customer, the data is saved to a queue in the database and the order is sent. If an order number is not returned, it is considered an unsuccessful attempt and the submission is retried after a short while. It is attempted 5 times in total, after which unsent orders are handled individually.

Can the store reject an order?

This should not happen, as everything Heureka offers is listed by the store in its XML feed and is therefore available for sale. Naturally, a delay may occur between checking availability and sending the order, but even in this case, the store should accept the order and then resolve the situation with the customer individually.

Order Cancellation

Order cancellation is performed only exceptionally to avoid problems during dispatch.

URL

Input Parameters

Response Structure

HTTP Request

The cURL tool is used to call the URL.

curl -X PUT -d "order_id=123&reason=6" https://www.example.com/api/1/order/cancel

Response

{
    
"status":
 
true

}

If a customer requests an order cancellation, we first forward this information to the store. We only process the order cancellation after mutual agreement with the merchant in order to avoid issues with goods dispatch. We do not cancel orders on our own initiative.

URL

Input Parameters

Response Structure

HTTP Request

The cURL tool is used to call the URL.

curl -X PUT -d "order_id=123&status=1&date=2012-12-30" 
https://www.example.com/api/1/payment/status

{
    
"status":
 
true

}

No questions

Returns a list of orders in a specific payout.

URL

Input Parameters

Response Structure

The response contains text/csv. Data is separated by semicolons (;). The file includes the following columns:

• Order number
• Order date
• Type
• Reference number
• Gross product price
• Shipping fee
• Gross commission
• Total order price
• Total price reduced by commission
• Variable symbol
• Internal ID

HTTP Request

curl -X 'POST' 'https://ssl.heureka.cz/api/cart/:APIkľúč:/1/payout-report' -H 'accept: text/csv' -H 'Content-Type: application/json' -d '{"day": "2023-08-28"}'

Response

1. „Order number“;“Order date“;Type;“Reference number“;“Gross product price“;“Shipping fee“;“Gross commission“;“Total purchase amount“;“Total amount reduced by commission“;“Variable symbol“;“Internal ID“
2. 8311418522;“2023-07-17 16:10:18″;Crediting;;24;0;3,19;24;20,81;2023000007;2023000007

What is the payout date?

Payouts are always processed on Mondays, provided there is a positive amount available for payout in the virtual account.

Setting Order Status on Heureka

It is important that every order change is transferred back to Heureka. Only then can customers see the current status of their order.

URL

Input Parameters

Response Structure

HTTP Request

curl -X PUT -d "order_id=123&status=10&transport[tracking_url]=http://www.exmaple.com/?id=101010&transport[expectDelivery]=2013-01-10" https://api.heureka.cz/cart/validate/1/order/status

Reponse

{
    
"status":
 
true

}

Is there a time limit for changing the order status?

Yes, you should set the order to its final status no later than 20 days after its creation. Orders older than 20 days are automatically marked as completed by our system. If you have an issue with an order and need to keep it open longer, please contact Marketplace support.

Setting Payment Status on Heureka

This method is used to set the payment status for cash on delivery or cash payment at a store branch.

URL

Input Parameters

Response Structure

HTTP Request

curl -X PUT -d "order_id=123&status=1&date=2013-01-10" https://api.heureka.cz/cart/validate/1/payment/status

Response

{
    
"status":
 
true

}

No questions

Information on Order Status and Internal Order Number on Heureka

URL

Input Parameters

Response Structure

HTTP Request

curl https://api.heureka.cz/cart/validate/1/order/status?order_id=1234

Response

{
    
"order_id":
 
123
,
    
"status":
 
1
,
    
"internal_id":
 
8100000630
,
    
"heureka_id":
 
9782212982398

}

No questions

Information on Branches / Pickup Points

Information about branches / pickup points stored by the store on Heureka. Used to set store in GET payment/delivery.

URL

Input Parameters

none

Response Structure

HTTP Request

curl https://api.heureka.cz/cart/validate/1/stores

Response

[
    {
        
"id":
 
390
,
        
"type":
 
1
,
        
"name":
 
"Pobočka na náměstí"
,
        
"city":
 
"Brno"

    },
    {
        
"id":
 
40
,
        
"type":
 
2
,
        
"name":
 
"WeDo Praha"
,
        
"city":
 
"Praha 3"

    }
]

No questions

Information on Store Activation in Marketplace

Used to determine whether the store is enabled in Marketplace or not. If Marketplace is disabled due to an API error or a process error, it is stated in the message parameter.

Activation/deactivation information is cached for 30 minutes. If you test the store status using a cron job, choose an interval of 30 minutes or more.

URL

Input Parameters

none

Response Structure

HTTP Request

curl https://api.heureka.cz/cart/validate/1/shop/status

Response

{
    
"status":
 
false
,
    
"error":
 {
        
"message":
 
"Odezva api je větší než 5 sekund."
,
        
"created":
 
"2012-09-21 19:11:01"

    }
}

No questions