Tracking API

Authentication

Every endpoint on this page takes your secret REST key: Authorization: Bearer rk_…. Find it under Tracking → Configuration → Developers. Only its SHA-256 hash is stored, so a lost key can be regenerated but never recovered — and regenerating invalidates the old one immediately.

The public tk_ key that sits in your storefront's page source is not accepted on the order rails. A browser-assertable purchase would let anyone reading your page inject fabricated conversions into your ad accounts; a browser-assertable refund would let them retract real ones.

Five rules that decide everything

• Money is major units on the wire on the /api/track endpoints. Send 49.99, never 4999. The server converts using each currency's own exponent, so JPY and KRW are handled correctly without a special case on your side. The one exception is the Orders API v1 (/api/v1/orders), which takes integer minor units: 4999 for 49.99.
• Consent is required on this rail. POST /api/track and POST /api/track/identify answer 400 consent_required when c is absent — your server knows what its data subject agreed to. c: "denied" is a real 200 (reason: consent_denied on the batch rail): the request did what you asked.
• Read the 2xx body. stored: 0 is a legitimate success outcome. Treating any 200 as "delivered" is how a consent-denied or fully-duplicate batch looks identical to a stored one.
• Everything is idempotent on a key you control. orderId for purchases, refundId for refunds, eid per event. Send them and retry freely; omit eid and a replayed batch is stored twice.
• Name your store. Whenever a commerce store (Shopify, WooCommerce, Gomag, MerchantPro) is connected to the account, even a single one, a request without storeUrl (store_url on the v1 API) is answered 409 store_ambiguous rather than filed under a guess — double-counted revenue is worse than a loud failure. Always sending it is safest.

Orders API v1

The versioned way to report orders from a custom store or any platform Aopy has no plugin for. Three calls, all authenticated with the secret rk_ key, all idempotent, all in integer minor units (cents). The older POST /api/track/order-confirm above stays supported and keeps its major-unit amounts. Machine-readable contract: /api/track/openapi.json.

Rules that decide everything

• Money is integer minor units. Send 4999 for 49.99 EUR, never 49.99. This is the opposite of /api/track/order-confirm, which takes major units. Only currencies with a 2-decimal minor unit are accepted (EUR, RON, USD, GBP); JPY, KRW, HUF, BHD, KWD are refused with a 400.
• Every call needs an Idempotency-Key header. 1-200 characters from A-Z a-z 0-9 _ -, unique per logical request, identical on every retry of it. The same key with the same body replays the first response (status and body) with the header Idempotency-Replayed: true, for 24 hours. The same key with a different body, method or path is a 409 idempotency_key_reused. A 409 idempotency_in_progress means the first attempt is still running: retry shortly. 5xx answers, 404 order_not_found and 409 store_ambiguous are not remembered, so you can fix the cause and retry under the same key.
• Unknown fields are a 400. Every body is strict: a misspelled or unsupported field fails with validation_failed and the offending names in details. It is never silently ignored.
• Status changes. POST /api/v1/orders carries the whole order and is an upsert on external_id. To move an order from pending to paid, POST it again with the same external_id, status paid and a newer updated_at. PATCH only accepts cancelled, fulfilled or delivered. An older updated_at than the stored one is accepted but changes nothing.
• Refunds need an existing order. POST /api/v1/orders/{externalId}/refunds finds the order and its buyer by externalId, so create the order first (404 order_not_found otherwise). The store is NOT read from the stored order: send store_url on PATCH and refunds too, exactly as on the POST, or a connected commerce store makes the call a 409 store_ambiguous.
• Body size. 256 KB for POST /api/v1/orders, 16 KB for PATCH and refunds. Over the limit is a 413.

curl -X POST https://app.aopy.com/api/v1/orders \
  -H "Authorization: Bearer rk_YOUR_SECRET_KEY" \
  -H "Idempotency-Key: order-1042-paid" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1042",
    "status": "paid",
    "placed_at": "2026-10-13T09:15:00+03:00",
    "updated_at": "2026-10-13T09:16:30+03:00",
    "currency": "EUR",
    "total_minor": 4999,
    "tax_minor": 867,
    "shipping_minor": 0,
    "payment_method": "card",
    "customer_email": "buyer@example.com",
    "customer_first_name": "Ana",
    "line_items": [
      {
        "product_id": "SKU-12",
        "name": "Wireless Headphones",
        "quantity": 1,
        "unit_price_minor": 4999
      }
    ],
    "store_url": "https://shop.example.com",
    "aid": "srv_7f3c1a9e2b4d8c60",
    "consent": "granted"
  }'

curl -X PATCH https://app.aopy.com/api/v1/orders/1042 \
  -H "Authorization: Bearer rk_YOUR_SECRET_KEY" \
  -H "Idempotency-Key: order-1042-fulfilled" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "fulfilled",
    "occurred_at": "2026-10-14T11:00:00+03:00"
  }'

curl -X POST https://app.aopy.com/api/v1/orders/1042/refunds \
  -H "Authorization: Bearer rk_YOUR_SECRET_KEY" \
  -H "Idempotency-Key: order-1042-refund-rf-9" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_id": "rf-9",
    "refunded_minor": 1250,
    "remaining_minor": 3749,
    "refunded_at": "2026-10-20T10:00:00+03:00"
  }'

Read your configuration

GET /api/track/config

With the REST key this returns your organization's consent mode, retention window, rail: "server" and consentFieldRequired: true. The response is never cached. Called with only the public tk query parameter it fails closed to strict defaults and is deliberately indistinguishable from a genuinely-strict organization — it is not a key oracle.

curl https://app.aopy.com/api/track/config \
  -H "Authorization: Bearer rk_YOUR_SECRET_KEY"

What to do with every response

Rate limits

• 1000 events per minute per credential. The REST key's SHA-256 hash is the bucket — the plaintext secret never becomes a Redis key.
• 100 events per minute per (organization, visitor id) — one visitor cannot exhaust a merchant's budget.
• Both are charged per EVENT in the batch, not per HTTP request.