Checkouts API

Introduction

The checkout API functionality can be used to advance an existing order’s state. Sending a PUT request to /api/checkouts/:number will advance an order’s state or, failing that, report any errors.

The following sections will walk through creating a new order and advancing an order from its cart state to its complete state.

Creating a blank order

To create a new, empty order, make this request:

POST /api/orders.json

Response

Status: 201 Created
{
  "id": 4,
  "number": "R307128032",
  "item_total": "0.0",
  "total": "0.0",
  "ship_total": "0.0",
  "state": "cart",
  "adjustment_total": "0.0",
  "user_id": 1,
  "created_at": "2014-07-06T18:52:33.724Z",
  "updated_at": "2014-07-06T18:52:33.752Z",
  "completed_at": null,
  "payment_total": "0.0",
  "shipment_state": null,
  "payment_state": null,
  "email": "[email protected]",
  "special_instructions": null,
  "channel": "spree",
  "included_tax_total": "0.0",
  "additional_tax_total": "0.0",
  "display_included_tax_total": "$0.00",
  "display_additional_tax_total": "$0.00",
  "tax_total": "0.0",
  "currency": "USD",
  "display_item_total": "$0.00",
  "total_quantity": 0,
  "display_total": "$0.00",
  "display_ship_total": "$0.00",
  "display_tax_total": "$0.00",
  "token": "n0kZnXjRfjnhZMY5ijhiOA",
  "checkout_steps": [
    "address",
    "delivery",
    "complete"
  ],
  "permissions": {
    "can_update": true
  },
  "bill_address": null,
  "ship_address": null,
  "line_items": [],
  "payments": [],
  "shipments": [],
  "adjustments": []
}

Any time you update the order or move a checkout step you’ll get a response similar as above along with the new associated objects. e.g. addresses, payments, shipments.

Add line items to an order

Pass line item attributes like this:

{
  "line_item": {
    "variant_id": 1,
    "quantity": 5
  }
}

to this api endpoint:

POST /api/orders/:number/line_items.json
Status: 201 Created
{
  "id": 3,
  "quantity": 5,
  "price": "15.99",
  "variant_id": 1,
  "single_display_amount": "$15.99",
  "display_amount": "$79.95",
  "total": "79.95",
  "variant": {
    "id": 1,
    "name": "Ruby on Rails Tote",
    "sku": "ROR-00011",
    "price": "15.99",
    "weight": "0.0",
    "height": null,
    "width": null,
    "depth": null,
    "is_master": true,
    "cost_price": "17.0",
    "slug": "ruby-on-rails-tote",
    "description": "Nihil et itaque adipisci sed ea dolorum.",
    "track_inventory": true,
    "display_price": "$15.99",
    "options_text": "",
    "in_stock": true,
    "option_values": [],
    "images": [
      {
        "id": 21,
        "position": 1,
        "attachment_content_type": "image/jpeg",
        "attachment_file_name": "ror_tote.jpeg",
        "type": "Spree::Image",
        "attachment_updated_at": "2014-07-06T18:37:34.534Z",
        "attachment_width": 360,
        "attachment_height": 360,
        "alt": null,
        "viewable_type": "Spree::Variant",
        "viewable_id": 1,
        "mini_url": "/spree/products/21/mini/ror_tote.jpeg?1404671854",
        "small_url": "/spree/products/21/small/ror_tote.jpeg?1404671854",
        "product_url": "/spree/products/21/product/ror_tote.jpeg?1404671854",
        "large_url": "/spree/products/21/large/ror_tote.jpeg?1404671854"
      },
      {
        "id": 22,
        "position": 2,
        "attachment_content_type": "image/jpeg",
        "attachment_file_name": "ror_tote_back.jpeg",
        "type": "Spree::Image",
        "attachment_updated_at": "2014-07-06T18:37:34.921Z",
        "attachment_width": 360,
        "attachment_height": 360,
        "alt": null,
        "viewable_type": "Spree::Variant",
        "viewable_id": 1,
        "mini_url": "/spree/products/22/mini/ror_tote_back.jpeg?1404671854",
        "small_url": "/spree/products/22/small/ror_tote_back.jpeg?1404671854",
        "product_url": "/spree/products/22/product/ror_tote_back.jpeg?1404671854",
        "large_url": "/spree/products/22/large/ror_tote_back.jpeg?1404671854"
      }
    ],
    "product_id": 1
  },
  "adjustments": []
}

Updating an order

To update an order you must be authenticated as the order’s user, and perform a request like this:

PUT /api/orders/:number.json

If you know the order’s token, then you can also update the order:

PUT /api/orders/:number.json?order_token=abcdef123456

Requests performed as a non-admin or non-authorized user will be met with a 401 response from this action.

Address

To transition an order to its next step, make a request like this:

PUT /api/checkouts/:number/next.json

If the request is successfull you’ll get a 200 response using the same order template shown when creating the order with the state updated. See example of failed response below.

Failed Response

Status: 422 Unprocessable Entity
{
  "error": "The order could not be transitioned. Please fix the errors and try again.",
  "errors": {
    "email": [
      "can't be blank"
    ]
  }
}

Delivery

To advance to the next state, delivery, the order will first need both a shipping and billing address.

In order to update the addresses, make this request with the necessary parameters:

PUT /api/checkouts/:number.json

As an example, here are the required address attributes and how they should be formatted:

{
  "order": {
    "bill_address_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "address1": "7735 Old Georgetown Road",
      "city": "Bethesda",
      "phone": "3014445002",
      "zipcode": "20814",
      "state_id": 48,
      "country_id": 49
    },
    "ship_address_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "address1": "7735 Old Georgetown Road",
      "city": "Bethesda",
      "phone": "3014445002",
      "zipcode": "20814",
      "state_id": 48,
      "country_id": 49
    }
  }
}

Response

Once valid address information has been submitted, the shipments and shipping rates available for this order will be returned inside a shipments key inside the order, as seen below:

Status: 200 OK
{
  ...
  "shipments": [
    {
      "id": 4,
      "tracking": null,
      "number": "H22035832422",
      "cost": "15.0",
      "shipped_at": null,
      "state": "pending",
      "order_id": "R181010551",
      "stock_location_name": "default",
      "shipping_rates": [
        {
          "id": 10,
          "name": "UPS Ground (USD)",
          "cost": "5.0",
          "selected": false,
          "shipping_method_id": 1,
          "display_cost": "$5.00"
        },
        {
          "id": 11,
          "name": "UPS Two Day (USD)",
          "cost": "10.0",
          "selected": false,
          "shipping_method_id": 2,
          "display_cost": "$10.00"
        },
        {
          "id": 12,
          "name": "UPS One Day (USD)",
          "cost": "15.0",
          "selected": true,
          "shipping_method_id": 3,
          "display_cost": "$15.00"
        }
      ],
      "selected_shipping_rate": {
        "id": 12,
        "name": "UPS One Day (USD)",
        "cost": "15.0",
        "selected": true,
        "shipping_method_id": 3,
        "display_cost": "$15.00"
      },
      "shipping_methods": [
        {
          "id": 1,
          "name": "UPS Ground (USD)",
          "zones": [
            {
              "id": 2,
              "name": "North America",
              "description": "USA + Canada"
            }
          ],
          "shipping_categories": [
            {
              "id": 1,
              "name": "Default"
            }
          ]
        },
        {
          "id": 2,
          "name": "UPS Two Day (USD)",
          "zones": [
            {
              "id": 2,
              "name": "North America",
              "description": "USA + Canada"
            }
          ],
          "shipping_categories": [
            {
              "id": 1,
              "name": "Default"
            }
          ]
        },
        {
          "id": 3,
          "name": "UPS One Day (USD)",
          "zones": [
            {
              "id": 2,
              "name": "North America",
              "description": "USA + Canada"
            }
          ],
          "shipping_categories": [
            {
              "id": 1,
              "name": "Default"
            }
          ]
        }
      ],
      "manifest": [
        {
          "quantity": 3,
          "states": {
            "on_hand": 3
          },
          "variant_id": 1
        }
      ]
    }
  ],
  ...

Payment

To advance to the next state, payment, you will need to select a shipping rate for each shipment for the order. These were returned when transitioning to the delivery step. If you need want to see them again, make the following request:

GET /api/orders/:number.json

Spree will select a shipping rate by default so you can advance to the payment state by making this request:

PUT /api/checkouts/:number/next.json

If the order doesn’t have an assigned shipping rate, or you want to choose a different shipping rate make the following request to select one and advance the order’s state:

PUT /api/checkouts/:number.json

With parameters such as these:

{
  "order": {
    "shipments_attributes": [
      {
        "selected_shipping_rate_id": 1,
        "id": 1
      }
    ]
  }
}

Please ensure you select a shipping rate for each shipment in the order. In the request above, the selected_shipping_rate_id should be the id of the shipping rate you want to use and the id should be the id of the shipment you are choosing this shipping rate for.

Confirm

To advance to the next state, confirm, the order will need to have a payment. You can create a payment by passing in parameters such as this:

{
  "order": {
    "payments_attributes": [
      {
        "payment_method_id": "1"
      }
    ]
  },
  "payment_source": {
    "1": {
      "number": "4111111111111111",
      "month": "1",
      "year": "2017",
      "verification_value": "123",
      "name": "John Smith"
    }
  }
}

The numbered key in the payment_source hash directly corresponds to the payment_method_id attribute within the payment_attributes key.

You can also use an existing card for the order by submitting the credit card id. See an example request:

{
  "order": {
    "existing_card": "1"
  }
}

Please note that for 2-2-stable checkout api the request body to submit a payment via api/checkouts is slight different. See example:

{
  "order": {
    "payments_attributes": {
      "payment_method_id": "1"
    },
    "payment_source": {
      "1": {
        "number": "4111111111111111",
        "month": "1",
        "year": "2017",
        "verification_value": "123",
        "name": "John Smith"
      }
    }
  }
}

If the order already has a payment, you can advance it to the confirm state by making this request:

PUT /api/checkouts/:number.json

For more information on payments, view the payments documentation.

Response

Status: 200 OK
{
  ...
  "state": "confirm",
  ...
  "payments": [
    {
      "id": 3,
      "source_type": "Spree::CreditCard",
      "source_id": 2,
      "amount": "65.37",
      "display_amount": "$65.37",
      "payment_method_id": 1,
      "response_code": null,
      "state": "checkout",
      "avs_response": null,
      "created_at": "2014-07-06T19:55:08.308Z",
      "updated_at": "2014-07-06T19:55:08.308Z",
      "payment_method": {
        "id": 1,
        "name": "Credit Card",
        "environment": "development"
      },
      "source": {
        "id": 2,
        "month": "1",
        "year": "2017",
        "cc_type": null,
        "last_digits": "1111",
        "name": "John Smith"
      }
    }
  ],
  ...

Complete

Now the order is ready to be advanced to the final state, complete. To accomplish this, make this request:

PUT /api/checkouts/:number.json

You should get a 200 response with all the order info.