Update Checkout

The Update Checkout endpoint allows you to manage the typical stages of an e-commerce checkout system.

Authorizations

X-Spree-Order-Token

string

header

required

Order token to authorize Cart and Checkout requests.

How to obtain X-Spree-Order-Token

Query Parameters

include

string

Specify the related resources you would like to receive in the response body. More Information.

Body

application/vnd.api+json

##### Add Customer Details Adding customer details is achieved by passing the customer-related attributes shown in the corresponding request body example. ##### Add Shipping Rates To add shipping rates, you will need a shipment associated with the checkout. If you do not have any shipments follow the steps below: 1. First, ensure your cart has items added via the **Add an Item to Cart** endpoint. 2. Next, ensure the checkout has a shipping address set, you can set this by running the *Add Customer Details* example above. 3. Next run the **Advance Checkout** endpoint, this will create shipments for the items in the cart and users shipping destination. Use the **List Shipping Rates** endpoint to find the shipments and shipping rates available for this checkout. Note the shipment `id` and shipping_rate `id`; use these values to populate your request body. ##### Add a Payment To add a payment method, you must find the available payment methods by running the **List Payment Methods** endpoint, each payment method has its own set of source attribute requirements. In the example shown, we have used the source attributes for a card payment. Pass the `payment_method_id` and `source_attribute` hash containing the required attributes for the selected payment method.

order

object

Show child attributes

order.email

string

Example:

"[e-mail]"

order.bill_address_attributes

object

Show child attributes

order.bill_address_attributes.firstname

string

required

order.bill_address_attributes.lastname

string

required

order.bill_address_attributes.address1

string

required

Street address

order.bill_address_attributes.city

string

required

City, town

order.bill_address_attributes.country_iso

string

required

Country ISO (2-chars) or ISO3 (3-chars) code. List of all codes

order.bill_address_attributes.address2

string

Additional address information, floor no etc

order.bill_address_attributes.phone

string

order.bill_address_attributes.zipcode

string

Valid zipcode, will be validated against the selected Country

order.bill_address_attributes.state_name

string

State/region/province 2 letter abbreviation

order.bill_address_attributes.company

string

Company name

Example:

"Paper Street Soap Co."

order.bill_address_attributes.label

string

The internal name for this address (Work, Home)

Example:

"Work"

Example:

{
  "firstname": "John",
  "lastname": "Snow",
  "address1": "7735 Old Georgetown Road",
  "address2": "2nd Floor",
  "city": "Bethesda",
  "phone": "3014445002",
  "zipcode": "20814",
  "state_name": "MD",
  "country_iso": "US"
}

order.ship_address_attributes

object

Show child attributes

order.ship_address_attributes.firstname

string

required

order.ship_address_attributes.lastname

string

required

order.ship_address_attributes.address1

string

required

Street address

order.ship_address_attributes.city

string

required

City, town

order.ship_address_attributes.country_iso

string

required

Country ISO (2-chars) or ISO3 (3-chars) code. List of all codes

order.ship_address_attributes.address2

string

Additional address information, floor no etc

order.ship_address_attributes.phone

string

order.ship_address_attributes.zipcode

string

Valid zipcode, will be validated against the selected Country

order.ship_address_attributes.state_name

string

State/region/province 2 letter abbreviation

order.ship_address_attributes.company

string

Company name

Example:

"Paper Street Soap Co."

order.ship_address_attributes.label

string

The internal name for this address (Work, Home)

Example:

"Work"

Example:

{
  "firstname": "John",
  "lastname": "Snow",
  "address1": "7735 Old Georgetown Road",
  "address2": "2nd Floor",
  "city": "Bethesda",
  "phone": "3014445002",
  "zipcode": "20814",
  "state_name": "MD",
  "country_iso": "US"
}

order.shipments_attributes

object[]

Show child attributes

order.shipments_attributes.id

string

required

The Shipment id

Example:

"3"

order.shipments_attributes.selected_shipping_rate_id

string

required

The Shipping Rate id

Example:

"10"

order.payments_attributes

object[]

Show child attributes

order.payments_attributes.payment_method_id

string

required

The id of the Payment Method

Example:

"1"

order.payments_attributes.source_attributes

object

required

Show child attributes

order.payments_attributes.source_attributes.gateway_payment_profile_id

string

order.payments_attributes.source_attributes.month

number

order.payments_attributes.source_attributes.year

number

order.payments_attributes.source_attributes.cc_type

string

order.payments_attributes.source_attributes.name

string

Response

200

application/vnd.api+json

200 Success - Returns the `cart` object.

data

object

required

The Cart provides a central place to collect information about an order, including line items, adjustments, payments, addresses, and shipments. Read more in Spree docs

Show child attributes

data.id

string

required

Example:

"1"

data.type

string

default:cart

required

data.attributes

object

required

Show child attributes

data.attributes.number

string

Used as the {order_number} value in the URI to identify a completed order.

Example:

"R123456789"

data.attributes.token

string

Used for authorizing actions through the X-Spree-Order-Token API Key.

Example:

"eL0nVxe1Aum-Qr9-UkryPA1633360128076"

data.attributes.item_total

string

Example:

"19.99"

data.attributes.total

string

Example:

"29.99"

data.attributes.ship_total

string

Example:

"0.0"

data.attributes.adjustment_total

string

Example:

"10.0"

data.attributes.created_at

string

Example:

"2020-02-16T07:14:54.617Z"

data.attributes.updated_at

string

Example:

"2020-02-16T07:14:54.617Z"

data.attributes.completed_at

string | null

data.attributes.included_tax_total

string

Example:

"5.00"

data.attributes.additional_tax_total

string

Example:

"5.0"

data.attributes.display_additional_tax_total

string

Example:

"$5.00"

data.attributes.tax_total

string

Example:

"10.0"

data.attributes.currency

string

Example:

"USD"

data.attributes.state

enum<string>

State of the Cart in the Checkout flow. Please see <a href="/developer/core-concepts/orders#the-order-state-machine"> The Order State machine </a> for a full list with description.

Available options:

cart,

address,

delivery,

payment,

confirm,

complete

Example:

"cart"

data.attributes.email

string | null

Example:

"[e-mail]"

data.attributes.display_item_total

string

Example:

"$19.99"

data.attributes.display_ship_total

string

Example:

"$19.99"

data.attributes.display_adjustment_total

string

Example:

"$10.00"

data.attributes.display_included_tax_total

string

Example:

"$5.00"

data.attributes.promo_total

string

Example:

"-10.0"

data.attributes.display_promo_total

string

Example:

"-$10.00"

data.attributes.item_count

number

Total quantity number of all items added to the Cart

Required range: x >= 0

Example:

2

data.attributes.special_instructions

string | null

Message added by the Customer

Example:

"Please wrap it as a gift"

data.attributes.display_total

string

Example:

"$29.99"

data.attributes.pre_tax_item_amount

string

Example:

"17.00"

data.attributes.display_pre_tax_item_amount

string

Example:

"$17.00"

data.attributes.pre_tax_total

string

Example:

"20.00"

data.attributes.display_tax_total

string

Example:

"$10.00"

data.attributes.display_pre_tax_total

string

Example:

"$20.00"

data.attributes.shipment_state

enum<string> | null

Overall state of the Shipments. Please see <a href="/developer/core-concepts/orders#order-shipment-states-1"> Order Shipments states </a> for a full list with description.

Available options:

pending,

backorder,

canceled,

partial,

ready,

shipped

data.attributes.payment_state

enum<string> | null

Overall state of the Payments. Please see <a href="/developer/core-concepts/orders#order-payment-states"> Order Payments states </a> for a full list with description.

Available options:

balance_due,

credit_owed,

failed,

paid,

void

data.relationships

object

required

Show child attributes

data.relationships.line_items

object

Show child attributes

data.relationships.line_items.data

array

Show child attributes

data.relationships.line_items.data.id

string

required

data.relationships.line_items.data.type

string

required

data.relationships.variants

object

Show child attributes

data.relationships.variants.data

array

Show child attributes

data.relationships.variants.data.id

string

required

data.relationships.variants.data.type

string

required

data.relationships.promotions

object

Show child attributes

data.relationships.promotions.data

array

Show child attributes

data.relationships.promotions.data.id

string

required

data.relationships.promotions.data.type

string

required

data.relationships.payments

object

Show child attributes

data.relationships.payments.data

array

Show child attributes

data.relationships.payments.data.id

string

required

data.relationships.payments.data.type

string

required

data.relationships.shipments

object

Show child attributes

data.relationships.shipments.data

array

Show child attributes

data.relationships.shipments.data.id

string

required

data.relationships.shipments.data.type

string

required

data.relationships.user

object

Show child attributes

data.relationships.user.data

object | null

Show child attributes

data.relationships.user.data.id

string

required

data.relationships.user.data.type

string

required

data.relationships.billing_address

object

Show child attributes

data.relationships.billing_address.data

object | null

Show child attributes

data.relationships.billing_address.data.id

string

required

data.relationships.billing_address.data.type

string

required

data.relationships.shipping_address

object

Show child attributes

data.relationships.shipping_address.data

object | null

Show child attributes

data.relationships.shipping_address.data.id

string

required

data.relationships.shipping_address.data.type

string

required

included

object[]

• Line Item
• Promotion
• Variant
• Payment
• User
• Shipment
• Digital Link
• Product

Show child attributes

included.id

string

required

Example:

"1"

included.type

string

default:line_item

required

included.attributes

object

required

Show child attributes

included.attributes.name

string

Example:

"Sample product"

included.attributes.quantity

integer

Example:

1

included.attributes.slug

string

Example:

"sample-product"

included.attributes.options_text

string

Example:

"Size: small, Color: red"

included.attributes.price

string

Price of Product per quantity

Example:

"125.0"

included.attributes.currency

string

Example:

"USD"

included.attributes.display_price

string

Price of Product per quantity

Example:

"$125.00"

included.attributes.total

string

Total price of Line Item including adjastments, promotions and taxes

Example:

"250.0"

included.attributes.display_total

string

Total price of Line Item including adjastments, promotions and taxes

Example:

"$250.00"

included.attributes.adjustment_total

string

TBD

Example:

"10.0"

included.attributes.display_adjustment_total

string

TBD

Example:

"$10.00"

included.attributes.additional_tax_total

string

Example:

"5.0"

included.attributes.display_additional_tax_total

string

Example:

"$5.00"

included.attributes.discounted_amount

string

Example:

"125.0"

included.attributes.display_discounted_amount

string

Example:

"$125.00"

included.attributes.pre_tax_amount

string

Example:

"125.0"

included.attributes.display_pre_tax_amount

string

Example:

"$125.00"

included.attributes.promo_total

string

Example:

"-5.0"

included.attributes.display_promo_total

string

included.attributes.included_tax_total

string

Taxes included in the price, eg. VAT

Example:

"0.0"

included.attributes.display_inluded_tax_total

string

Example:

"$0.00"

included.attributes.public_metadata

object

The public metadata for the Line Item.

Example:

{ "recommended_by_us": true }

included.relationships

object

required

Show child attributes

included.relationships.variant

object

Show child attributes

included.relationships.variant.data

object | null

Show child attributes

included.relationships.variant.data.id

string

required

included.relationships.variant.data.type

string

required

included.relationships.digital_links

object

Show child attributes

included.relationships.digital_links.data

array

Show child attributes

included.relationships.digital_links.data.id

string

required

included.relationships.digital_links.data.type

string

required