Orders API

The Orders API allows you to search orders, retrieve a specific order, or update order information.

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.
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 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).
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.

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 the status of a specific order. Use this endpoint to set tracking information, change status, or attach metadata.

⚠️ 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 Yes 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.
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": "Delivered"}'

Example response 

{
  "token": "c7af6278-1c06-411d-b009-22a839efda75",
  "status": "Delivered",
  "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 }
  ],
  ...
}

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. (JSON key is daysUntilExpire. The backing property name contains a typo intentionally, but the API output uses the correct spelling.)
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?