Orders

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

GET /orders

This method will return you 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.
placedBy No string The name of the person who made the purchase.
from No datetime Will return only the orders placed after this date.
to No datetime Will return only the orders placed before this date.

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 will return a particular order with all items, promocodes 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. We plan to allow updating more information in the future, but for now only the status is updatable through the API.

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).
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 http://app.snipcart.local/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,
}