Template Docs Commerce APIs Tools
Get Started
Get Started

Orders API Overview

Current Version: 1.0

The Orders API provides access to a store's complete order history, which includes traditional checkout orders and recurring orders generated by customer subscriptions. Using this API, you can read order data and mark orders as fulfilled, updating them with shipment information and triggering notifications.

Order Resources

An order resource returned by this API has the following characteristics:

{
  "id": "585d498fdee9f31a60284a37",
  "orderNumber": "3",
  "createdOn": "2016-12-23T15:58:07.187Z",
  "modifiedOn": "2016-12-23T15:58:07.187Z",
  "testmode": true,
  "customerEmail": "foo@example.com",
  "billingAddress": {
    "firstName": "Bob",
    "lastName": "Loblaw",
    "address1": "459 Broadway",
    "address2": null,
    "city": "New York",
    "state": "NY",
    "countryCode": "US",
    "postalCode": "10003",
    "phone": "5553334444"
  },
  "shippingAddress": {
    "firstName": "Bob",
    "lastName": "Loblaw",
    "address1": "459 Broadway",
    "address2": null,
    "city": "New York",
    "state": "NY",
    "countryCode": "US",
    "postalCode": "10003",
    "phone": "5553334444"
  },
  "fulfillmentStatus": "PENDING",
  "lineItems": [
    {
      "id": "585d4975dee9f31a60284a16",
      "variantId": "88c16ee4-547b-445e-a392-bded9991ae30",
      "sku": "SQ3381024",
      "productId": "565c8f3da7c8a3cf71d5fd0a",
      "productName": "Product",
      "quantity": 1,
      "unitPricePaid": {
        "value": "55.00",
        "currency": "USD"
      },
      "variantOptions": [
        {
          "value": "Small",
          "optionName": "Size"
        }, {
          "value": "Red",
          "optionName": "Color"
        }
      ],
      "customizations": [
        {
          "label": "Shirt Emblem Location",
          "value": "Middle Chest"
        }
      ],
      "imageUrl": "https://static.squarespace.com/universal/commerce/images/brine-32oz-spring-mix-v2.jpg?format=300w"
    }
  ],
  "internalNotes": [
    {
      "content": "First note"
    }, {
      "content": "Second note"
    }
  ],
  "shippingLines": [
    {
      "method": "Flat Rate",
      "amount": {
        "value": "1.00",
        "currency": "USD"
      }
    }
  ],
  "discountLines": [
    {
      "description": "Fall Sale",
      "amount": {
        "value": "1.00",
        "currency": "USD"
      },
      "promoCode": "FALLSALE"
    }
  ],
  "formSubmission": [
    {
      "label": "How did you hear about us?",
      "value": "Facebook"
    }
  ],
  "fulfillments": [
    {
      "shipDate": "2017-01-28T22:19:26.980Z",
      "carrierName": "USPS",
      "service": "Priority Mail",
      "trackingNumber": "9400109699939624119857",
      "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=9400109699939624119857"
    }, {
      "shipDate": "2017-01-29T22:19:26.980Z",
      "carrierName": "FedEx",
      "service": "Same-Day Delivery",
      "trackingNumber": "103932814692659",
      "trackingUrl": "https://www.fedex.com/apps/fedextrack/?tracknumbers=103932814692659"
    }
  ],
  "subtotal": {
    "value": "55.00",
    "currency": "USD"
  },
  "shippingTotal": {
    "value": "1.00",
    "currency": "USD"
  },
  "discountTotal": {
    "value": "1.00",
    "currency": "USD"
  },
  "taxTotal": {
    "value": "2.70",
    "currency": "USD"
  },
  "refundedTotal": {
    "value": "0.00",
    "currency": "USD"
  },
  "grandTotal": {
    "value": "57.70",
    "currency": "USD"
  }
}
  • id: The order's system identifier.
  • orderNumber: The unique, sequential number of this order.
  • createdOn: The ISO 8601 date and time representation of when this order was created.
  • modifiedOn: The ISO 8601 date and time representation of when this order was last modified.
  • testMode: If true, this order is a test order, created using a payment method in test mode.
  • customerEmail: The email address entered at checkout or, for recurring subscription orders, is the customer's current email address.
  • billingAddress: The customer’s billing address.
  • shippingAddress: The customer’s shipping address.
  • fulfillmentStatus: The current status of the order in the fulfillment workflow. Possible values are: PENDING, FULFILLED, and CANCELED.
  • lineItems: An array of line item objects that describe what was purchased and how many were purchased, including requested customizations where applicable.
    • id: The line item’s system identifier.
    • variantId: The system identifier of the purchased product variant. Value will always be null for digital products. [1]
    • sku: The SKU of the purchased item.
    • productId: The system identifier of the purchased product.
    • productName: The name of the purchased product.
    • quantity: The amount of this purchased product.
    • unitPricePaid: The price the shopper paid per unit of this item.
    • variantOptions: An array of objects representing variant choices made by the shopper, such as “Small, Red” for a t-shirt.
    • customizations: An array of objects representing requested customizations, if supported by the item at purchase.
    • imageUrl: The URL to the primary image for this line item.
  • internalNotes: An array of internal order note objects. Attributes:
    • content: The content of the note.
  • shippingLines: An array of objects detailing chosen shipping options, such as method and cost.
  • discountLines: An array of objects detailing discounts the shopper applied to their order at checkout.
  • formSubmission: An array of objects detailing questions and answers the shopper provided at checkout, if they were presented with a form.
  • fulfillments: An array of fulfillment objects detailing shipment information for all shipments associated with the order.
    • shipDate: The ISO 8601 date and time representing the moment the shipment occurred.
    • carrierName: The name of the shipping company handling the shipment.
    • service: A string representing the level of service, as offered by the carrier, used for this shipment.
    • trackingNumber: The shipping company's parcel tracking number.
    • trackingUrl: The tracking URL for the shipment.
  • subtotal, shippingTotal, discountTotal, taxTotal, refundedTotal, grandTotal: Money objects representing totals respective to their named concerns: taxes, shipping, etc.

Notes

  1. Variant ids are only guaranteed to exist for sales of non-digital products on and after May 28, 2019. Variant id information is available prior to this date on an inconsistent basis.