Skip to content

Keep orders in sync

Keep a copy of your orders current with webhooks, a daily check and a weekly copy.

Updated

To keep your orders in your own database, let webhooks tell you when an order changes, and read your orders back on a schedule for anything a webhook doesn’t bring. The receive webhooks guide builds a Cloudflare Worker that does both; this guide explains what it does and why, so you can do the same anywhere.

The one rule: read, then write, one order at a time

Deliveries may repeat, arrive in any order and run at once, and an event’s data is the order as it stood when its delivery was first built; created_at is only to the second. So no timestamp can tell which of two copies is newer. Instead, every copy of an order comes from the API: an event, or a scheduled pass, asks for an order to be refreshed, and one place per order reads it from GET /orders/{order} and writes the answer, one refresh after another. The newest read then writes last (the weekly copy repairs the rare exception, such as a write that lands late while the Worker is being updated). In the Worker, that place is a Durable Object per order, reached through refreshOrder(env, id); never read and write an order around it.

The Worker’s token needs transaction:read to read orders and revenue:read to see their amounts (without it they come back null; see scopes). The token that creates the webhook endpoint needs organization:write and the order events’ read scopes, customer:read, transaction:read, product:read and revenue:read, plus organization:read to list its deliveries.

1. Listen first

Create a webhook endpoint for order.created and order.refunded before anything else, so a change that happens while the first copy runs still reaches you. order.created is sent for each new order, and order.refunded for every refund, a dispute’s too:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/webhooks' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/sherpo/webhooks",
  "events": [
    "order.created",
    "order.refunded"
  ],
  "description": "Order sync"
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/webhooks', {
  body: {
    "url": "https://example.com/sherpo/webhooks",
    "events": [
      "order.created",
      "order.refunded"
    ],
    "description": "Order sync"
  },
});

Answers 201, abridged:

{
  "webhook": {
    "id": "c4b3a291-8f7e-4d6c-8b5a-49382716a5b4",
    "url": "https://example.com/sherpo/webhooks",
    "description": "Order sync",
    "events": [
      "order.created",
      "order.refunded"
    ],
    "enabled": true,
    "connection_ended_at": null,
    "created_at": "2026-11-03T10:00:00.000Z",
    "updated_at": "2026-11-03T10:00:00.000Z"
  },
  "secret": "whsec_3Jx9b2kQ7mVt4ZpR8nYc1LwE6aHs0DfG"
}

2. Copy what exists

Page through GET /orders oldest first, and refresh each order it lists. Here with the daily check’s filter on occurred_at; a copy of every order leaves it out:

curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/orders?filter[occurred_at][gte]=2026-11-01T00%3A00%3A00Z&sort=occurred&direction=asc&limit=100' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/orders', {
  query: [
    ['filter[occurred_at][gte]', '2026-11-01T00:00:00Z'],
    ['sort', 'occurred'],
    ['direction', 'asc'],
    ['limit', '100'],
  ],
});

Answers 200, abridged:

{
  "items": [
    {
      "id": "9a8b7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b",
      "number": 1042,
      "customer": {
        "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "phone": null,
        "erased": false
      },
      "currency": "eur",
      "exponent": 2,
      "amount": 4900,
      "discount": 0,
      "total": 4900,
      "source": "checkout",
      "occurred_at": "2026-11-02T16:21:09.000Z"
    }
  ],
  "cursor": null
}

The Worker does this on a schedule, a batch at a time, and its first run starts a copy of every order:

  • A run is bounded. It refreshes at most a few hundred orders and stops taking more after a few minutes, well within a scheduled run’s time; the next run, ten minutes later, goes on.
  • A run keeps its place after every order, the page’s cursor and the last order it refreshed, so a copy that stops (a deploy, a failure, the time running out) goes on from the next order.
  • One run works a copy at a time. A run takes a copy only while no other run holds it, so runs that overlap never do the same work, and the last days’ copy goes before the copy of everything.
  • A failure shows. A copy whose refresh fails keeps its place and its error in its row, and the run fails with the reason, so it shows among the Worker’s cron events (and in wrangler tail). The copy waits on that order until its cause is fixed (a token without revenue:read, say), and a new copy of the same kind doesn’t start meanwhile; delete its row in order_copies to drop it.
  • A copy still running goes on. When the next copy of its kind is due, the running one keeps going instead, so on a store too large to copy in a week, the copy of everything simply runs on.

Each refresh is one call, and the token’s calls are metered (see rate limits), so keep a batch within what the token may call in the minutes a run takes, and within the database’s queries a run may make, about one per order. A scheduled run waits out a 429’s Retry-After of up to a minute; a delivery’s refresh doesn’t wait (unless it queues behind a scheduled refresh of the same order), and a delivery refused for the limit, or timed out, is delivered again. The Worker needs the Workers Paid plan, whose limits let a scheduled run make the hundreds of calls a batch takes.

3. Check regularly

A delivery your endpoint never accepted fails after 8 attempts over about 45 hours, orders have no “updated since” filter, and some changes send no event: a refund a payment processor fails is taken back, lowering refunded with nothing delivered. So the Worker also:

  • Daily copies the orders of the last three days, a window wider than the retries, which brings what a failed delivery missed.
  • Weekly copies every order: an order recorded with an older occurred_at than the window, a refund on an older order whose delivery failed, or a refund taken back on an older order, only shows there.

Failed deliveries are listed by GET /webhook_deliveries and can be resent. An order’s lines, settlements, refunds and affiliates come with it, each capped with its total; GET /orders/{order}/items and its siblings page the rest of one.

Recording orders from elsewhere

Sales made outside Sherpo can be recorded too, with POST /orders. It names the buyer by id, or by email: someone who isn’t a customer yet becomes one, invited, and finds the order and what it gave them when they first sign in with that address. Its statements.customer_status is verified for a customer who proved their address, and anon for one invited this way. Recording moves no money: nothing is charged, and a refund you record later returns nothing. Its source_key, your own id for the sale, records it once however often you send it. A search on GET /orders finds it again by that key, even one made only of digits; follow its cursor until it is null, as pagination explains for a search.

Type to search…

↑↓ navigate↵ selectEsc close