Orders API

The Orders API allows you to search orders, retrieve a specific order, update order information, and update many orders' statuses at once.

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details.

GET /orders

Retrieve all completed orders.

Resource URL

GET https://app.snipcart.com/api/orders

Headers

Name Value Required Description
Accept application/json Yes Must always be set. The API only supports JSON.

Query Parameters

Name Required Type Description
offset No int Number of results to skip. Default: 0.
limit No int Number of results to fetch. Default: 20.
status No string Filter orders by status. Values: InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled.
paymentStatus No string Filter by payment status. Values: Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Failed, Pending, Expired, Cancelled, Open, Authorized.
format No string Level of detail for list items. Full (default) returns complete orders; Excerpt returns lighter order summaries.
hasPendingWithdrawal No bool Filter orders that have a pending withdrawal request.
campaignId No guid Return only orders recovered from this abandoned-cart recovery campaign.
invoiceNumber No string Filter by invoice number.
productId No string Returns orders containing this product. Must be the user-defined ID, not Snipcart's internal ID.
placedBy No string Name or email of the purchaser.
from No datetime Return orders placed after this date.
to No datetime Return orders placed before this date.
isRecurringOrder No bool Filter by recurring orders (true/false).
includeTestOrders No bool When the request is made in Live mode, set to true to also return Test-mode orders.
billingAddressCity No string Exact match on billing city.
billingAddressCountry No string Exact match, 2-letter country code.
billingAddressProvince No string Exact match on billing province/state.
billingAddressPostalCode No string Exact match on billing postal/ZIP code.
shippingAddressCity No string Exact match on shipping city.
shippingAddressCountry No string Exact match, 2-letter country code.
shippingAddressProvince No string Exact match on shipping province/state.
shippingAddressPostalCode No string Exact match on shipping postal/ZIP code.

Example request 

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/orders?offset=0&limit=50&status=Processed" \
  -u {API_KEY}:

Example response 

{
  "totalItems": 10,
  "offset": 0,
  "limit": 50,
  "items": [
    {
      "token": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70",
      "creationDate": "2013-10-21T20:36:26.46Z",
      "status": "Processed",
      "paymentMethod": "CreditCard",
      "invoiceNumber": "SNIP-0001",
      "email": "geeks@snipcart.com",
      ...
    }
  ]
}

GET /orders/{token}

Retrieve a single order, including all items, promo codes, and applied taxes.

Resource URL

GET https://app.snipcart.com/api/orders/{token}

Headers

Name Value Required Description
Accept application/json Yes Must always be set.

Path Parameters

Name Required Type Description
token Yes guid The unique order token.

Query Parameters

Name Required Type Description
includeTestOrders No bool When the request is made in Live mode, set to true to fetch a Test-mode order.

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/orders/{token} \
  -u {API_KEY}:

Example response 

{
  "token": "93c4604e-35ac-4db7-b3f1-2871476e9e6a",
  "status": "Processed",
  "invoiceNumber": "SNIP-1427",
  "items": [
    {
      "id": "1",
      "name": "Un poster",
      "price": 300,
      "quantity": 1,
      ...
    }
  ],
  "taxes": [
    { "taxName": "TPS", "taxRate": 0.05, "amount": 12.5 },
    { "taxName": "TVQ", "taxRate": 0.09975, "amount": 24.94 }
  ],
  ...
}

PUT /orders/{token}

Update a specific order. Use this endpoint to change status, set tracking information, edit addresses, or attach metadata. Only the fields you include in the body are modified; everything else is left untouched.

⚠️ Important: Changing an order's status from Pending → Processed and payment status from Authorized → Paid will capture the payment (only applies to two-step Stripe payments).

Resource URL

PUT https://app.snipcart.com/api/orders/{token}

Headers

Name Value Required Description
Accept application/json Yes Must always be set.
Content-Type application/json Yes JSON only. Other content types (e.g., XML) are not supported.

Path Parameters

Name Required Type Description
token Yes guid The unique order token.

Body Parameters

Name Required Type Description
status No string New order status. Values: InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled.
paymentStatus No string Payment status. Values: Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Failed, Pending, Expired, Cancelled, Open, Authorized.
trackingNumber No string Tracking number for the order.
trackingUrl No string Tracking URL for the customer.
email No string Customer email address on the order.
billingAddress No object Billing address. Must contain at least the minimal required fields (name, address, city, country, postal code) or it is ignored.
shippingAddress No object Shipping address. Same minimal-required-fields rule as billingAddress.
notes No string Internal notes attached to the order.
customFields No array Order custom fields, each an object with name and value.
metadata No object Arbitrary JSON object with custom metadata. Example: { "internal_id": "12345", "external_user_id": "user_1" }.

Example request 

curl -X PUT https://app.snipcart.com/api/orders/{token} \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '{"status": "Shipped", "trackingNumber": "1Z999", "trackingUrl": "https://track.example.com/1Z999"}'

Example response 

{
  "token": "c7af6278-1c06-411d-b009-22a839efda75",
  "status": "Shipped",
  "invoiceNumber": "SNIP-1427",
  "trackingNumber": "1Z999",
  "trackingUrl": "https://track.example.com/1Z999",
  "items": [
    {
      "id": "1",
      "name": "Un poster",
      "price": 300,
      "quantity": 1
    }
  ],
  "taxes": [
    { "taxName": "TPS", "taxRate": 0.05, "amount": 12.5 },
    { "taxName": "TVQ", "taxRate": 0.09975, "amount": 24.94 }
  ],
  "hasPendingWithdrawal": true,
  "withdrawals": [
    {
      "id": "5b8c9d10-7e2f-4a8b-9c2d-1e3f4a5b6c7d",
      "orderToken": "c7af6278-1c06-411d-b009-22a839efda75",
      "orderInvoiceNumber": "SNIP-1427",
      "customerName": "Marie Dubois",
      "requestedAt": "2026-05-07T14:32:11Z",
      "isPartial": true,
      "isOutsideWithdrawalPeriod": false,
      "refundAmount": 300,
      "resolution": "Pending",
      "confirmationNumber": "WD-20260507-5B8C9D10",
      "items": [
        {
          "itemUniqueId": "1",
          "itemName": "Un poster",
          "quantity": 1,
          "unitPrice": 300,
          "totalPrice": 300
        }
      ]
    }
  ],
  ...
}

PATCH /orders

Update the status of several orders at once. Send an array of { id, status } objects, where id is the order token. Each status change emits the same events and notifications as a single update.

Resource URL

PATCH https://app.snipcart.com/api/orders

Headers

Name Value Required Description
Accept application/json Yes Must always be set.
Content-Type application/json Yes JSON only.

Body Parameters

A JSON array, where each element is:

Name Required Type Description
id Yes guid The order token to update.
status Yes string New status. Values: InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled.

Query Parameters

Name Required Type Description
includeTestOrders No bool In Live mode, set to true to also include Test-mode orders in the batch.

Example request 

curl -X PATCH https://app.snipcart.com/api/orders \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '[{"id": "c7af6278-1c06-411d-b009-22a839efda75", "status": "Shipped"}, {"id": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70", "status": "Delivered"}]'

Example response 

[
  { "id": "c7af6278-1c06-411d-b009-22a839efda75", "status": "Shipped" },
  { "id": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70", "status": "Delivered" }
]

GET /orders/{token}/digital

Return the list of digital goods attached to an order.

Resource URL

GET https://app.snipcart.com/api/orders/{token}/digital

Headers

Name Value Required Description
Accept application/json Yes Must always be set.

Path Parameters

Name Required Type Description
token Yes guid The unique order token.

Response

An array of CustomerOrderDigitalGoodDto objects:

Field Type Description
fileGuid string Unique identifier of the digital file.
name string Display name of the digital good.
url string Download URL for the file.
downloadedNbrTime int Number of times the item has been downloaded.
maxNbrDownload int? Maximum allowed downloads; null means unlimited.
daysUntilExpire int? Number of days the download link remains valid after creationDate; null means it does not expire.
creationDate datetime UTC date the digital good was created/issued.
isValid bool true if both conditions are met: downloads have not reached maxNbrDownload (or unlimited), and the item is not expired based on daysUntilExpire and creationDate.

Validity logic (for reference):

isValid =
  (maxNbrDownload == null || downloadedNbrTime < maxNbrDownload) &&
  (daysUntilExpire == null || (nowUtc - creationDate).TotalDays <= daysUntilExpire)

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/orders/{token}/digital \
  -u {API_KEY}:

Example response 

[
  {
    "fileGuid": "7e3f0c7a-2b4e-4db8-9b0a-0f9a8b2b8c11",
    "name": "Album – FLAC",
    "url": "https://cdn.example.com/dl/7e3f0c7a-2b4e-4db8-9b0a-0f9a8b2b8c11",
    "downloadedNbrTime": 1,
    "maxNbrDownload": 5,
    "daysUntilExpire": 30,
    "creationDate": "2025-09-01T12:34:56Z",
    "isValid": true
  },
  {
    "fileGuid": "a1b2c3d4-e5f6-47a8-9abc-def012345678",
    "name": "E-book (PDF)",
    "url": "https://cdn.example.com/dl/a1b2c3d4-e5f6-47a8-9abc-def012345678",
    "downloadedNbrTime": 3,
    "maxNbrDownload": 3,
    "daysUntilExpire": null,
    "creationDate": "2024-10-22T08:10:00Z",
    "isValid": false
  }
]

Was this article helpful?