E-commerce events

Two collection paths, one report#

E-commerce in AdPix is fed from two places, and both land in the same report:

The reason for the split is simple. Up to the moment of payment, the event happens on the page the customer has open, and the browser is the best place to see it. Payment itself happens off the page — the customer leaves for the gateway, may never come back, and an ad blocker may swallow the beacon. The truth about the purchase lives on your server, so send it from there.

What the browser command looks like#

ap('ecommerce', 'add_to_cart', {
  currency: 'USD',
  value: 49,
  items: [
    { item_id: 'SKU-42', item_name: 'Leather bag', price: 49, quantity: 1, category: 'bags' }
  ]
});

The second argument is the event name and the third is the e-commerce object. The command does two separate things:

1. It emits a full event under that name with value, currency and transaction_id as event parameters — so the Events report and key-event revenue see it immediately.
2. It attaches the items array as a separate context alongside the event. Collection unpacks that context and writes one row per line item. The products table and AOV are built from those rows.

Like page and track, ecommerce is bound to the statistics consent category: until the visitor has accepted it, the command sends nothing and returns quietly.

Event names#

The same set GA4 uses is accepted. Send the name with exactly this spelling — Purchase and purchase are two different events.

The four funnel steps are counted in distinct users, not events. Money and products are read only from purchase and refund; the other names still write line items, but no money report looks at them.

The fields on a line item#

Line revenue is price × quantity − discount, and that is the figure summed into the products table's revenue column. Up to 200 items are accepted on one event.

coupon, shipping, tax and affiliation at order level, and coupon and index per item, are accepted and never cause a rejection — but no report reads them today. If you need one of them in a report, send it as an ordinary event parameter instead and build a custom dimension from it.

Three things that leave the report empty#

• No items, no rows. A purchase event with no items array is visible in the Events report and in key-event revenue, but as far as the e-commerce report is concerned it does not exist. If you do not have the line detail, send at least one item carrying the order ID and the total.
• No transaction_id, no order — as above.
• No currency and amounts pile up under "unknown". Send the code as three uppercase letters, such as USD or IRR. The server path rejects an invalid code with a 422.

Send the purchase from your server#

The server-to-server path accepts the same items array and uses order_id as the transaction identity:

curl -X POST https://api.adpix.io/api/v1/s2s/events \
  -H 'Authorization: Bearer sk_...' \
  -H 'X-Sov-Site: <property_id>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "purchase",
    "event_id": "order_10482",
    "order_id": "10482",
    "email": "ali@example.com",
    "value": 4900,
    "currency": "USD",
    "items": [
      { "item_id": "SKU-42", "item_name": "Leather bag", "price": 2450, "quantity": 2 }
    ]
  }'

This path gives you three things the browser cannot:

• Re-sending does not create a second order. You choose the event_id, and it must always identify that same order. A second send with the same ID and the same body returns the first response and writes no new event.
• The order's attribution is frozen. The channel and campaign that produced the sale are written onto the order once, and the customer's later behaviour never rewrites them.
• Ad blockers and abandoned tabs are irrelevant.

Server keys, headers and error codes are covered in Server-side tracking.

Repeat purchases in the browser#

If you have no choice but to send the purchase from the browser, always include transaction_id. An event named exactly purchase that carries a transaction ID is given a stable ID derived from that transaction, so a reload of the success page, a back-navigation and a tracker retry all collapse onto one purchase.

That guard only applies to the name purchase. If your purchase event has a different name — because an event rule created it or renamed it — you need the approach described in Create and Modify event rules.

Currency#

Amounts are stored in the currency you send, with no conversion. The e-commerce report renders them with a $ sign; that sign does not change your unit, and the number next to it is the amount in your own currency.

The practical consequence: a property selling in two currencies adds them together in its revenue total. Create a separate property per currency.

Where each number comes from#

Those last two sources are deliberately kept apart: key-event revenue comes from value and knows nothing about the items array. So a purchase sent without items costs you the e-commerce report, not the revenue.

Reading the report itself is covered in The E-commerce report.

Frequently asked questions#

Related#