📦Orders

An order is one purchase. It is usually built from several messages: a Discord checkout post, an order-confirmation email, a shipping email and carrier tracking lookups can all add to the same record. The order number ties them together: a message whose order number matches an existing order is merged into it instead of creating a new one.

All order endpoints need a token and only see orders in the token's account. For the parameter-by-parameter spec see the Orders reference and Tracking reference.

Endpoints

The order object

{
  "id": "ord_mpvu9uim_aeh5t",
  "userId": "usr_4f1c2a9b7e0d3c11",
  "source": "email",
  "sources": ["discord", "email"],
  "botId": "bot_m1x2y3z4",
  "botName": "Hayha — Target",
  "emailSourceId": "email_m1x2y3z5",
  "templateId": "hayha",
  "templateName": "Hayha",
  "eventType": "order_shipped",
  "parser": "shape:target-order_shipped",
  "store": "target",
  "storeLabel": "Target",
  "orderNumber": "912004578812",
  "itemSummary": "Example Console Bundle",
  "imageUrl": "https://cdn.example.com/p/12345.png",
  "total": "$499.99",
  "price": "$499.99",
  "quantity": 1,
  "trackingNumber": "1Z999AA10123456784",
  "carrier": "UPS",
  "estimatedDelivery": "2026-09-27",
  "costCents": 49999,
  "salePriceCents": 62000,
  "status": "shipped",
  "receivedAt": "2026-09-22T18:04:51.000Z",
  "updatedAt": "2026-09-24T09:12:03.114Z",
  "rawText": "…",
  "intakeIds": ["webhook:m1x2y3z4ab12cd", "email:[email protected]"]
}

Fields with no value are left out, never sent as null.

Identity and where it came from

Lifecycle

Item and store

Money

Shipping and carrier

Status

status is always worked out from real signals. It can't be set through the API.

From a single message, the first matching rule wins:

1. eventType is order_delivered → delivered

2. eventType is order_shipped, or a tracking number is present → shipped

3. eventType is order_canceled → canceled

4. Store is unknown and item is "Unparsed order" → issue

5. Otherwise → ordered

Status only moves forward. When messages merge, the higher-ranked status wins:

issue (0) < ordered (1) < canceled (1.5) < shipped (2) < delivered (3)

So a partial-cancellation email can't move a shipped order back to canceled, and a late confirmation email can't move a delivered order back.

Event type

List orders

GET /api/orders returns orders newest first by receivedAt, in the pagination envelope.

curl -s "https://shippified.net/api/orders?status=shipped&hasTracking=true&from=2026-09-01&limit=100" \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const page = await shippified.orders.list({
  status: "shipped",
  hasTracking: true,
  from: "2026-09-01",
  limit: 100,
});

{
  "items": [ { "id": "ord_mpvu9uim_aeh5t", "status": "shipped", "…": "…" } ],
  "total": 37,
  "limit": 100,
  "offset": 0,
  "hasMore": false
}

Get an order

GET /api/orders/:id returns the order object with no wrapper, or 404 {"error": "Order not found"} if it doesn't exist or belongs to another account.

curl -s https://shippified.net/api/orders/ord_mpvu9uim_aeh5t \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const order = await shippified.orders.get("ord_mpvu9uim_aeh5t");

Create an order

POST /api/orders records a purchase that no bot or inbox will report. It goes through the same merge logic as parsed messages: if orderNumber matches an existing order, your request is merged into that order instead of creating a new one. This is what the dashboard's New order dialog calls.

curl -s -X POST https://shippified.net/api/orders \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "itemSummary": "Example Console Bundle",
    "store": "bestbuy",
    "orderNumber": "BBY01-000000000001",
    "trackingNumber": "1Z999AA10123456784",
    "costCents": 49999,
    "quantity": 1
  }'

const { order, merged } = await shippified.orders.create({
  itemSummary: "Example Console Bundle",
  store: "bestbuy",
  orderNumber: "BBY01-000000000001",
  trackingNumber: "1Z999AA10123456784",
  costCents: 49999,
  quantity: 1,
});

Response 201 Created:

{
  "order": {
    "id": "ord_mq1a2b3c_x9y8z",
    "source": "manual",
    "sources": ["manual"],
    "parser": "manual",
    "store": "bestbuy",
    "storeLabel": "Best Buy",
    "orderNumber": "BBY01-000000000001",
    "itemSummary": "Example Console Bundle",
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "UPS",
    "eventType": "order_shipped",
    "status": "shipped",
    "costCents": 49999,
    "quantity": 1,
    "receivedAt": "2026-09-24T15:20:00.000Z",
    "rawText": "Example Console Bundle"
  },
  "merged": false
}

merged: true means an order with that orderNumber already existed. The status is still 201, and order is the existing record (same id) after the merge. In a merge, existing non-empty values win: your request only fills empty fields, and status never moves back.

A create fires order.created (or order.merged), plus order.shipped or order.delivered when the eventType implies it. See Webhooks. It doesn't post a status card to the workspace's Discord updates webhook (the Shippified pings webhook); only orders arriving through intake and carrier tracking changes do.

Update an order

PATCH /api/orders/:id follows a fill-missing-only rule: you can fill fields that are empty, but you can't overwrite a value a message or carrier already set. This keeps order data traceable to real messages.

A value counts as empty when it's missing, null or "". Values that break a rule are skipped silently; the request still returns 200. The response is the order (no wrapper), so compare it with what you sent. Every field actually written is added to userEdited.

curl -s -X PATCH https://shippified.net/api/orders/ord_mpvu9uim_aeh5t \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"salePriceCents": 62000, "trackingNumber": "1Z999AA10123456784"}'

const updated = await shippified.orders.patch("ord_mpvu9uim_aeh5t", {
  salePriceCents: 62000,
  trackingNumber: "1Z999AA10123456784",
});

// Clear the sale price
await shippified.orders.patch("ord_mpvu9uim_aeh5t", { salePriceCents: null });

Events:

• A PATCH that writes at least one field fires order.updated with { order, patch }. A cleared sale price appears as "salePriceCents": null in patch.

• Adding a tracking number to an ordered order also fires order.shipped with source: "manual".

• A PATCH that changes nothing writes nothing, fires nothing, and returns the order unchanged.

Delete an order

DELETE /api/orders/:id returns 200 {"ok": true} or 404 {"error": "Order not found"}. Deletion is permanent and fires no webhook event. The order drops out of analytics; share cards already created keep their frozen snapshot. It's the same action as Delete order in the dashboard.

curl -s -X DELETE https://shippified.net/api/orders/ord_mpvu9uim_aeh5t \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

await shippified.orders.delete("ord_mpvu9uim_aeh5t");

Re-parse orders

POST /api/orders/reparse rebuilds every order that has stored messages, using the current built-in shapes and your current custom templates. Run it after you create or fix a custom template to apply the change to past orders. It waits until done and returns a summary.

curl -s -X POST https://shippified.net/api/orders/reparse \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const summary = await shippified.orders.reparse();

{ "reparsed": 412, "changed": 37, "merged": 3, "removed": 5, "skipped": 21 }

Kept from the old record: id, the earliest receivedAt, the union of sources, intakeIds, userEdited; the carrier and user fields (salePriceCents, estimatedDelivery, actualDelivery, addresses, weightGrams, dimensionsCm, signedBy, serviceLevel, rawCarrierResponse); every field in userEdited; and carrier-confirmed delivery (an order with actualDelivery stays delivered). Everything else is rebuilt. Emails you imported by hand are never dropped as non-order mail. Re-parsing fires no webhook events.

Tracking

For how carriers are detected, see the tracking guide.

Which carriers are live

Live lookups only run for carriers switched on for the server. Ask rather than hard-coding:

curl -s https://shippified.net/api/carrier-status \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const { carriers } = await shippified.orders.carrierStatus();

{
  "carriers": [
    { "key": "ups", "label": "UPS", "configured": false, "envVars": ["UPS_CLIENT_ID", "UPS_CLIENT_SECRET"] },
    { "key": "fedex", "label": "FedEx", "configured": false, "envVars": ["FEDEX_CLIENT_ID", "FEDEX_CLIENT_SECRET"] },
    { "key": "dhl", "label": "DHL", "configured": true, "envVars": ["DHL_API_KEY"] },
    { "key": "dhl-express", "label": "DHL Express", "configured": true, "envVars": ["DHL_API_KEY"] },
    { "key": "usps", "label": "USPS", "configured": false, "envVars": [], "note": "Free USPS tracking API is unavailable. Paid USPS Web Tools key required." }
  ]
}

The values above are an example; your answer reflects the server you call. configured: true means live lookups, the background tracker and sync-tracking cover that carrier. envVars names the server settings a self-hosted instance needs; there's nothing to set on your account. USPS never has live tracking.

Get tracking

GET /api/orders/:id/tracking answers from cache while it's fresh (5 minutes for packages in transit, 24 hours once delivered) and otherwise runs a live lookup. POST /api/orders/:id/tracking/refresh has the same response but always looks up live.

curl -s https://shippified.net/api/orders/ord_mpvu9uim_aeh5t/tracking \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

curl -s -X POST https://shippified.net/api/orders/ord_mpvu9uim_aeh5t/tracking/refresh \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const cached = await shippified.orders.getTracking("ord_mpvu9uim_aeh5t");
const live = await shippified.orders.refreshTracking("ord_mpvu9uim_aeh5t");

A live answer (example):

{
  "track": {
    "carrier": "dhl-express",
    "trackingNumber": "1234567890",
    "delivered": false,
    "events": [
      { "date": "2026-09-23T14:10:00Z", "location": "Louisville, KY", "description": "Departed facility", "status": "in_transit" }
    ]
  },
  "fetchedAt": "2026-09-24T15:21:09.002Z",
  "stale": false,
  "carrierKey": "dhl-express",
  "liveUnavailable": false,
  "credsRequired": false,
  "trackingNumber": "1234567890",
  "order": { "id": "ord_mpvu9uim_aeh5t", "status": "shipped", "…": "…" }
}

A carrier without live tracking on the server (here UPS):

{
  "error": "Live UPS tracking isn't enabled on this Shippified server — showing updates from your order emails.",
  "carrierKey": "ups",
  "liveUnavailable": true,
  "credsRequired": true,
  "trackingNumber": "1Z999AA10123456784"
}

A live lookup that returns data also updates the order: it fills the carrier fields it received (never wiping ones it didn't), sets estimatedDelivery from the carrier's estimate, moves ordered to shipped once there are scans, and on delivery sets actualDelivery and moves ordered or shipped to delivered. canceled and issue orders keep their status. Each live answer fires tracking.refreshed; order.shipped and order.delivered fire only on a real change. A real status change also posts a status card to the workspace's Discord updates webhook, if one is set and that event type is switched on.

Bulk sync

POST /api/orders/sync-tracking looks up, live, up to 50 orders with status ordered or shipped, a tracking number, and a carrier with live tracking. Other orders are skipped, not counted as failures.

curl -s -X POST https://shippified.net/api/orders/sync-tracking \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const { total, refreshed, failed, delivered } = await shippified.orders.syncTracking();

{ "total": 12, "refreshed": 11, "failed": 1, "delivered": 4 }

total: 0 means there was nothing to look up.

Background refresh

You don't need to poll. Every 5 minutes the server plans a batch of carrier lookups across all workspaces and applies each result exactly as the endpoints above do, events included.

Because the budget is shared, packages can be checked less often than the table says when many are in flight. Call the refresh endpoint when you need a fresh answer, and subscribe to webhooks instead of polling for changes.

Troubleshooting