API: orders

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

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

Was this article helpful?