Orders

For the moment, orders are readonly, you can not create new order or update existing one using our API. Those features will be available in the future.

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 (Processed, Cancelled, ...).
invoiceNumber No string The invoice number of the order you want 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
token 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:
  • 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.
Example:

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