---
title: "Keep orders in sync"
description: "Keep a copy of your orders current with webhooks, a daily check and a weekly copy."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep orders in sync

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](/merchant-api/guides/receive-webhooks) 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 <a href="/merchant-api/reference/get-order/">`GET /orders/{order}`</a> 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](/merchant-api/scopes#scopes-that-change-what-you-see)). 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:

```bash
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"
}'
```

```js
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:

```json
{
  "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 <a href="/merchant-api/reference/list-orders/">`GET /orders`</a> 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:

```bash
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"
```

```js
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:

```json
{
  "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](/merchant-api/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 <a href="/merchant-api/reference/list-webhook-deliveries/">`GET /webhook_deliveries`</a> and can be [resent](/merchant-api/webhooks#deliveries-and-resends). An order's `lines`, `settlements`, `refunds` and `affiliates` come with it, each capped with its `total`; <a href="/merchant-api/reference/list-order-items/">`GET /orders/{order}/items`</a> and its siblings page the rest of one.

## Recording orders from elsewhere

Sales made outside Sherpo can be recorded too, with <a href="/merchant-api/reference/record-order/">`POST /orders`</a>. 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 <a href="/merchant-api/reference/list-orders/">`GET /orders`</a> finds it again by that key, even one made only of digits; follow its `cursor` until it is `null`, as [pagination](/merchant-api/pagination) explains for a search.

Source: https://docs.sherpo.io/merchant-api/guides/sync-orders/index.mdx
