Checkout

The Checkout API makes it possible to purchase products from a Shopify store programmatically. A checkout in Shopify is the object used to manage a user’s Cart as it transitions to a paid checkout. This includes calculating taxes, shipping rates, attaching a shipping address, and associating one or more payments.

Use this API if you want a fully customized checkout user experience, while taking full advantage of the commerce engine used to power every Shopify store.

For a detailed tutorial that walks you through the key capabilities of the Checkout API, see Sell through the Checkout API.

Caution

The Checkout API is only for use with the Sales Channel SDK. It is not possible to use it to create a new checkout for an individual store - for that you can use our Javascript, iOS, or Android SDKs.

Caution

The Checkout API can only be used with direct payment gateways. A list of all supported payment gateways can be found here.

What you can do with Checkout

The Shopify API lets you do the following with the Checkout resource. More detailed versions of these general actions may be available:

Checkout properties

billing_address
"billing_address": [
  {
    "address1": "Chestnut Street 92",
    "address2": "Suite 300",
    "city": "Louisville",
    "company": null,
    "country": "US",
    "first_name": null,
    "id": 207119551,
    "last_name": null,
    "phone": "555-625-1199",
    "province": "KY",
    "zip": "40202",
    "province_code": null,
    "country_code": null
  }
]

The mailing address associated with the payment method. It has the following properties:

  • address1: The street address of the billing_address.
  • address2: An optional additional field for the street address of the billing_address.
  • city: The city of the billing address.
  • company: The company of the person associated with the billing address.
  • country: The name of the country of the billing address.
  • country_code: The two-letter code (ISO 3166-1 alpha-2 two-letter country code) for the country of the billing address.
  • first_name: The first name of the person associated with the payment method.
  • last_name: The last name of the person associated with the payment method.
  • phone: The phone number at the billing address.
  • province: The name of the state or province of the billing address.
  • province_code: The two-letter abbreviation of the state or province of the billing address.
  • zip: The zip or postal code of the billing address.

created_at
"created_at": "2008-01-10T11:00:00-05:00"

The date and time when the checkout was created. The API returns this value in ISO 8601 format.

currency
"currency": "USD"

The three letter code (ISO 4217) for the currency used for the payment.

customer_id
"customer_id": 1234

The id of the customer associated with this checkout.

discount_code
"discount_code": "30_DOLLARS_OFF"

The discount code that is applied to the checkout. This updates the applied_discount with the appropriate metadata for that discount code. To remove a discount, send an empty string or null.

applied_discount
"applied_discount": [
  {
    "amount": "30.00",
    "title": "XYZ Promotion",
    "description": "Promotional item for blackfriday.",
    "value": "30.00",
    "value_type": "fixed_amount",
    "non_applicable_reason": null,
    "applicable": true
  }
]

The discount metadata generated by applying a discount code. A custom discount can also be added by specifying the amount, title, description, value, and value_type.

  • amount: The amount that is deducted from payment_due.
  • title: The title to categorize the applied discount.
  • description: The description of the applied discount.
  • value: The value that was used to calculate the final applied discount amount.
  • value_type: The type of value that was used to calculate the final applied discount amount. Possible values: fixed_amount, percentage
  • non_applicable_reason: Reason why the discount is not applicable, if the discount cannot be applied to the checkout.
  • applicable: Whether this discount code can be applied to the checkout.

email
"email": "bob.norman@hostmail.com"

The customer's email address.

gift_cards
"gift_cards": [
  {
    "amount_used": "30.00",
    "balance": "70.00",
    "id": "",
    "last_characters": "abdr"
  }
]

A list of gift card objects, each one containing information about a gift card applied to this checkout. Gift cards may be applied to a checkout by passing {"checkout": {"gift_cards": [{"code": "a gift card code"}, {"code": "another gift card code"}]}}. Each gift_card object returned has the following properties:

  • amount_used: The amount of the gift card used by this checkout.
  • code: A gift card code.
  • balance: The amount left on the gift card after being applied to this checkout.
  • id: The identifier for the applied gift card.
  • last_characters: The last four characters of the applied gift card for display back to the user.
Note that applying a gift_cards object to a checkout will overwrite any existing gift cards already defined in the checkout. Therefore, in order to remove a gift card from the list of applied gift cards, you must reapply a gift_cards array without that gift card.

line_items
"line_items": [
  {
    "compare_at_price": "9.99",
    "fulfillment_service": "manual",
    "fulfillment_status": null,
    "grams": "20",
    "id": 39072856,
    "line_price": "19.99",
    "price": "19.99",
    "product_id": 632910392,
    "quantity": "",
    "requires_shipping": false,
    "sku": "IPOD2008GREEN",
    "taxable": true,
    "title": "IPod Nano - 8GB",
    "variant_id": 39072856,
    "variant_title": "Green",
    "vendor": "Apple",
    "name": "IPod Nano - 8GB - Green"
  }
]

A list of line item objects, each one containing information about an item in the checkout. Each line_item object has the following properties:

  • fulfillment_service: Service provider who is doing the fulfillment. Valid values are: manual, api, legacy and custom
  • fulfillment_status: How far along an checkout is in terms line items fulfilled. Valid values are: fulfilled, null or partial.
  • grams: The weight of the item in grams.
  • id: An identifier for the line item.
  • line_price: The line price of the item.
  • price: The price of the item.
  • product_id: The unique numeric identifier for the product in the fulfillment.
  • properties: The order note on a checkout (optional).
  • quantity: The number of products that were purchased.
  • requires_shipping: States whether or not the fulfillment requires shipping. Values are: true or false.
  • sku: A unique identifier of the item in the fulfillment.
  • taxable: Whether this product is taxable.
  • title: The title of the product.
  • variant_id: The id of the product variant.
  • variant_title: The title of the product variant.
  • vendor: The name of the supplier of the item.
  • name: The name of the product variant.

requires_shipping
"requires_shipping": true

true if the checkout requires shipping. If so, the "shipping_line" must be set before creating a payment.

shipping_address
"shipping_address": [
  {
    "address1": "Chestnut Street 92",
    "address2": "Apt 2",
    "city": "Louisville",
    "company": null,
    "country": "United States",
    "first_name": "Bob",
    "last_name": "Norman",
    "phone": "555-625-1199",
    "province": "Kentucky",
    "zip": "40202",
    "country_code": "US",
    "province_code": "KY"
  }
]

The mailing address to where the checkout will be shipped. It has the following properties:

  • address1: The street address of the shipping address.
  • address2: An optional additional field for the street address of the shipping address.
  • city: The city of the shipping address.
  • company: The company of the person associated with the shipping address.
  • country: The name of the country of the shipping address.
  • country_code: The two-letter code for the country of the shipping address.
  • first_name: The first name of the person associated with the payment method.
  • last_name: The last name of the person associated with the payment method.
  • phone: The phone number at the shipping address.
  • province: The name of the state or province of the shipping address.
  • province_code: The two-letter abbreviation of the state or province of the shipping address.
  • zip: The zip or postal code of the shipping address.

shipping_rates

An array of shipping_rate objects, each of which details the shipping methods available.

shipping_rate
"shipping_rate": [
  {
    "handle": "shopify-10.00%20standard-shipping",
    "price": "10.00",
    "title": "Standard shipping",
    "checkout": {:subtotal_price=>"75.00", :total_price=>"111.16", :total_tax=>"9.66"},
    "delivery_range": [
      {
        "2015-04-03T00:00:00.000+00:00",
"2015-04-04T00:00:00.000+00:00"
      }
    ],
    "requires_phone": false
  }
]

Each shipping_rate object has the following properties:

  • handle: A concatenation of shipping provider, price, and title, enabling the customer to select the applicable shipping_rate.
  • price: The price of this shipping method.
  • title: The shipping method name.
  • checkout: An object containing the new price information for the checkout should this shipping method be applied.
  • delivery_range: one or two ISO 8601 timestamps of the potential delivery dates.
  • requires_phone: True when phone number is required.

shipping_line
"handle": "shopify-10.00%20-standard-shipping"

Once a shipping_rate is selected by the customer it is transitioned to a shipping_line object. Shipping_lines on checkouts can be updated via the API, if the customer decides to pick a different shipping_rate.

subtotal_price
"subtotal_price": "398.00"

Price of the checkout before shipping and taxes

tax_lines
"tax_lines": [
  {
    "price": "11.94",
    "rate": "0.06",
    "title": "State Tax"
  }
]

An array of tax_line objects, each of which details the taxes applicable to the checkout. Each tax_line object has the following properties:

  • price: The amount of tax to be charged.
  • rate: The rate of tax to be applied.
  • title: The name of the tax.

taxes_included
"taxes_included": false

True when taxes are included in the subtotal_price

token
"token": "b1946ac92492d2347c6235b4d2611184"

Unique identifier for a particular checkout.

total_price
"total_price": "409.94"

The sum of all the prices of all the items in the checkout, taxes and discounts included.

total_tax
"total_tax": "11.94"

The sum of all the taxes applied to the line items in the checkout.

updated_at
"updated_at": "2012-08-24T14:02:15-04:00"

The date and time when the checkout was last modified. The API returns this value in ISO 8601 format.

order
"order": [
  {
    "id": 123,
    "name": "#0123",
    "status_url": "https://checkout.shopify.com/123/checkouts/4207896aad57dfb159?key=123abc"
  }
]

This value is null until the checkout is complete. Once it is completed, this field will contain the id, name and status_url of the associated order.

user_id
"user_id": 1234

The id of the user who created the checkout. It is null by default. This value will be passed to the order.

web_url
"order_status_url": "https://checkout.shopify.com/112233/checkouts/4207896aad57dfb159?key=123abc"

The url pointing to the checkout accessible from the web.

payment_url
"payment_url": "https://elb.deposit.shopifycs.com/sessions"

The url which must be used to store credit cards in Shopify's card vault. These urls may change at our discretion, so you should always use the one supplied here. The general pattern for the urls is https://elb.deposit.shopifycs.com/sessions

reservation_time
"reservation_time": 300

The reservation time in seconds for the products in the line items. This can be set up to 5 minutes, or 1 hour depending on the authentication type used.

reservation_time_left
"reservation_time_left": 220

The time in seconds that the products in the line items will be held. If the reservation time expires, the products may not be available and completion may fail.

source_name
"source_name": "my_app"

Apart from the reserved values of 'web', 'pos', 'iphone' and 'android'; you may set this value to whatever you like.

payment_due
"payment_due": "99.95"

The amount left to be paid. This is equal to the cost of the line items, taxes and shipping minus discounts and gift cards.

request_details
"request_details": [
  {
    "ip_address": "123.1.1.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36",
    "accept_language": "en-US,en;q=0.8,fr;q=0.6"
  }
]

The request details of the customer you are processing the checkout on behalf of.

  • ip_address: The IP address of the customer.
  • user_agent: A string identifying the customer's user agent.
  • accept_language: A string identifying the customer's preferred language, formatted according to the Accept-Language header as defined in RFC2616 Section 14.4.

Endpoints

POST /admin/checkouts.json
Create a new Checkout

Create a new Checkout with a product variant and quantity

POST /admin/checkouts.json
{
  "checkout": {
    "line_items": [
      {
        "variant_id": 39072856,
        "quantity": 5
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
Location: https://apple.myshopify.com/admin/checkouts/24f69147f52ddb25e2e5ee05aaa41aa8.json
{
  "checkout": {
    "completed_at": null,
    "created_at": "2017-01-18T15:45:27-05:00",
    "currency": "USD",
    "customer_id": null,
    "device_id": null,
    "discount_code": null,
    "email": null,
    "location_id": null,
    "name": "#1066348317",
    "note": "",
    "note_attributes": {},
    "order_id": null,
    "order": null,
    "payment_due": "995.00",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 300,
    "reservation_time": 300,
    "source_identifier": null,
    "source_name": "755357713",
    "source_url": null,
    "subtotal_price": "995.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "24f69147f52ddb25e2e5ee05aaa41aa8",
    "total_price": "995.00",
    "total_tax": "0.00",
    "updated_at": "2017-01-18T15:45:27-05:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/24f69147f52ddb25e2e5ee05aaa41aa8",
    "line_items": [
      {
        "id": "d1b1f216123c277b3e0997a6f2b42c55",
        "key": "d1b1f216123c277b3e0997a6f2b42c55",
        "product_id": 632910392,
        "variant_id": 39072856,
        "sku": "IPOD2008GREEN",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Green",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "995.00",
        "properties": {},
        "quantity": 5,
        "grams": 567,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
    ],
    "tax_manipulations": [
    ],
    "shipping_line": null,
    "shipping_rate": null,
    "shipping_address": null,
    "credit_card": null,
    "billing_address": null,
    "applied_discount": null
  }
}

Create a new checkout without any line_items

POST /admin/checkouts.json
{
  "checkout": {
    "email": "me@example.com"
  }
}
View Response
HTTP/1.1 201 Created
Location: https://apple.myshopify.com/admin/checkouts/235f79e56e0b5b2eb65c45c612618d2a.json
{
  "checkout": {
    "completed_at": null,
    "created_at": "2017-01-18T15:45:33-05:00",
    "currency": "USD",
    "customer_id": 1073339457,
    "device_id": null,
    "discount_code": null,
    "email": "me@example.com",
    "location_id": null,
    "name": "#1066348318",
    "note": "",
    "note_attributes": {},
    "order_id": null,
    "order": null,
    "payment_due": "0.00",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": false,
    "reservation_time_left": 0,
    "reservation_time": 300,
    "source_identifier": null,
    "source_name": "755357713",
    "source_url": null,
    "subtotal_price": "0.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "235f79e56e0b5b2eb65c45c612618d2a",
    "total_price": "0.00",
    "total_tax": "0.00",
    "updated_at": "2017-01-18T15:45:33-05:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/235f79e56e0b5b2eb65c45c612618d2a",
    "line_items": [
    ],
    "gift_cards": [
    ],
    "tax_lines": [
    ],
    "tax_manipulations": [
    ],
    "shipping_line": null,
    "shipping_rate": null,
    "shipping_address": null,
    "credit_card": null,
    "billing_address": null,
    "applied_discount": null
  }
}

Trying to create a checkout with errors such as an invalid variant_id will result in a 422, no checkout created and errors returned

POST /admin/checkouts.json
{
  "checkout": {
    "line_items": [
      {
        "variant_id": 123456789,
        "quantity": 1
      }
    ]
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "line_items": {
      "0": {
        "variant_id": [
          {
            "code": "invalid",
            "message": "is invalid",
            "options": {}
          }
        ]
      }
    }
  }
}

Errors on line items are mapped by index

POST /admin/checkouts.json
{
  "checkout": {
    "line_items": [
      {
        "variant_id": 39072856,
        "quantity": 1
      },
      {
        "variant_id": 1,
        "quantity": 1
      },
      {
        "variant_id": 1,
        "quantity": 1
      },
      {
        "variant_id": 49148385,
        "quantity": 1
      },
      {
        "variant_id": 1,
        "quantity": 1
      }
    ]
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "line_items": {
      "1": {
        "variant_id": [
          {
            "code": "invalid",
            "message": "is invalid",
            "options": {}
          }
        ]
      },
      "2": {
        "variant_id": [
          {
            "code": "invalid",
            "message": "is invalid",
            "options": {}
          }
        ]
      },
      "4": {
        "variant_id": [
          {
            "code": "invalid",
            "message": "is invalid",
            "options": {}
          }
        ]
      }
    }
  }
}
GET /admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a.json
Get a single Checkout

Get an existing Checkout

GET /admin/checkouts/#{token}.json
View Response
HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a.json
Retry-After: 1
{
  "checkout": {
    "completed_at": null,
    "created_at": "2012-10-12T07:05:27-04:00",
    "currency": "USD",
    "customer_id": 207119551,
    "device_id": null,
    "discount_code": null,
    "email": "bob.norman@hostmail.com",
    "location_id": null,
    "name": "#862052962",
    "note": "",
    "note_attributes": {
      "custom engraving": "Happy Birthday",
      "colour": "green"
    },
    "order_id": null,
    "order": null,
    "payment_due": "379.69",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 0,
    "reservation_time": null,
    "source_identifier": null,
    "source_name": "web",
    "source_url": null,
    "subtotal_price": "398.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "total_price": "379.69",
    "total_tax": "21.49",
    "updated_at": "2012-10-12T07:05:27-04:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/exuw7apwoycchjuwtiqg8nytfhphr62a",
    "line_items": [
      {
        "id": "1bec1113d7cd1926",
        "key": "1bec1113d7cd1926",
        "product_id": 632910392,
        "variant_id": 49148385,
        "sku": "IPOD2008RED",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Red",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      },
      {
        "id": "902a33517a9a7d2c",
        "key": "902a33517a9a7d2c",
        "product_id": 632910392,
        "variant_id": 808950810,
        "sku": "IPOD2008PINK",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Pink",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
      {
        "price": "21.49",
        "rate": 0.06,
        "title": "State Tax",
        "compare_at": 0.06
      }
    ],
    "tax_manipulations": [
    ],
    "shipping_line": {
      "handle": "shopify-Free%20Shipping-0.00",
      "price": "0.00",
      "title": "Free Shipping"
    },
    "shipping_rate": {
      "id": "shopify-Free%20Shipping-0.00",
      "price": "0.00",
      "title": "Free Shipping"
    },
    "shipping_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "credit_card": null,
    "billing_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "applied_discount": null
  }
}

Get a completed Checkout

GET /admin/checkouts/#{token}.json
View Response
HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/checkouts/bd5a8aa1ecd019dd3520ff791ee3a24c.json
{
  "checkout": {
    "completed_at": "2005-07-31T11:57:11-04:00",
    "created_at": "2012-10-12T07:05:27-04:00",
    "currency": "USD",
    "customer_id": 207119551,
    "device_id": null,
    "discount_code": null,
    "email": "bob.norman@hostmail.com",
    "location_id": null,
    "name": "#901414060",
    "note": "",
    "note_attributes": {
      "custom engraving": "Happy Birthday",
      "colour": "green"
    },
    "order_id": 450789469,
    "order": {
      "id": 450789469,
      "name": "#1001",
      "status_url": "https:\/\/checkout.local\/690933842\/checkouts\/bd5a8aa1ecd019dd3520ff791ee3a24c\/thank_you"
    },
    "payment_due": "408.99",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 0,
    "reservation_time": null,
    "source_identifier": null,
    "source_name": "web",
    "source_url": null,
    "subtotal_price": "398.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
    "total_price": "408.99",
    "total_tax": "0.00",
    "updated_at": "2012-10-12T07:05:27-04:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/bd5a8aa1ecd019dd3520ff791ee3a24c",
    "line_items": [
      {
        "id": "1bec1113d7cd1926",
        "key": "1bec1113d7cd1926",
        "product_id": 632910392,
        "variant_id": 49148385,
        "sku": "IPOD2008RED",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Red",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      },
      {
        "id": "902a33517a9a7d2c",
        "key": "902a33517a9a7d2c",
        "product_id": 632910392,
        "variant_id": 808950810,
        "sku": "IPOD2008PINK",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Pink",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
    ],
    "tax_manipulations": [
    ],
    "shipping_line": {
      "handle": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping"
    },
    "shipping_rate": {
      "id": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping"
    },
    "shipping_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "credit_card": null,
    "billing_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "applied_discount": null
  }
}

Get a processing Checkout

GET /admin/checkouts/#{token}.json
View Response
HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x.json
Retry-After: 1
{
  "checkout": {
    "completed_at": null,
    "created_at": "2012-10-12T07:05:27-04:00",
    "currency": "USD",
    "customer_id": 207119551,
    "device_id": null,
    "discount_code": null,
    "email": "bob.norman@hostmail.com",
    "location_id": null,
    "name": "#446514532",
    "note": "",
    "note_attributes": {
      "custom engraving": "Happy Birthday",
      "colour": "green"
    },
    "order_id": null,
    "order": null,
    "payment_due": "408.99",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
      {
        "id": 25428999,
        "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
        "payment_processing_error_message": null,
        "transaction": null,
        "credit_card": null
      }
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 0,
    "reservation_time": null,
    "source_identifier": null,
    "source_name": "web",
    "source_url": null,
    "subtotal_price": "398.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
    "total_price": "408.99",
    "total_tax": "21.49",
    "updated_at": "2012-10-12T07:05:27-04:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
    "line_items": [
      {
        "id": "1bec1113d7cd1926",
        "key": "1bec1113d7cd1926",
        "product_id": 632910392,
        "variant_id": 49148385,
        "sku": "IPOD2008RED",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Red",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      },
      {
        "id": "902a33517a9a7d2c",
        "key": "902a33517a9a7d2c",
        "product_id": 632910392,
        "variant_id": 808950810,
        "sku": "IPOD2008PINK",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Pink",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
      {
        "price": "21.49",
        "rate": 0.06,
        "title": "State Tax",
        "compare_at": 0.06
      }
    ],
    "tax_manipulations": [
    ],
    "shipping_line": {
      "handle": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping"
    },
    "shipping_rate": {
      "id": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping"
    },
    "shipping_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "credit_card": {
      "first_name": "Bob",
      "last_name": "Norman",
      "first_digits": "1",
      "last_digits": "1",
      "expiry_month": 8,
      "expiry_year": 2042
    },
    "billing_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "applied_discount": null
  }
}
PUT /admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a.json
Modify an existing Checkout

Select a shipping rate

PUT /admin/checkouts/#{token}.json
{
  "checkout": {
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "shipping_line": {
      "handle": "shopify-Standard%20Shipping-10.99"
    }
  }
}
View Response
HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a.json
{
  "checkout": {
    "completed_at": null,
    "created_at": "2012-10-12T07:05:27-04:00",
    "currency": "USD",
    "customer_id": 207119551,
    "device_id": null,
    "discount_code": null,
    "email": "bob.norman@hostmail.com",
    "location_id": null,
    "name": "#862052962",
    "note": "",
    "note_attributes": {
      "custom engraving": "Happy Birthday",
      "colour": "green"
    },
    "order_id": null,
    "order": null,
    "payment_due": "408.99",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 0,
    "reservation_time": null,
    "source_identifier": null,
    "source_name": "web",
    "source_url": null,
    "subtotal_price": "398.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "total_price": "408.99",
    "total_tax": "0.00",
    "updated_at": "2017-01-18T15:45:25-05:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/exuw7apwoycchjuwtiqg8nytfhphr62a",
    "line_items": [
      {
        "id": "1bec1113d7cd1926",
        "key": "1bec1113d7cd1926",
        "product_id": 632910392,
        "variant_id": 49148385,
        "sku": "IPOD2008RED",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Red",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      },
      {
        "id": "902a33517a9a7d2c",
        "key": "902a33517a9a7d2c",
        "product_id": 632910392,
        "variant_id": 808950810,
        "sku": "IPOD2008PINK",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Pink",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
    ],
    "tax_manipulations": [
    ],
    "shipping_line": {
      "handle": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping"
    },
    "shipping_rate": {
      "id": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping"
    },
    "shipping_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "credit_card": null,
    "billing_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "applied_discount": null
  }
}

Update the shipping address and email of a Checkout

PUT /admin/checkouts/#{token}.json
{
  "checkout": {
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "email": "john.smith@example.com",
    "shipping_address": {
      "first_name": "John",
      "last_name": "Smith",
      "address1": "126 York St.",
      "city": "Los Angeles",
      "province_code": "CA",
      "country_code": "US",
      "phone": "(123)456-7890",
      "zip": "90002"
    }
  }
}
View Response
HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a.json
Retry-After: 1
{
  "checkout": {
    "completed_at": null,
    "created_at": "2012-10-12T07:05:27-04:00",
    "currency": "USD",
    "customer_id": 1073339456,
    "device_id": null,
    "discount_code": null,
    "email": "john.smith@example.com",
    "location_id": null,
    "name": "#862052962",
    "note": "",
    "note_attributes": {
      "custom engraving": "Happy Birthday",
      "colour": "green"
    },
    "order_id": null,
    "order": null,
    "payment_due": "398.00",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 0,
    "reservation_time": null,
    "source_identifier": null,
    "source_name": "web",
    "source_url": null,
    "subtotal_price": "398.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "total_price": "398.00",
    "total_tax": "0.00",
    "updated_at": "2017-01-18T15:45:31-05:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/exuw7apwoycchjuwtiqg8nytfhphr62a",
    "line_items": [
      {
        "id": "1bec1113d7cd1926",
        "key": "1bec1113d7cd1926",
        "product_id": 632910392,
        "variant_id": 49148385,
        "sku": "IPOD2008RED",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Red",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      },
      {
        "id": "902a33517a9a7d2c",
        "key": "902a33517a9a7d2c",
        "product_id": 632910392,
        "variant_id": 808950810,
        "sku": "IPOD2008PINK",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Pink",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
    ],
    "tax_manipulations": [
    ],
    "shipping_line": null,
    "shipping_rate": null,
    "shipping_address": {
      "id": 550558813,
      "first_name": "John",
      "last_name": "Smith",
      "phone": "(123)456-7890",
      "company": null,
      "address1": "126 York St.",
      "address2": "",
      "city": "Los Angeles",
      "province": "California",
      "province_code": "CA",
      "country": "United States",
      "country_code": "US",
      "zip": "90002"
    },
    "credit_card": null,
    "billing_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "applied_discount": null
  }
}

Set the reservation to expire in five minutes

PUT /admin/checkouts/#{token}.json
{
  "checkout": {
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "reservation_time": 300
  }
}
View Response
HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a.json
Retry-After: 1
{
  "checkout": {
    "completed_at": null,
    "created_at": "2012-10-12T07:05:27-04:00",
    "currency": "USD",
    "customer_id": 207119551,
    "device_id": null,
    "discount_code": null,
    "email": "bob.norman@hostmail.com",
    "location_id": null,
    "name": "#862052962",
    "note": "",
    "note_attributes": {
      "custom engraving": "Happy Birthday",
      "colour": "green"
    },
    "order_id": null,
    "order": null,
    "payment_due": "398.00",
    "payment_url": "https:\/\/app.local\/cardserver\/sessions",
    "payments": [
    ],
    "privacy_policy_url": null,
    "refund_policy_url": null,
    "requires_shipping": true,
    "reservation_time_left": 300,
    "reservation_time": 300,
    "source_identifier": null,
    "source_name": "web",
    "source_url": null,
    "subtotal_price": "398.00",
    "tax_exempt": false,
    "taxes_included": false,
    "terms_of_service_url": null,
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "total_price": "398.00",
    "total_tax": "0.00",
    "updated_at": "2017-01-18T15:45:35-05:00",
    "user_id": null,
    "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/exuw7apwoycchjuwtiqg8nytfhphr62a",
    "line_items": [
      {
        "id": "1bec1113d7cd1926",
        "key": "1bec1113d7cd1926",
        "product_id": 632910392,
        "variant_id": 49148385,
        "sku": "IPOD2008RED",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Red",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      },
      {
        "id": "902a33517a9a7d2c",
        "key": "902a33517a9a7d2c",
        "product_id": 632910392,
        "variant_id": 808950810,
        "sku": "IPOD2008PINK",
        "vendor": "Apple",
        "title": "IPod Nano - 8GB",
        "variant_title": "Pink",
        "taxable": true,
        "requires_shipping": true,
        "price": "199.00",
        "compare_at_price": null,
        "line_price": "199.00",
        "properties": {},
        "quantity": 1,
        "grams": 200,
        "fulfillment_service": "manual",
        "applied_discounts": [
        ]
      }
    ],
    "gift_cards": [
    ],
    "tax_lines": [
    ],
    "tax_manipulations": [
    ],
    "shipping_line": {
      "handle": "shopify-Free%20Shipping-0.00",
      "price": "0.00",
      "title": "Free Shipping"
    },
    "shipping_rate": {
      "id": "shopify-Free%20Shipping-0.00",
      "price": "0.00",
      "title": "Free Shipping"
    },
    "shipping_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "credit_card": null,
    "billing_address": {
      "id": 550558813,
      "first_name": "Bob",
      "last_name": "Norman",
      "phone": "555-625-1199",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
    },
    "applied_discount": null
  }
}

Update shipping address with an invalid zip

PUT /admin/checkouts/#{token}.json
{
  "checkout": {
    "token": "exuw7apwoycchjuwtiqg8nytfhphr62a",
    "shipping_address": {
      "first_name": "John",
      "last_name": "Smith",
      "address1": "126 York St.",
      "city": "Beverly Hills",
      "province_code": "CA",
      "country_code": "US",
      "phone": "(123)456-7890",
      "zip": "12345"
    }
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "shipping_address": {
      "zip": [
        {
          "code": "invalid_for_country_and_province",
          "message": "is not valid for California and United States",
          "options": {
            "province": "California",
            "country": "United States"
          }
        }
      ]
    }
  }
}
GET /admin/checkouts/zs9ru89kuqcdagk8bz4r9hnxt22wwd42/shipping_rates.json
Get a list of available shipping rates for the specified checkout. Implementers need to poll this API until rates become available. Each shipping rate will also contain the checkout's subtotal_price, total_tax and total_price in the event that this shipping rate is selected. This can be used to update the UI without performing a road-trip to API.

Rates have been requested but none are available for the current shipping address and cart.

GET /admin/checkouts/#{token}/shipping_rates.json
View Response
HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/checkouts/zs9ru89kuqcdagk8bz4r9hnxt22wwd42/shipping_rates.json
{
  "shipping_rates": [
  ]
}

Rates have been requested but are not yet available.

GET /admin/checkouts/#{token}/shipping_rates.json
View Response
HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a/shipping_rates.json
Retry-After: 1
{
  "shipping_rates": [
  ]
}

Rates have been requested and are available.

GET /admin/checkouts/#{token}/shipping_rates.json
View Response
HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/checkouts/exuw7apwoycchjuwtiqg8nytfhphr62a/shipping_rates.json
{
  "shipping_rates": [
    {
      "id": "shopify-Standard%20Shipping-10.99",
      "price": "10.99",
      "title": "Standard Shipping",
      "checkout": {
        "total_tax": "0.00",
        "total_price": "408.99",
        "subtotal_price": "398.00"
      },
      "phone_required": false,
      "delivery_range": null,
      "handle": "shopify-Standard%20Shipping-10.99"
    },
    {
      "id": "shopify-Expensive%20Shipping-99.99",
      "price": "99.99",
      "title": "Expensive Shipping",
      "checkout": {
        "total_tax": "0.00",
        "total_price": "497.99",
        "subtotal_price": "398.00"
      },
      "phone_required": false,
      "delivery_range": null,
      "handle": "shopify-Expensive%20Shipping-99.99"
    }
  ]
}
GET /admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
Retreive a list of Payments on a particular Checkout

Retrive all the Payments on a Checkout

GET /admin/checkouts/#{token}/payments.json
View Response
HTTP/1.1 200 OK
{
  "payments": [
    {
      "id": 25428999,
      "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
      "payment_processing_error_message": null,
      "transaction": null,
      "credit_card": null,
      "checkout": {
        "completed_at": null,
        "created_at": "2012-10-12T07:05:27-04:00",
        "currency": "USD",
        "customer_id": 207119551,
        "device_id": null,
        "discount_code": null,
        "email": "bob.norman@hostmail.com",
        "location_id": null,
        "name": "#446514532",
        "note": "",
        "note_attributes": {
          "custom engraving": "Happy Birthday",
          "colour": "green"
        },
        "order_id": null,
        "order": null,
        "payment_due": "408.99",
        "payment_url": "https:\/\/app.local\/cardserver\/sessions",
        "payments": [
          {
            "id": 25428999,
            "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
            "payment_processing_error_message": null,
            "transaction": null,
            "credit_card": null
          }
        ],
        "privacy_policy_url": null,
        "refund_policy_url": null,
        "requires_shipping": true,
        "reservation_time_left": 0,
        "reservation_time": null,
        "source_identifier": null,
        "source_name": "web",
        "source_url": null,
        "subtotal_price": "398.00",
        "tax_exempt": false,
        "taxes_included": false,
        "terms_of_service_url": null,
        "token": "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
        "total_price": "408.99",
        "total_tax": "21.49",
        "updated_at": "2012-10-12T07:05:27-04:00",
        "user_id": null,
        "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
        "line_items": [
          {
            "id": "1bec1113d7cd1926",
            "key": "1bec1113d7cd1926",
            "product_id": 632910392,
            "variant_id": 49148385,
            "sku": "IPOD2008RED",
            "vendor": "Apple",
            "title": "IPod Nano - 8GB",
            "variant_title": "Red",
            "taxable": true,
            "requires_shipping": true,
            "price": "199.00",
            "compare_at_price": null,
            "line_price": "199.00",
            "properties": {},
            "quantity": 1,
            "grams": 200,
            "fulfillment_service": "manual",
            "applied_discounts": [
            ]
          },
          {
            "id": "902a33517a9a7d2c",
            "key": "902a33517a9a7d2c",
            "product_id": 632910392,
            "variant_id": 808950810,
            "sku": "IPOD2008PINK",
            "vendor": "Apple",
            "title": "IPod Nano - 8GB",
            "variant_title": "Pink",
            "taxable": true,
            "requires_shipping": true,
            "price": "199.00",
            "compare_at_price": null,
            "line_price": "199.00",
            "properties": {},
            "quantity": 1,
            "grams": 200,
            "fulfillment_service": "manual",
            "applied_discounts": [
            ]
          }
        ],
        "gift_cards": [
        ],
        "tax_lines": [
          {
            "price": "21.49",
            "rate": 0.06,
            "title": "State Tax",
            "compare_at": 0.06
          }
        ],
        "tax_manipulations": [
        ],
        "shipping_line": {
          "handle": "shopify-Standard%20Shipping-10.99",
          "price": "10.99",
          "title": "Standard Shipping"
        },
        "shipping_rate": {
          "id": "shopify-Standard%20Shipping-10.99",
          "price": "10.99",
          "title": "Standard Shipping"
        },
        "shipping_address": {
          "id": 550558813,
          "first_name": "Bob",
          "last_name": "Norman",
          "phone": "555-625-1199",
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "province_code": "KY",
          "country": "United States",
          "country_code": "US",
          "zip": "40202"
        },
        "credit_card": {
          "first_name": "Bob",
          "last_name": "Norman",
          "first_digits": "1",
          "last_digits": "1",
          "expiry_month": 8,
          "expiry_year": 2042
        },
        "billing_address": {
          "id": 550558813,
          "first_name": "Bob",
          "last_name": "Norman",
          "phone": "555-625-1199",
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "province_code": "KY",
          "country": "United States",
          "country_code": "US",
          "zip": "40202"
        },
        "applied_discount": null
      }
    }
  ]
}
POST /admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
session_id represents the id that was returned by the card vault.

Attempting an authorization with an invalid session_id.

POST /admin/checkouts/#{token}/payments.json
{
  "payment": {
    "request_details": {
      "ip_address": "123.1.1.1",
      "accept_language": "en-US,en;q=0.8,fr;q=0.6",
      "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36"
    },
    "amount": "408.99",
    "session_id": "global-an_invalid_session_id",
    "unique_token": "client-side-idempotency-token"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "payment_gateway": [
      {
        "code": "invalid",
        "message": "is invalid",
        "options": {}
      }
    ],
    "checkout": {
      "payment_gateway": [
        {
          "code": "invalid",
          "message": "is invalid",
          "options": {}
        }
      ]
    }
  }
}

Attempting an authorization with a valid session_id can fail for various reasons.

POST /admin/checkouts/#{token}/payments.json
{
  "payment": {
    "request_details": {
      "ip_address": "123.1.1.1",
      "accept_language": "en-US,en;q=0.8,fr;q=0.6",
      "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36"
    },
    "amount": "408.99",
    "session_id": "global-90ac917b99b70c04",
    "unique_token": "client-side-idempotency-token"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "base": [
      {
        "code": "processing_error",
        "message": "Your payment could not be processed at this time, please try again in a few minutes",
        "options": {
          "raw_gateway_error": "Service is unavailable."
        }
      }
    ]
  }
}

Attempting an authorization with a valid session_id, but an invalid credit card.

POST /admin/checkouts/#{token}/payments.json
{
  "payment": {
    "request_details": {
      "ip_address": "123.1.1.1",
      "accept_language": "en-US,en;q=0.8,fr;q=0.6",
      "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36"
    },
    "amount": "408.99",
    "session_id": "global-3259ed3c605104cf",
    "unique_token": "client-side-idempotency-token"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "credit_card": {
      "number": [
        {
          "code": "invalid",
          "message": "is invalid",
          "options": {}
        }
      ]
    }
  }
}

Attempting an authorization using a valid session_id stored in the vault.

POST /admin/checkouts/#{token}/payments.json
{
  "payment": {
    "request_details": {
      "ip_address": "123.1.1.1",
      "accept_language": "en-US,en;q=0.8,fr;q=0.6",
      "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36"
    },
    "amount": "408.99",
    "session_id": "global-9c7c786bc76b2816",
    "unique_token": "client-side-idempotency-token"
  }
}
View Response
HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/1068492618.json
Retry-After: 1
{
  "payment": {
    "id": 1068492618,
    "unique_token": "client-side-idempotency-token",
    "payment_processing_error_message": null,
    "fraudulent": false,
    "transaction": null,
    "credit_card": {
      "first_name": "Bob",
      "last_name": "Norman",
      "first_digits": "424242",
      "last_digits": "4242",
      "expiry_month": 9,
      "expiry_year": 2018
    },
    "checkout": {
      "completed_at": null,
      "created_at": "2012-10-12T07:05:27-04:00",
      "currency": "USD",
      "customer_id": 207119551,
      "device_id": null,
      "discount_code": null,
      "email": "bob.norman@hostmail.com",
      "location_id": null,
      "name": "#446514532",
      "note": "",
      "note_attributes": {
        "custom engraving": "Happy Birthday",
        "colour": "green"
      },
      "order_id": null,
      "order": null,
      "payment_due": "408.99",
      "payment_url": "https:\/\/app.local\/cardserver\/sessions",
      "payments": [
        {
          "id": 25428999,
          "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
          "payment_processing_error_message": null,
          "transaction": null,
          "credit_card": null
        },
        {
          "id": 1068492618,
          "unique_token": "client-side-idempotency-token",
          "payment_processing_error_message": null,
          "transaction": null,
          "credit_card": {
            "first_name": "Bob",
            "last_name": "Norman",
            "first_digits": "424242",
            "last_digits": "4242",
            "expiry_month": 9,
            "expiry_year": 2018
          }
        }
      ],
      "privacy_policy_url": null,
      "refund_policy_url": null,
      "requires_shipping": true,
      "reservation_time_left": 3600,
      "reservation_time": null,
      "source_identifier": null,
      "source_name": "web",
      "source_url": null,
      "subtotal_price": "398.00",
      "tax_exempt": false,
      "taxes_included": false,
      "terms_of_service_url": null,
      "token": "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "total_price": "408.99",
      "total_tax": "0.00",
      "updated_at": "2017-01-18T15:45:44-05:00",
      "user_id": null,
      "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "1bec1113d7cd1926",
          "key": "1bec1113d7cd1926",
          "product_id": 632910392,
          "variant_id": 49148385,
          "sku": "IPOD2008RED",
          "vendor": "Apple",
          "title": "IPod Nano - 8GB",
          "variant_title": "Red",
          "taxable": true,
          "requires_shipping": true,
          "price": "199.00",
          "compare_at_price": null,
          "line_price": "199.00",
          "properties": {},
          "quantity": 1,
          "grams": 200,
          "fulfillment_service": "manual",
          "applied_discounts": [
          ]
        },
        {
          "id": "902a33517a9a7d2c",
          "key": "902a33517a9a7d2c",
          "product_id": 632910392,
          "variant_id": 808950810,
          "sku": "IPOD2008PINK",
          "vendor": "Apple",
          "title": "IPod Nano - 8GB",
          "variant_title": "Pink",
          "taxable": true,
          "requires_shipping": true,
          "price": "199.00",
          "compare_at_price": null,
          "line_price": "199.00",
          "properties": {},
          "quantity": 1,
          "grams": 200,
          "fulfillment_service": "manual",
          "applied_discounts": [
          ]
        }
      ],
      "gift_cards": [
      ],
      "tax_lines": [
      ],
      "tax_manipulations": [
      ],
      "shipping_line": {
        "handle": "shopify-Standard%20Shipping-10.99",
        "price": "10.99",
        "title": "Standard Shipping"
      },
      "shipping_rate": {
        "id": "shopify-Standard%20Shipping-10.99",
        "price": "10.99",
        "title": "Standard Shipping"
      },
      "shipping_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "province_code": "KY",
        "country": "United States",
        "country_code": "US",
        "zip": "40202"
      },
      "credit_card": {
        "first_name": "Bob",
        "last_name": "Norman",
        "first_digits": "424242",
        "last_digits": "4242",
        "expiry_month": 9,
        "expiry_year": 2018
      },
      "billing_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "province_code": "KY",
        "country": "United States",
        "country_code": "US",
        "zip": "40202"
      },
      "applied_discount": null
    }
  }
}
GET /admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
Get the payment information for an existing payment

Retrive a payment with a failed transaction

GET /admin/checkouts/#{token}/payments/#{id}.json
View Response
HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
{
  "payment": {
    "id": 25428999,
    "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
    "payment_processing_error_message": null,
    "fraudulent": false,
    "transaction": {
      "amount": "408.99",
      "amount_in": null,
      "amount_out": null,
      "amount_rounding": null,
      "authorization": null,
      "created_at": "2017-01-18T15:45:37-05:00",
      "currency": "USD",
      "error_code": null,
      "gateway": "bogus",
      "id": 1068278463,
      "kind": "authorization",
      "message": null,
      "status": "failure",
      "test": false
    },
    "credit_card": null,
    "checkout": {
      "completed_at": null,
      "created_at": "2012-10-12T07:05:27-04:00",
      "currency": "USD",
      "customer_id": 207119551,
      "device_id": null,
      "discount_code": null,
      "email": "bob.norman@hostmail.com",
      "location_id": null,
      "name": "#446514532",
      "note": "",
      "note_attributes": {
        "custom engraving": "Happy Birthday",
        "colour": "green"
      },
      "order_id": null,
      "order": null,
      "payment_due": "408.99",
      "payment_url": "https:\/\/app.local\/cardserver\/sessions",
      "payments": [
        {
          "id": 25428999,
          "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
          "payment_processing_error_message": null,
          "transaction": {
            "amount": "408.99",
            "amount_in": null,
            "amount_out": null,
            "amount_rounding": null,
            "authorization": null,
            "created_at": "2017-01-18T15:45:37-05:00",
            "currency": "USD",
            "error_code": null,
            "gateway": "bogus",
            "id": 1068278463,
            "kind": "authorization",
            "message": null,
            "status": "failure",
            "test": false
          },
          "credit_card": null
        }
      ],
      "privacy_policy_url": null,
      "refund_policy_url": null,
      "requires_shipping": true,
      "reservation_time_left": 0,
      "reservation_time": null,
      "source_identifier": null,
      "source_name": "web",
      "source_url": null,
      "subtotal_price": "398.00",
      "tax_exempt": false,
      "taxes_included": false,
      "terms_of_service_url": null,
      "token": "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "total_price": "408.99",
      "total_tax": "21.49",
      "updated_at": "2012-10-12T07:05:27-04:00",
      "user_id": null,
      "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "1bec1113d7cd1926",
          "key": "1bec1113d7cd1926",
          "product_id": 632910392,
          "variant_id": 49148385,
          "sku": "IPOD2008RED",
          "vendor": "Apple",
          "title": "IPod Nano - 8GB",
          "variant_title": "Red",
          "taxable": true,
          "requires_shipping": true,
          "price": "199.00",
          "compare_at_price": null,
          "line_price": "199.00",
          "properties": {},
          "quantity": 1,
          "grams": 200,
          "fulfillment_service": "manual",
          "applied_discounts": [
          ]
        },
        {
          "id": "902a33517a9a7d2c",
          "key": "902a33517a9a7d2c",
          "product_id": 632910392,
          "variant_id": 808950810,
          "sku": "IPOD2008PINK",
          "vendor": "Apple",
          "title": "IPod Nano - 8GB",
          "variant_title": "Pink",
          "taxable": true,
          "requires_shipping": true,
          "price": "199.00",
          "compare_at_price": null,
          "line_price": "199.00",
          "properties": {},
          "quantity": 1,
          "grams": 200,
          "fulfillment_service": "manual",
          "applied_discounts": [
          ]
        }
      ],
      "gift_cards": [
      ],
      "tax_lines": [
        {
          "price": "21.49",
          "rate": 0.06,
          "title": "State Tax",
          "compare_at": 0.06
        }
      ],
      "tax_manipulations": [
      ],
      "shipping_line": {
        "handle": "shopify-Standard%20Shipping-10.99",
        "price": "10.99",
        "title": "Standard Shipping"
      },
      "shipping_rate": {
        "id": "shopify-Standard%20Shipping-10.99",
        "price": "10.99",
        "title": "Standard Shipping"
      },
      "shipping_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "province_code": "KY",
        "country": "United States",
        "country_code": "US",
        "zip": "40202"
      },
      "credit_card": {
        "first_name": "Bob",
        "last_name": "Norman",
        "first_digits": "1",
        "last_digits": "1",
        "expiry_month": 8,
        "expiry_year": 2042
      },
      "billing_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "province_code": "KY",
        "country": "United States",
        "country_code": "US",
        "zip": "40202"
      },
      "applied_discount": null
    }
  }
}

Retrive a payment with a succesful transaction

GET /admin/checkouts/#{token}/payments/#{id}.json
View Response
HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
{
  "payment": {
    "id": 25428999,
    "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
    "payment_processing_error_message": null,
    "fraudulent": false,
    "transaction": {
      "amount": "408.99",
      "amount_in": null,
      "amount_out": null,
      "amount_rounding": null,
      "authorization": null,
      "created_at": "2017-01-18T15:45:48-05:00",
      "currency": "USD",
      "error_code": null,
      "gateway": "bogus",
      "id": 1068278464,
      "kind": "authorization",
      "message": null,
      "status": "success",
      "test": false
    },
    "credit_card": null,
    "checkout": {
      "completed_at": null,
      "created_at": "2012-10-12T07:05:27-04:00",
      "currency": "USD",
      "customer_id": 207119551,
      "device_id": null,
      "discount_code": null,
      "email": "bob.norman@hostmail.com",
      "location_id": null,
      "name": "#446514532",
      "note": "",
      "note_attributes": {
        "custom engraving": "Happy Birthday",
        "colour": "green"
      },
      "order_id": null,
      "order": null,
      "payment_due": "408.99",
      "payment_url": "https:\/\/app.local\/cardserver\/sessions",
      "payments": [
        {
          "id": 25428999,
          "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
          "payment_processing_error_message": null,
          "transaction": {
            "amount": "408.99",
            "amount_in": null,
            "amount_out": null,
            "amount_rounding": null,
            "authorization": null,
            "created_at": "2017-01-18T15:45:48-05:00",
            "currency": "USD",
            "error_code": null,
            "gateway": "bogus",
            "id": 1068278464,
            "kind": "authorization",
            "message": null,
            "status": "success",
            "test": false
          },
          "credit_card": null
        }
      ],
      "privacy_policy_url": null,
      "refund_policy_url": null,
      "requires_shipping": true,
      "reservation_time_left": 0,
      "reservation_time": null,
      "source_identifier": null,
      "source_name": "web",
      "source_url": null,
      "subtotal_price": "398.00",
      "tax_exempt": false,
      "taxes_included": false,
      "terms_of_service_url": null,
      "token": "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "total_price": "408.99",
      "total_tax": "21.49",
      "updated_at": "2012-10-12T07:05:27-04:00",
      "user_id": null,
      "web_url": "https:\/\/checkout.local\/690933842\/checkouts\/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "1bec1113d7cd1926",
          "key": "1bec1113d7cd1926",
          "product_id": 632910392,
          "variant_id": 49148385,
          "sku": "IPOD2008RED",
          "vendor": "Apple",
          "title": "IPod Nano - 8GB",
          "variant_title": "Red",
          "taxable": true,
          "requires_shipping": true,
          "price": "199.00",
          "compare_at_price": null,
          "line_price": "199.00",
          "properties": {},
          "quantity": 1,
          "grams": 200,
          "fulfillment_service": "manual",
          "applied_discounts": [
          ]
        },
        {
          "id": "902a33517a9a7d2c",
          "key": "902a33517a9a7d2c",
          "product_id": 632910392,
          "variant_id": 808950810,
          "sku": "IPOD2008PINK",
          "vendor": "Apple",
          "title": "IPod Nano - 8GB",
          "variant_title": "Pink",
          "taxable": true,
          "requires_shipping": true,
          "price": "199.00",
          "compare_at_price": null,
          "line_price": "199.00",
          "properties": {},
          "quantity": 1,
          "grams": 200,
          "fulfillment_service": "manual",
          "applied_discounts": [
          ]
        }
      ],
      "gift_cards": [
      ],
      "tax_lines": [
        {
          "price": "21.49",
          "rate": 0.06,
          "title": "State Tax",
          "compare_at": 0.06
        }
      ],
      "tax_manipulations": [
      ],
      "shipping_line": {
        "handle": "shopify-Standard%20Shipping-10.99",
        "price": "10.99",
        "title": "Standard Shipping"
      },
      "shipping_rate": {
        "id": "shopify-Standard%20Shipping-10.99",
        "price": "10.99",
        "title": "Standard Shipping"
      },
      "shipping_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "province_code": "KY",
        "country": "United States",
        "country_code": "US",
        "zip": "40202"
      },
      "credit_card": {
        "first_name": "Bob",
        "last_name": "Norman",
        "first_digits": "1",
        "last_digits": "1",
        "expiry_month": 8,
        "expiry_year": 2042
      },
      "billing_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "province_code": "KY",
        "country": "United States",
        "country_code": "US",
        "zip": "40202"
      },
      "applied_discount": null
    }
  }
}
GET /admin/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/count.json
Count the number of Payments attempted on a Checkout

Counting Payments on a Checkout

GET /admin/checkouts/#{token}/payments/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 1
}
POST https://elb.deposit.shopifycs.com/sessions
Credit cards cannot be sent to the checkout API directly. They must be sent to our card vault which in response will return an id. This id can then be used when calling the checkout API's PATCH {token}.json end-point. An id is only valid for a single call to the endpoint. The card vault has a static url and is located at https://elb.deposit.shopifycs.com/sessions. It is also provided via the payment_url attribute. The card vault requests should be completed with Content-Type: application/json and Accept: application/json.

Create a payment session with the specified billing details and checkout.

POST https://elb.deposit.shopifycs.com/sessions
{
  "credit_card": {
    "number": "1",
    "first_name": "John",
    "last_name": "Smith",
    "month": "5",
    "year": "15",
    "verification_value": "123"
  }
}
View Response
HTTP/1.1 200 OK
{
  "id": "83hru3obno3hu434b3u"
}