Commerce API: send orders from a shop on its own platform
Your shop's server sends its orders, customers, products and refunds to CDP, so the reports count what the browser cannot see.
A shop on WooCommerce, Shopify, CloudCart, OpenCart or Magento connects its data in a few clicks — see Connect your store. A shop on its own platform sends it from its own server instead, through the Commerce API. The Monfri tag on the shop still tracks the visits; the API adds what the browser cannot see: orders hidden by an ad blocker, cancellations, refunds, cash on delivery that was never paid, the history before the tag, and the catalogue.
The key
Use a server key that can do nothing else: in CDP, Configure → Settings → API keys → External API keys → Create external key, with the scope Commerce API (write orders, customers, products). Do not give a shop or its developer a key of type write — that one also reads and changes every profile in the workspace. Send the key in the header, never in the address:
Authorization: Bearer <your server key>
The key in your site's tag is public and does not work here. A request with the key in the address is refused before the key is read.
What to send
All requests go to https://cdp.monfri.net/v1/commerce with a JSON body of at most 1 MB and 500 records:
| Request | Body |
|---|---|
POST /orders |
{ "orders": [ … ] } |
POST /customers |
{ "customers": [ … ] } |
POST /products |
{ "products": [ … ] } |
POST /refunds |
{ "refunds": [ … ] } |
POST /events |
{ "events": [ … ] } — cart and checkout events from the server |
DELETE /products/{id} |
takes a product off sale |
GET /status |
how many orders, customers and products CDP holds, and when the last of each arrived |
A record is created or replaced by its id, so sending an order again — with a new status, or delivered — replaces the stored one. Send the complete record every time: a field you leave out is cleared, and a status you leave out returns to its default. The answer says how many were accepted and lists the ones that failed, with the reason.
Answers and errors
The answer to a POST is { "accepted": 3, "failed": 1, "errors": [ … ] }. The status is 200 when at least one record was accepted — always read failed — and 422 when none was. Correct the failed records and send only those again; repeating a request is safe.
| Status | Meaning |
|---|---|
400 |
The body is not { "orders": [ … ] }, the list is empty, or the key is in the address |
401 |
No key, or the key is unknown, revoked or expired |
403 |
The key has no Commerce API scope, or it is the key from the tag |
404 |
DELETE /products/{id}: no product with this id |
409 |
The connection Own platform (Commerce API) is disconnected in CDP |
413 |
More than 500 records, or a body over 1 MB |
429 |
Too many requests — wait the seconds in the Retry-After header |
An order
The fields: id, total, and as many of these as you have — email, customerId, status (pending, processing, completed, cancelled), financialStatus (pending, paid, partially_refunded, refunded), fulfillmentStatus, currency, shipping, tax, discount, coupons, paymentMethod, shippingMethod, createdAt and items (productId, name, quantity, price).
- Use the same order number your shop sends to Google in the
dataLayerpurchase. CDP keeps one order per number, whichever arrives first — the browser or your server. - Dates with the time zone, for example
2026-10-29T09:12:00+02:00. - Money in euro, or in leva with
"currency": "BGN"— leva are stored in euro at 1.95583. - Cash on delivery is
pendinguntil the money arrives. - The shopper's browser (optional): send
anonymousId, the value of thecdp_anonymous_idcookie in the checkout request. It joins a guest's order to the browser that shopped and read.
Products and refunds
A product: id, name, price, and url, imageUrl, brand, categoryPath, stockStatus, compareAtPrice, variants (id, price, sku, attributes) when you have them. Instead of sending products, you can give CDP a Google Merchant XML feed address in Commerce → Connections → Own platform (Commerce API); it is read at every sync.
To take a product off sale, call DELETE /products/{id} or send it with "status": "archived". The product stays in CDP, because orders point at it, and is treated as out of stock: it is not recommended and not advertised.
A refund: orderId, amount, type (refund, partial_refund, return, cancellation), reason, and the refund's own id when you have one — without it a refund is recognised by its order, type, amount and createdAt. A refund sent again is recorded once. Send the order before its refund: a refund for an order CDP does not hold is refused.
Carts and checkout
Product views, add to cart, remove from cart and the checkout steps come from the Monfri tag in the shop's pages: the tag reads the events the shop already sends to Google in the dataLayer (Enhanced Ecommerce or GA4), so the pages need no extra code.
A shop that prefers to send them from its server uses POST /events. An event has a type — product_viewed, product_added, product_removed, cart_viewed, checkout_started or checkout_step_completed — the product or the cart it is about, and who did it: anonymousId (the value of the cdp_anonymous_id cookie in the shopper's request), customerId or email; one of the three is required. Give each event an eventId: the same one again within 7 days is recorded once. The purchase is not an event — send it as an order.
An action must reach CDP one way, not both. Before your server starts sending a kind of event, tell us which kinds, and we switch those off in the tag for your shop.
When to send
Orders as they happen, and again when their status changes; the history once, in batches of up to 500, oldest first; customers and products when they change, or once a day.