Docs

Reconcile with metadata

Carry your own order IDs, customer refs, and SKU data through the webhook round-trip using the metadata field.

Every invoice carries two merchant-owned fields echoed back in every webhook:

  • external_id — short, unique, used for idempotency.
  • metadata — arbitrary JSON for anything else you want to reconcile.

Using them well turns the webhook into a self-contained reconciliation event — no second lookup needed.

What to put in metadata#

Anything your system needs to match the webhook to its own record:

{
  "order_id": "1234",
  "customer_id": "cust_42",
  "sku": "ABC",
  "campaign": "spring-sale-2026",
  "fulfilment_warehouse": "ams-1"
}

Do not put:

  • Secrets.
  • Personally identifying information you would not want in a webhook.
  • Large blobs — the store is not a dumping ground; payloads balloon delivery time.

Typical reconciliation flow#

  1. On POST /api/invoices: include external_id (your order ID) and metadata (everything else).
  2. On webhook arrival: verify signature.
  3. Read external_id or metadata.order_id to look up your record.
  4. Decide what to do based on status + the amounts in the payload.

Why echo them in every event#

Without the echo, every webhook would force a second API call to join the event back to your own record. With the echo, the webhook is a complete event.

Historic invoices created before this feature shipped still carry their original (thinner) payload — the platform does not retro-enrich. Only new invoices going forward get the full echo.

See also#