Orders

Orders

The order is the core resource in Shippified. Each order is one purchase. It can be built from several messages: a Discord checkout embed, an order-confirmation email, a shipping email, and carrier tracking lookups can all contribute to the same record.

Endpoints

All order endpoints require authentication and only see orders that belong to the authenticated account. Request bodies larger than 2 MiB are rejected with 413.

The order object

{
  "id": "ord_mpvu9uim_aeh5t",
  "userId": "usr_4f1c2a9b7e0d3c11",
  "source": "email",
  "sources": ["discord", "email"],
  "botId": "bot_m1x2y3z4",
  "botName": "Checkout monitor",
  "emailSourceId": "email_m1x2y3z5",
  "templateId": "hayha",
  "templateName": "Hayha",
  "eventType": "order_shipped",
  "parser": "shape:walmart-order_shipped",
  "store": "walmart",
  "storeLabel": "Walmart",
  "orderNumber": "2000123-45678",
  "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 of the response entirely. They are never sent as null.

Identity and provenance

Lifecycle

Item and store

Money

Shipping and carrier

Status

status is always derived from real signals. It cannot be set through the API.

Status only moves forward. When messages merge, the order keeps the highest-ranked status:

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

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

How the status is derived from a message, first match 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

Event type

List orders

GET /api/orders

Returns orders newest first by receivedAt, in the standard 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"

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

Get an order

GET /api/orders/:id

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

Returns the order object itself, with no wrapper. Returns 404 {"error": "Order not found"} if the order doesn't exist or belongs to another account.

Create an order

POST /api/orders

Creates an order by hand, for purchases that no connected bot or inbox will report. The request goes through the same ingest path as parsed messages. If orderNumber matches an existing order, the request merges into that order instead of creating a new one.

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
  }'

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",
    "…": "…"
  },
  "merged": false
}

merged: true means an order with the same orderNumber already existed and your request was folded into it. The response status is still 201, and order is the merged record, which keeps the existing order's id. In a merge, existing non-empty values win. The new request only fills fields that were empty, and status never moves backward.

Creating an order fires order.created, or order.merged for a merge. It also fires order.shipped / order.delivered when the eventType implies that transition. See Webhooks.

Update an order

PATCH /api/orders/:id

Updates follow a fill-missing-only model. You can fill fields that are empty, but you can't overwrite a value the parser or a carrier already set. This keeps order data traceable to real messages. Fields not listed below are ignored.

A value counts as empty if it is missing, null, or an empty string. Values that don't meet a rule are skipped silently. The request still returns 200.

Every field the request actually writes (except the derived status) is added to the order's userEdited list, so re-parsing and mailbox rebuilds keep your values.

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

The response is the updated order object with no wrapper. To see whether a field was written, compare the returned values with what you sent.

To clear a sale price:

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": null}'

Sending "" for salePriceCents has no effect.

Events:

• A PATCH that writes at least one field fires order.updated with { order, patch }, where patch lists the fields that were applied (a cleared sale price appears as "salePriceCents": null).

• A PATCH that adds a tracking number to an ordered order also fires order.shipped.

• A PATCH that changes nothing writes nothing, fires no event, and returns the order unchanged with 200.

Delete an order

DELETE /api/orders/:id

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

Returns 200 {"ok": true} or 404. Deletion is permanent and fires no webhook event. The order disappears from analytics. Share cards already created keep their frozen snapshot. The dashboard offers the same action as Delete order in every order's drawer.

Important: If a stored source message is ingested again later, for example during a mailbox rebuild, the order can reappear.

Re-parse orders

POST /api/orders/reparse

Rebuilds every order that has stored source 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.

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

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

What re-parsing keeps from the old record:

• id, userId, the earliest receivedAt, the union of sources, intakeIds, and userEdited.

• Carrier and user fields: salePriceCents, estimatedDelivery, actualDelivery, shippingAddress, billingAddress, weightGrams, dimensionsCm, signedBy, serviceLevel, rawCarrierResponse.

• Every field listed in userEdited.

• A carrier-confirmed delivery: an order with actualDelivery stays delivered.

Everything else is rebuilt from the messages. An order is only removed if it has no salePriceCents and no userEdited entries. Emails you imported by hand with POST /api/email/import are never dropped as non-order mail. Re-parsing fires no webhook events.

Note: The request runs synchronously and can take a while on large workspaces. Use a generous client timeout.

Tracking

For how carriers are detected and which ones are supported, see the tracking guide.

Get tracking

GET /api/orders/:id/tracking

Returns cached results when they are fresh: 5 minutes for packages in transit, 24 hours once delivered. Otherwise it runs a live carrier lookup.

Live lookups are only made for carriers that have live tracking enabled on the server. On shippified.net that is currently DHL and DHL Express. UPS and FedEx numbers are detected and labelled, but return the "live unavailable" response described below, as do USPS and unrecognised numbers. Call GET /api/carrier-status to see what's live instead of hard-coding it.

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

{
  "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"
}

{
  "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 shippingAddress, weightGrams, dimensionsCm, signedBy, serviceLevel and rawCarrierResponse when the carrier returns them. Fields the carrier didn't return are never wiped.

• It sets estimatedDelivery from the carrier's estimate while the package is in transit.

• It moves ordered to shipped once the carrier has scan events.

• When the carrier reports delivery, it sets actualDelivery and moves ordered or shipped to delivered.

• canceled and issue orders keep their status.

Every carrier response fires tracking.refreshed. order.shipped and order.delivered fire only on a real status transition.

Force refresh

POST /api/orders/:id/tracking/refresh has the same response, but always does a live lookup.

Bulk sync

POST /api/orders/sync-tracking refreshes up to 50 orders with status ordered or shipped that have a tracking number on a carrier with live tracking, bypassing the cache. Orders on USPS, unrecognised carriers, or carriers without live tracking are skipped rather than counted as failures.

{ "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 to keep orders current. Every 5 minutes the server plans a bounded batch of carrier lookups across all workspaces and applies each result to the orders exactly as the endpoints above do, so status, estimatedDelivery, actualDelivery and the tracking.refreshed / order.shipped / order.delivered events all move without any client involvement.

Because the DHL budget is shared across all workspaces, packages may be checked less often than the cadence above when many are in flight. If you need a fresh answer, call POST /api/orders/:id/tracking/refresh. Subscribe to webhooks rather than polling for changes.

Carrier status

GET /api/carrier-status lists every carrier Shippified recognises and whether live tracking is enabled on this server.

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

configured: true means live lookups, background refresh and sync-tracking apply to that carrier. envVars names the server settings a self-hosted instance needs to enable it; there is nothing to configure on your account.

Related

• Order lifecycle guide

• Profitability guide: how costCents and salePriceCents are used.

• Webhooks: get notified instead of polling.