API: orders

You can search your orders, fetch a specific one, or update order information through our API.

Get all orders
Get an order by token
Update an order

GET /orders

This method returns all orders that have been completed.

Resource URL

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

Headers

Name	Value	Required?	Description
`Accept`	`application/json`	Yes	Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name	Required?	Type	Description
`offset`	Yes	`int`	Number of results to skip. Default is 0.
`limit`	Yes	`int`	Number of results to fetch. Default is 20.
`status`	No	`string`	A status criteria for your order collection. Possible values: (`InProgress`, `Processed`, `Disputed`, `Shipped`, `Delivered`, `Pending`, `Cancelled`)
`invoiceNumber`	No	`string`	The invoice number of the order to retrieve.
`productId`	No	`string`	Returns only orders containing that product. **Note that this has to be the user defined ID, not the unique ID defined by Snipcart
`placedBy`	No	`string`	The name of the person who made the purchase.
`from`	No	`datetime`	Returns only the orders placed after this date.
`to`	No	`datetime`	Returns only the orders placed before this date.
`isRecurringOrder`	No	`bool`	returns only the orders that are recurring or not.
`billingAddressCity`	No	`string`	The billing address city. Exact match.
`billingAddressCountry`	No	`string`	The billing address country. Two letter code. Exact match.
`billingAddressProvince`	No	`string`	The billing address province or state. Exact match.
`billingAddressPostalCode`	No	`string`	The billing address zip or postal code. Exact match..
`shippingAddressCity`	No	`string`	The shipping address city. Exact match.
`shippingAddressCountry`	No	`string`	The shipping address country. Two letter code. Exact match.
`shippingAddressProvince`	No	`string`	The shipping address province or state. Exact match.
`shippingAddressPostalCode`	No	`string`	The shipping address zip or postal code. Exact match.

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",
            "modificationDate": "2013-10-21T20:36:26.46Z",
            "status": "Processed",
            "paymentMethod": "CreditCard",
            "invoiceNumber": "SNIP-0001",
            "email": "geeks@snipcart.com",
            "cardHolderName": "Geeks Snipcart",
            "creditCardLast4Digits": "4242",
            "billingAddressName": "Geeks Snipcart",
            "billingAddressCompanyName": "Snipcart",
            "billingAddressAddress1": "4885 1ere Avenue",
            "billingAddressAddress2": "",
            "billingAddressCity": "Québec",
            "billingAddressCountry": "CA",
            "billingAddressProvince": "QC",
            "billingAddressPostalCode": "G1H2T5",
            "billingAddressPhone": "1-877-301-4813",
            "notes": null,
            "shippingAddressName": "Geeks Snipcart",
            "shippingAddressCompanyName": "Snipcart",
            "shippingAddressAddress1": "4885 1ere Avenue",
            "shippingAddressAddress2": "",
            "shippingAddressCity": "Québec",
            "shippingAddressCountry": "CA",
            "shippingAddressProvince": "QC",
            "shippingAddressPostalCode": "G1H2T5",
            "shippingAddressPhone": "1-877-301-4813",
            "shippingAddressSameAsBilling": true,
            "finalGrandTotal": 443,
            "shippingFees": 0,
            "shippingMethod": "Free shipping",
            "items": [],
            "taxes": [],
            "promocodes": [],
            "willBePaidLater": false,
            "customFields": [],
            "paymentTransactionId": "gateway_payment_id",
        },
        ...
    ]
}

GET /orders/{token}

This method returns a particular order with all items, promo codes and taxes that were applied on this order.

Resource URL

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

Headers

Name	Value	Required?	Description
`Accept`	`application/json`	Yes	Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name	Required?	Type	Description
`code`	Yes	`guid`	The order unique token

Example request

curl -H "Accept: application/json" \
    https://app.snipcart.com/api/orders/d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70 \
    -u {API_KEY}:

Example response

{
    "token": "93c4604e-35ac-4db7-b3f1-2871476e9e6a",
    "creationDate": "2013-10-22T20:54:40.377Z",
    "modificationDate": "2013-10-22T20:55:45.617Z",
    "status": "Processed",
    "paymentMethod": "CreditCard",
    "invoiceNumber": "SNIP-1427",
    "email": "geeks@snipcart.com",
    "cardHolderName": "Geeks Snipcart",
    "creditCardLast4Digits": "4242",
    "billingAddressName": "Geeks Snipcart",
    "billingAddressCompanyName": "Snipcart",
    "billingAddressAddress1": "4885 1ere Avenue",
    "billingAddressAddress2": null,
    "billingAddressCity": "Quebec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1H2T5",
    "billingAddressPhone": "1-877-301-4813",
    "notes": null,
    "shippingAddressName": "Geeks Snipcart",
    "shippingAddressCompanyName": "Snipcart",
    "shippingAddressAddress1": "4885 1ere Avenue",
    "shippingAddressAddress2": null,
    "shippingAddressCity": "Quebec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1H2T5",
    "shippingAddressPhone": "1-877-301-4813",
    "shippingAddressSameAsBilling": true,
    "finalGrandTotal": 287.44,
    "shippingFees": 10,
    "shippingMethod": "Shipping",
    "items": [
        {
            "uniqueId": "1aad3398-1260-419c-9af4-d18e6fe75fbf",
            "id": "1",
            "name": "Un poster",
            "price": 300,
            "quantity": 1,
            "url": "http://snipcart.com",
            "weight": 10,
            "description": "Bacon",
            "image": "",
            "customFieldsJson": "[]",
            "stackable": true,
            "maxQuantity": null,
            "totalPrice": 300,
            "totalWeight": 10
        },
        ...
    ],
    "taxes": [
        {
            "taxName": "TPS",
            "taxRate": 0.05,
            "amount": 12.5,
            "numberForInvoice": ""
        },
        {
            "taxName": "TVQ",
            "taxRate": 0.09975,
            "amount": 24.94,
            "numberForInvoice": ""
        },
        ...
    ],
    "rebateAmount": 0,
    "subtotal": 310,
    "itemsTotal": 300,
    "grandTotal": 347.44,
    "totalWeight": 10,
    "hasPromocode": true,
    "totalRebateRate": 20,
    "promocodes": [
        {
            "code": "PROMO",
            "name": "PROMO",
            "type": "Rate",
            "rate": 20,
        },
        ...
    ],
    "willBePaidLater": false,
    "customFields": [
        {
            "name":"Slug",
            "value": "An order"
        },
        ...
    ],
    "paymentTransactionId": null,
}

PUT /orders/{token}

This method updates the status of the specified order. You can use this endpoint to set the order tracking number, change its status, or add useful metadata information.

Changing the status of an order from Pending to Processed as well as changing the payment status from Authorized to Paid will capture a payment. This only applies to two-step payments offered by Stripe.

Resource URL

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

Headers

Name	Value	Required?	Description
`Accept`	`application/json`	Yes	Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.
`Content-Type`	`application/json`	Yes	Make sure to specify the correct Content-Type. Our API is JSON only, we do not and will not support other content types such as XML.

Parameters

Name	Required?	Type	Description
`token`	Yes	`guid`	The order unique token. This parameter must be passed through the URL.
`status`	Yes	`string`	The order status. Possible values: (`InProgress`, `Processed`, `Disputed`, `Shipped`, `Delivered`, `Pending`, `Cancelled`)
`paymentStatus`	No	`string`	The order payment status. Possible values: (`Paid`, `Deferred`, `PaidDeferred`, `ChargedBack`, `Refunded`, `Paidout`, `Failed`, `Pending`, `Expired`, `Cancelled`, `Open`, `Authorized`).
`trackingNumber`	No	`string`	The tracking number associated to the order.
`trackingUrl`	No	`string`	The URL where the customer will be able to track its order.
`metadata`	No	`object`	A simple JSON object that can hold any data associated to this order. `{ "internal_id": "12345", "external_user_id": "user_id_1" }`

Example request

curl https://app.snipcart.com/api/orders/c7af6278-1c06-411d-b009-22a839efda75 -X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" -u {YOUR_API_KEY}: \
-d "{'status': 'Delivered'}"

Response

Example response

{
    "token": "c7af6278-1c06-411d-b009-22a839efda75",
    "creationDate": "2013-10-22T20:54:40.377Z",
    "modificationDate": "2013-10-22T20:55:45.617Z",
    "status": "Delivered",
    "paymentMethod": "CreditCard",
    "invoiceNumber": "SNIP-1427",
    "email": "geeks@snipcart.com",
    "cardHolderName": "Geeks Snipcart",
    "creditCardLast4Digits": "4242",
    "billingAddressName": "Geeks Snipcart",
    "billingAddressCompanyName": "Snipcart",
    "billingAddressAddress1": "4885 1ere Avenue",
    "billingAddressAddress2": null,
    "billingAddressCity": "Quebec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1H2T5",
    "billingAddressPhone": "1-877-301-4813",
    "notes": null,
    "shippingAddressName": "Geeks Snipcart",
    "shippingAddressCompanyName": "Snipcart",
    "shippingAddressAddress1": "4885 1ere Avenue",
    "shippingAddressAddress2": null,
    "shippingAddressCity": "Quebec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1H2T5",
    "shippingAddressPhone": "1-877-301-4813",
    "shippingAddressSameAsBilling": true,
    "finalGrandTotal": 287.44,
    "shippingFees": 10,
    "shippingMethod": "Shipping",
    "items": [
        {
            "uniqueId": "1aad3398-1260-419c-9af4-d18e6fe75fbf",
            "id": "1",
            "name": "Un poster",
            "price": 300,
            "quantity": 1,
            "url": "http://snipcart.com",
            "weight": 10,
            "description": "Bacon",
            "image": "",
            "customFieldsJson": "[]",
            "stackable": true,
            "maxQuantity": null,
            "totalPrice": 300,
            "totalWeight": 10
        },
        ...
    ],
    "taxes": [
        {
            "taxName": "TPS",
            "taxRate": 0.05,
            "amount": 12.5,
            "numberForInvoice": ""
        },
        {
            "taxName": "TVQ",
            "taxRate": 0.09975,
            "amount": 24.94,
            "numberForInvoice": ""
        },
        ...
    ],
    "rebateAmount": 0,
    "subtotal": 310,
    "itemsTotal": 300,
    "grandTotal": 347.44,
    "totalWeight": 10,
    "hasPromocode": true,
    "totalRebateRate": 20,
    "promocodes": [
        {
            "code": "PROMO",
            "name": "PROMO",
            "type": "Rate",
            "rate": 20,
        },
        ...
    ],
    "willBePaidLater": false,
    "customFields": [],
    "paymentTransactionId": null,
}

API: orders

GET /orders

GET /orders/{token}

PUT /orders/{token}

Was this article helpful?