REST API and Node SDK

To answer "where is my order?" or "is this in stock?", the AI needs your order, product and shipment data. A custom-built store sends that data to purser through the REST API: push whenever something changes in your system, and use the bulk endpoints to bring in your history when you first connect.

BasicsCopy Anchor Link

The reference page and the OpenAPI document are generated from the API's own definitions; where they differ from this page, they are right.

Two kinds of keyCopy Anchor Link

• Only owners and admins can create secret keys. The key is shown once; purser only stores its hash, so copy it into your server's environment right away.
• Each key belongs to one workspace. You do not (and cannot) pass a workspace ID: the key alone decides which workspace the data goes to.
• Older keys in the sk_live_… and pk_sand_… format keep working.
• Setup (接入) → "3. Push order data" lists all of the workspace's keys (owners and admins only). When a key leaks or is no longer used, click Revoke (撤销): it stops working at once, every request with it gets 401, and it cannot be restored. The publishable key in your chat-window embed code is marked "in use by the window" (窗口在用) and cannot be revoked.
• The identity secret used for signed-in customers is a different thing; see Identity tokens.

Check that a key works:

curl https://askpurser.com/api/v1/ping \
  -H "Authorization: Bearer $PURSER_SECRET_KEY"
# {"orgId":"…"}  the workspace this key belongs to

Data endpointsCopy Anchor Link

There is also POST /widget/sessions, called with the publishable key (header x-purser-key). The chat widget uses it to start a session; you normally never call it.

Upsert rulesCopy Anchor Link

• The request body is { "data": [ … ] }.
• Objects are upserted by id, which is your system's ID: created if new, updated otherwise.
• updatedAt is required: when your system last changed the object. A write that is not newer than the stored copy is ignored and reported as stale, so pushes arriving out of order never overwrite new data with old.
• Timestamps are ISO-8601 strings with a time zone (such as 2026-09-26T08:00:00Z) or epoch milliseconds.
• Amounts are integers in minor units: 1999 means $19.99, and for yen 1999 means ¥1999. Currencies are ISO 4217 codes in capitals, such as USD and JPY.
• Every object can carry custom: your own fields, stored as they are and not shown to the AI by default.
• A customer's tags replace only the tags the API set before; tags your agents added in the console are kept. Leave tags out to change nothing; [] removes the API's tags.
• A customer can carry totalSpent + totalSpentCurrency and ordersCount (lifetime spend and order count as your system knows them). Customer segments use them first; without them, purser counts the orders it has received.

Order statuses: pending, processing, partially_shipped, shipped, delivered, cancelled, refunded, returned.

Shipment statuses: label_created, in_transit, out_for_delivery, delivered, delayed, exception, lost, returned_to_sender.

Every field is listed in the API reference.

Example: push one orderCopy Anchor Link

curl -X POST https://askpurser.com/api/v1/orders \
  -H "Authorization: Bearer $PURSER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":[{
    "id": "ord_2001",
    "updatedAt": "2026-09-26T08:00:00Z",
    "number": "2001",
    "customerId": "cus_mia",
    "email": "mia@example.com",
    "status": "processing",
    "currency": "USD",
    "total": 1599,
    "placedAt": "2026-09-25T10:12:00Z",
    "items": [{ "id": "li_1", "title": "Canvas tote", "quantity": 1, "unitPrice": 1599 }]
  }]}'

{ "results": [{ "id": "ord_2001", "status": "created" }] }

Each object's result is one of created, updated or stale.

The order's customerId must match the sub in the identity token; that is how the AI finds a signed-in customer's orders when they ask in the chat.

Idempotency keysCopy Anchor Link

The write endpoints accept an Idempotency-Key header, with the same rules as Stripe:

• same key, same body, again within 24 hours: you get the first response back and nothing is processed twice;
• same key, different body: 409 (CONFLICT), which usually means a bug in your code.

Send the same key when you retry after a network timeout and you never write twice.

Bulk upserts and history importsCopy Anchor Link

The synchronous endpoints take at most 25 objects per call. For more, use the /bulk endpoints: up to 1,000 objects per call, validated immediately and processed in the background. They answer 202 with { "batchId": "…" } right away; follow progress with GET /batches/{id} (pending, processing, done, failed). The upsert rules are the same as for the synchronous endpoints.

To import hundreds of thousands of past orders, group many batches into one history import (backfill) with a single progress number:

1. POST /backfills (optionally with { "label": "…" }) returns an id;
2. send each /bulk request with "backfillId": "<id>";
3. when you have sent everything, POST /backfills/{id}/close;
4. follow GET /backfills/{id}; it becomes done once every object received has been processed.

ErrorsCopy Anchor Link

Every non-2xx response has this body:

{ "code": "CONFLICT", "status": 409, "message": "…", "data": { } }

Rate limitsCopy Anchor Link

Per minute; over the limit you get 429 with Retry-After: 60:

For large amounts of history use /bulk and history imports (above) rather than looping one object at a time. The Node SDK backs off and retries on 429 by itself.

Node SDK: @purser-ai/nodeCopy Anchor Link

Zero dependencies, Node 20 or later (it also runs on Bun, Deno and Cloudflare Workers: it only uses fetch and WebCrypto). Request and response types are generated from the API's OpenAPI document.

import { Purser, signIdentityToken } from "@purser-ai/node";

const purser = new Purser({ secretKey: process.env.PURSER_SECRET_KEY });

await purser.ping(); // { orgId }

await purser.orders.upsert({
  id: "ord_2001", updatedAt: Date.now(), number: "2001", customerId: "cus_mia",
  status: "shipped", currency: "USD", total: 1599, placedAt: Date.now(),
});

// History: an array or any (async) iterable, so a paginated export streams straight through
const result = await purser.backfill("orders", fetchAllOrders(), { onProgress: console.log });

What the SDK does for you:

• Coalescing: single-object upsert calls for the same resource within 20 ms share one request (each call still gets its own result), which suits a burst of webhooks;
• Batching: arrays are split into requests of 25 objects (50 for tickets);
• Idempotency: every write carries an Idempotency-Key; if you pass idempotencyKey, each split batch uses <your key>:<offset>;
• Retries: network errors, 429 and 5xx are retried with jittered backoff, at most 4 attempts in total; other 4xx errors are thrown at once;
• History imports: backfill sends batches of 1,000 through /bulk, closes the backfill when the source is exhausted, then polls until it is done (or a batch has failed) and returns the final progress;
• Errors: it throws PurserError with status, code and the API's body.