Skip to main content

Checkout API

POST 
/v2/carts/:cartID/checkout

When a Cart is ready for checkout, you can convert the cart to an order. The cart remains and can be modified and checked out again if required.

A cart can be checked out with a customer ID, customer object, or with an account by authenticating with the Client Credentials Token.

After a successful checkout, a response that contains the order is returned. If the cart is linked to a shipping group, the shipping group is also associated with the order after checkout.

You can checkout using one of the following methods:

  • Customer ID: You can checkout a cart with an existing customer ID.
  • Guest Checkout (Checkout with Customer Object): You can checkout a cart with an associated customer name and email.
  • Checkout with Account: The shopper authenticates with the Client Credentials Token.
  • Checkout with Account Management Authentication Token: The shopper authenticates with the Implicit Token and the EP-Account-Management-Authentication-Token.
note
  • The cart currency is set when the first item is added to the cart.
  • The product being added to the cart requires a price in the same currency as the other items in the cart. The API returns a 400 error if a price is not defined in the correct currency.
  • To ensure that a free gift is automatically applied to an order, set the promotion to automatic. The checkout process will not be successful if free gift items are out of stock. See Errors section.
caution
  • By default, carts are automatically deleted 7 days after the last update. You can change this setting by updating cart settings.
  • Your inventory is modified during checkout and payment of an order. For more information about the changes in the inventory, see the Inventory section.

You can pass order_number and external_ref in the checkout endpoint or when updating an order. The order_number is an optional, user-managed field that is used as an alternative to order_id. When processing transactions through Authorize.net, the order_number is sent instead of the order_id, and it will appear in the invoice number section. If no order_number is provided, the order_id is sent to Authorize.net on payment by default. There are no duplication restrictions on the order_number value.

Next Steps​

After a cart has been converted to an Order using either of the previous methods, you most likely want to capture payment for order. See Paying for an Order.

Errors​

The following error response is returned during checkout when an eligible item is added to the cart, and the free gift is out of stock.

{
    "errors": [
        {
            "status": 400,
            "title": "Insufficient stock",
            "detail": "There is not enough stock to add gift2 to your cart",
            "meta": {
                "id": "f2b68648-9621-45a3-aed6-1b526b0f5beb",
                "sku": "gift2"
            }
        }
    ]
}

Request​

Path Parameters

    cartID stringrequired

    The ID of the cart that you want to checkout.

Header Parameters

    EP-Account-Management-Authentication-Token string

    An account management authentication token that identifies the authenticated account member.

Body

    oneOf
    data object
    order_number string

    A user-managed, optional field used as an alternative to the existing order_id. If provided, the order-number will be sent to Authorize.net instead of the order_id, and will appear as the invoice number in Authorize.net transactions.

    external_ref string

    An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.

    customer object
    id string

    The ID of the customer.

    billing_address object
    company_name string

    Company name of the billing recipient.

    country stringrequired

    Specifies the country of the billing address.

    county string

    Specifies the county of the billing address.

    first_name stringrequired

    First name of the billing recipient.

    last_name stringrequired

    Last name of the billing recipient.

    line_1 stringrequired

    First line of the billing address.

    line_2 string

    Second line of the billing address.

    postcode stringrequired

    Postcode of the billing address.

    region stringrequired

    Specifies state, province, or region of the billing address.

    shipping_address object
    company_name string

    Company of the shipping recipient.

    country stringrequired

    Specifies the country of the shipping address.

    county string

    Specifies the county of the shipping address.

    first_name stringrequired

    First name of the shipping recipient.

    last_name stringrequired

    Last name of the shipping recipient.

    line_1 stringrequired

    First line of the shipping address.

    line_2 string

    Second line of the shipping address.

    postcode stringrequired

    Post code of the shipping address.

    region stringrequired

    Specifies the state, province, or region of the shipping address.

Responses​

OK

Schema
    data object
    type string

    Specifies the type of object being returned. You must use order.

    order_number string

    Specifies a user-managed, optional field used as an alternative to the existing order_id. If provided, the order-number will be sent to Authorize.net instead of the order_id, and will appear as the invoice number in Authorize.net transactions.

    external_ref string

    An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.

    id uuid

    Specifies the unique identifier of the order.

    status string

    Specifies the status of the order, such as incomplete, complete, processing, or cancelled.

    payment string

    Specifies the status of the payment, such as unpaid, authorized, paid, or refunded.

    shipping string

    Specifies the status of the shipment, such as fulfilled or unfulfilled.

    anonymized boolean

    Specifies if the order is anonymized.

    meta object
    timestamps object
    created_at string

    The date this was created.

    updated_at

    The date this was last updated.

    with_tax object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    without_tax object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    tax object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    discount object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    paid object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    authorized object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    without_discount object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    billing_address object
    company_name string

    Company name of the billing recipient.

    country stringrequired

    Specifies the country of the billing address.

    county string

    Specifies the county of the billing address.

    first_name stringrequired

    First name of the billing recipient.

    last_name stringrequired

    Last name of the billing recipient.

    line_1 stringrequired

    First line of the billing address.

    line_2 string

    Second line of the billing address.

    postcode stringrequired

    Postcode of the billing address.

    region stringrequired

    Specifies state, province, or region of the billing address.

    contact object
    email string

    The email address of the contact.

    name string

    The name of the contact.

    shipping_address object
    company_name string

    Company of the shipping recipient.

    country stringrequired

    Specifies the country of the shipping address.

    county string

    Specifies the county of the shipping address.

    first_name stringrequired

    First name of the shipping recipient.

    last_name stringrequired

    Last name of the shipping recipient.

    line_1 stringrequired

    First line of the shipping address.

    line_2 string

    Second line of the shipping address.

    postcode stringrequired

    Post code of the shipping address.

    region stringrequired

    Specifies the state, province, or region of the shipping address.

Loading...