Skip to main content

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.

M
Monfri Team
Updated ·5 min read

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 dataLayer purchase. 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 pending until the money arrives.
  • The shopper's browser (optional): send anonymousId, the value of the cdp_anonymous_id cookie 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.

Didn't find your answer?

Write to us and tell us what you were trying to do.