PATCH
/
api
/
v2
/
storefront
/
checkout
curl --request PATCH \
  --url https://demo.spreecommerce.org/api/v2/storefront/checkout \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: <api-key>' \
  --data '{
  "order": {
    "email": "john@snow.org",
    "bill_address_attributes": {
      "firstname": "John",
      "lastname": "Snow",
      "address1": "7735 Old Georgetown Road",
      "city": "Bethesda",
      "phone": "3014445002",
      "zipcode": "20814",
      "state_name": "MD",
      "country_iso": "US"
    },
    "ship_address_attributes": {
      "firstname": "John",
      "lastname": "Snow",
      "address1": "7735 Old Georgetown Road",
      "city": "Bethesda",
      "phone": "3014445002",
      "zipcode": "20814",
      "state_name": "MD",
      "country_iso": "US"
    }
  }
}'
{
  "data": {
    "id": "17",
    "type": "cart",
    "attributes": {
      "number": "R233871560",
      "item_total": "0.0",
      "total": "0.0",
      "ship_total": "0.0",
      "adjustment_total": "0.0",
      "created_at": "2021-09-28T22:15:07.471Z",
      "updated_at": "2021-09-28T22:15:07.471Z",
      "completed_at": null,
      "included_tax_total": "0.0",
      "additional_tax_total": "0.0",
      "display_additional_tax_total": "$0.00",
      "display_included_tax_total": "$0.00",
      "tax_total": "0.0",
      "currency": "USD",
      "state": "cart",
      "token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
      "email": null,
      "display_item_total": "$0.00",
      "display_ship_total": "$0.00",
      "display_adjustment_total": "$0.00",
      "display_tax_total": "$0.00",
      "promo_total": "0.0",
      "display_promo_total": "$0.00",
      "item_count": 0,
      "special_instructions": null,
      "display_total": "$0.00",
      "pre_tax_item_amount": "0.0",
      "display_pre_tax_item_amount": "$0.00",
      "pre_tax_total": "0.0",
      "display_pre_tax_total": "$0.00",
      "shipment_state": null,
      "payment_state": null
    },
    "relationships": {
      "line_items": {
        "data": []
      },
      "variants": {
        "data": []
      },
      "promotions": {
        "data": []
      },
      "payments": {
        "data": []
      },
      "shipments": {
        "data": []
      },
      "user": {
        "data": null
      },
      "billing_address": {
        "data": null
      },
      "shipping_address": {
        "data": null
      }
    }
  }
}

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.

The body is of type object.

Response

200
application/vnd.api+json

200 Success - Returns the cart object.

The response is of type object.

PATCH
/
api
/
v2
/
storefront
/
checkout
curl --request PATCH \
  --url https://demo.spreecommerce.org/api/v2/storefront/checkout \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: <api-key>' \
  --data '{
  "order": {
    "email": "john@snow.org",
    "bill_address_attributes": {
      "firstname": "John",
      "lastname": "Snow",
      "address1": "7735 Old Georgetown Road",
      "city": "Bethesda",
      "phone": "3014445002",
      "zipcode": "20814",
      "state_name": "MD",
      "country_iso": "US"
    },
    "ship_address_attributes": {
      "firstname": "John",
      "lastname": "Snow",
      "address1": "7735 Old Georgetown Road",
      "city": "Bethesda",
      "phone": "3014445002",
      "zipcode": "20814",
      "state_name": "MD",
      "country_iso": "US"
    }
  }
}'
{
  "data": {
    "id": "17",
    "type": "cart",
    "attributes": {
      "number": "R233871560",
      "item_total": "0.0",
      "total": "0.0",
      "ship_total": "0.0",
      "adjustment_total": "0.0",
      "created_at": "2021-09-28T22:15:07.471Z",
      "updated_at": "2021-09-28T22:15:07.471Z",
      "completed_at": null,
      "included_tax_total": "0.0",
      "additional_tax_total": "0.0",
      "display_additional_tax_total": "$0.00",
      "display_included_tax_total": "$0.00",
      "tax_total": "0.0",
      "currency": "USD",
      "state": "cart",
      "token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
      "email": null,
      "display_item_total": "$0.00",
      "display_ship_total": "$0.00",
      "display_adjustment_total": "$0.00",
      "display_tax_total": "$0.00",
      "promo_total": "0.0",
      "display_promo_total": "$0.00",
      "item_count": 0,
      "special_instructions": null,
      "display_total": "$0.00",
      "pre_tax_item_amount": "0.0",
      "display_pre_tax_item_amount": "$0.00",
      "pre_tax_total": "0.0",
      "display_pre_tax_total": "$0.00",
      "shipment_state": null,
      "payment_state": null
    },
    "relationships": {
      "line_items": {
        "data": []
      },
      "variants": {
        "data": []
      },
      "promotions": {
        "data": []
      },
      "payments": {
        "data": []
      },
      "shipments": {
        "data": []
      },
      "user": {
        "data": null
      },
      "billing_address": {
        "data": null
      },
      "shipping_address": {
        "data": null
      }
    }
  }
}

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.

The body is of type object.

Response

200
application/vnd.api+json

200 Success - Returns the cart object.

The response is of type object.