Hand over the cart
At the end of the advice there is a selection of your products. We call a URL in your shop that builds the cart from it, and the customer lands on your cart page.
What to do
- Tell us the path that accepts a line-item list, and the name of the parameter. If no such path exists, build it following the format below. Done when we can call the URL with your article numbers and the cart holds exactly those items with those quantities.
- Let the call replace the session's existing cart instead of adding to it. Done when the same call twice in a row yields the same cart and the quantities do not double.
- Serve the response with
Cache-Control: no-store. Done when a repeated call of the same URL reaches the shop again and is not answered from the browser or CDN cache.
Format of the line-item list
One parameter, line items separated by commas, quantity after the colon:
https://www.example-shop.com/cart/?content=MAG-1001:2,AMI-2044:1Path and parameter name are your choice. We adopt what you tell us and store it per brand. If
your shop already uses a different form, for example 687:3,683:2 with product IDs,
tell us the pattern and we send it that way.
The article numbers are exactly the ones from your product data. Which value that is per shop system is listed under keys per shop system.
Skip unknown article numbers and accept the remaining items. The call must not end on an error page.
Three requirements
- Replace, do not add The URL describes the complete cart. On each call the shop discards the session's existing cart and rebuilds it from the line items in the URL. Customers change their selection during the advice and are then sent to you again. The last call counts.
- Idempotent The same URL called twice, by reload or the back button, yields the same cart. Quantities do not add up.
- Not cached
Respond with
Cache-Control: no-storeand do not deduplicate identical calls. Otherwise the cache answers the second call and the cart stays as it was.
Two common failure modes: the cart is only filled when it is empty. Or the line items are added to the existing cart. Both mean the customer sees a different cart than in the advice.
Keys per shop system
The value we send in the link comes from your product data. If it does not match the pattern, the line item drops out of the link without an error message.
| Shop system | Key in the link | Pattern | Quantities | Coupon in link |
|---|---|---|---|---|
| Shopify | variant ID | digits | yes | yes |
| Own JSON feed | variants[].sku | ^[A-Za-z0-9-]+$ | yes | no |
| WooCommerce | g:id | ^\d+$ | yes | yes |
| JSON-LD on product pages | article number from sku | ^[0-9]+(\.[0-9]+)*$ | yes | no |
| PrestaShop | product handle | path segment | no | no |
For WooCommerce we send all line items in one parameter as soon as you tell us its name.
Without that we hand over only the first item via add-to-cart.
For PrestaShop we currently hand over one product and link its detail page. Tell us a URL that accepts several line items and we hand over the complete cart. We also need to know which identifier that URL expects, the product ID or the article number.
Reserved parameters
We occupy these names in the cart link itself. If you use them for tracking, pick other names, otherwise they overwrite the line-item list.
| Shop system | Occupied |
|---|---|
| Own JSON feed | content, or the name agreed with you |
| WooCommerce | add-to-cart, quantity, or the agreed name |
| JSON-LD on product pages | i, or the agreed name |
Affiliate identifier, sub identifier and coupon code are appended in addition. We agree the names with you, see step 3.
Check it yourself
Three calls and you know whether the handoff holds:
curl -sI "https://www.example-shop.com/cart/?content=MAG-1001:2,AMI-2044:1" | grep -i cache-control
# open the cart in a browser, compare line items and quantities
# call the same URL again, the cart must be identicalThe full contract as a file, with parameters, response codes and examples: cart-handoff.openapi.yaml (OpenAPI 3.1).
If something does not fit, write to us via the partner contact and name the URL you built. We call it and report what we see.