Spree Commerce Checkout / State API

openapi: 3.0.3
info:
  title: Admin Account / Address Checkout / State API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Checkout / State
paths:
  /api/v2/storefront/checkout/next:
    patch:
      description: Goes to the next checkout step.
      operationId: checkout-next
      responses:
        '200':
          $ref: '#/components/responses/Cart'
        '404':
          $ref: '#/components/responses/404NotFound'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CartIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsCart'
      summary: Next Checkout Step
      tags:
      - Checkout / State
  /api/v2/storefront/checkout/advance:
    patch:
      description: Advances the checkout to the furthest checkout step validation allows, up until the **completed** step.
      operationId: advance-checkout
      responses:
        '200':
          $ref: '#/components/responses/Cart'
        '404':
          $ref: '#/components/responses/404NotFound'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CartIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsCart'
      summary: Advance Checkout
      tags:
      - Checkout / State
  /api/v2/storefront/checkout/complete:
    patch:
      description: 'Completes the checkout by marking the order as complete.


        **Please be aware**; Once a checkout is marked as `complete` it is considered a completed order, the Cart and Checkout endpoints will no longer access a completed order, and a new cart will need to be created.


        If you want to access a completed order you will need to use the **Account / Orders** or **Order Status** endpoints.'
      operationId: complete-checkout
      responses:
        '200':
          $ref: '#/components/responses/Cart'
        '404':
          $ref: '#/components/responses/404NotFound'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CartIncludeParam'
      summary: Complete Checkout
      tags:
      - Checkout / State
components:
  schemas:
    User:
      type: object
      title: User
      description: ' '
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: user
        attributes:
          type: object
          properties:
            email:
              type: string
              example: spree@example.com
            first_name:
              type: string
              example: John
            last_name:
              type: string
              example: Doe
            selected_locale:
              type: string
              example: fr
            store_credits:
              type: number
              example: 150.75
            completed_orders:
              type: number
              example: 3
              description: Number of placed Orders by this User
            tags:
              type: array
              items:
                type: string
              description: List of tags associated with the user
            public_metadata:
              type: object
              example:
                user_segment: supplier
              description: The public metadata for this User
        relationships:
          type: object
          properties:
            default_billing_address:
              type: object
              description: Default billing address associated with this Account
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            default_shipping_address:
              type: object
              description: Default shipping address associated with this Account
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Product:
      type: object
      title: Product
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: product
        attributes:
          type: object
          properties:
            name:
              type: string
              example: Example product
            description:
              type: string
              example: Example description
              nullable: true
            available_on:
              type: string
              example: '2012-10-17T03:43:57Z'
              nullable: true
            slug:
              type: string
              example: example-product
            price:
              type: string
              example: '15.99'
              nullable: true
            currency:
              type: string
              example: USD
            display_price:
              type: string
              example: $15.99
              nullable: true
            purchasable:
              type: boolean
              description: Indicates if any of Variants are in stock or backorderable
            in_stock:
              type: boolean
              description: Indicates if any of Variants are in stock
            backorderable:
              type: boolean
              description: Indicates if any of Variants are backeorderable
            meta_description:
              type: string
              example: Example product
              nullable: true
            meta_keywords:
              type: string
              example: example, product
              nullable: true
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            sku:
              type: string
              example: 9238-WS
            available:
              type: boolean
            compare_at_price:
              type: string
              example: '49.99'
              nullable: true
            display_compare_at_price:
              type: string
              example: $49.99
              nullable: true
            localized_slugs:
              type: object
              description: Provides product's slugs in other locales
            tags:
              type: array
              items:
                type: string
              description: List of tags associated with the product
            labels:
              type: array
              items:
                type: string
              description: List of labels associated with the product
        relationships:
          type: object
          properties:
            variants:
              type: object
              description: List of Product Variants, excluding Master Variant
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            option_types:
              type: object
              description: List of Product Option Types
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            product_properties:
              type: object
              description: List of Product Properties
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            taxons:
              type: object
              description: List of Taxons associated with this Product
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            images:
              type: object
              description: List of Images associated with this Product
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            default_variant:
              type: object
              description: The default Variant for this product
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            primary_variant:
              type: object
              description: The Primary Variant for this product
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Promotion:
      type: object
      title: Promotion
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: promotion
        attributes:
          type: object
          properties:
            name:
              type: string
              example: 10% Discount
            description:
              type: string
              example: Super discount for you
            amount:
              type: string
              example: '-10.0'
            display_amount:
              type: string
              example: -$10.00
            code:
              type: string
              example: BLK-FRI
      required:
      - id
      - type
      - attributes
      x-internal: false
    Timestamp:
      type: string
      format: date-time
      example: '2020-02-16T07:14:54.617Z'
      x-internal: false
      title: Time Stamp
      x-examples:
        example-1: '2020-02-16T07:14:54.617Z'
    Variant:
      title: Variant
      description: 'Variant records track the individual variants of a Product. Variants are of two types: master variants and normal variants.'
      x-examples: {}
      type: object
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: variant
        attributes:
          type: object
          properties:
            sku:
              type: string
              example: SKU-1001
            price:
              type: string
              example: '15.99'
            currency:
              type: string
              example: USD
            display_price:
              type: string
              example: $15.99
            weight:
              type: string
              example: '10'
              nullable: true
            height:
              type: string
              example: '10'
              nullable: true
            width:
              type: string
              example: '10'
              nullable: true
            depth:
              type: string
              example: '10'
              nullable: true
            is_master:
              type: boolean
              description: Indicates if Variant is the master Variant
            options_text:
              type: string
              example: 'Size: small, Color: red'
            options:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
                  presentation:
                    type: string
            purchasable:
              type: boolean
              description: Indicates if Variant is in stock or backorderable
            in_stock:
              type: boolean
              description: Indicates if Variant is in stock
            backorderable:
              type: boolean
        relationships:
          type: object
          properties:
            product:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            images:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            option_values:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Shipment:
      type: object
      title: Shipment
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: shipment
        attributes:
          type: object
          properties:
            number:
              type: string
              example: H121354
              description: Unique Shipment identifier
            free:
              type: boolean
              description: Indicates if the Shipping Rate is free, eg. when Free shipping promo applied to Cart
            final_price:
              type: string
              example: '10.0'
              description: Price to be presented for the Customer
            display_final_price:
              type: string
              example: $10.00
            tracking_url:
              type: string
              example: https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels=4123412434%2C
              description: Tracking URL to the service provider website
              nullable: true
            state:
              type: string
              example: shipped
              enum:
              - pending
              - ready
              - shipped
              - canceled
              description: "Status of the Shipment. For a list of all available statuses please refer: <a href=\"/developer/core-concepts/shipments\" target=\"_blank\" rel=\"noopener\">\n  Shipment section in Spree Guides\n</a>"
            shipped_at:
              type: string
              format: date-time
              example: '2021-01-02 13:42:12'
              description: Date when Shipment was being sent from the warehouse
              nullable: true
        relationships:
          type: object
          properties:
            stock_location:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            shipping_rates:
              type: object
              properties:
                data:
                  type: array
                  items:
                    allOf:
                    - $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Cart:
      description: 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](/developer/core-concepts/orders)
      type: object
      title: Cart
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: cart
        attributes:
          type: object
          properties:
            number:
              type: string
              example: R123456789
              description: Used as the **{order_number}** value in the URI to identify a completed order.
            token:
              type: string
              example: eL0nVxe1Aum-Qr9-UkryPA1633360128076
              description: Used for authorizing actions through the `X-Spree-Order-Token` API Key.
            item_total:
              type: string
              example: '19.99'
            subtotal_cents:
              type: integer
              example: 1999
            store_credit_total_cents:
              type: integer
              example: 0
            total:
              type: string
              example: '29.99'
            total_cents:
              type: integer
              example: 2999
            total_minus_store_credits:
              type: string
              example: '29.99'
            total_minus_store_credits_cents:
              type: integer
              example: 2999
            ship_total:
              type: string
              example: '5.0'
            ship_total_cents:
              type: integer
              example: 500
            adjustment_total:
              type: string
              example: '10.0'
            created_at:
              $ref: '#/components/schemas/Timestamp'
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            completed_at:
              type: string
              format: date-time
              nullable: true
            included_tax_total:
              type: string
              example: '5.00'
            additional_tax_total:
              type: string
              example: '5.0'
            display_additional_tax_total:
              type: string
              example: $5.00
            tax_total:
              type: string
              example: '10.0'
            tax_total_cents:
              type: integer
              example: 1000
            currency:
              type: string
              example: USD
            state:
              type: string
              example: cart
              enum:
              - cart
              - address
              - delivery
              - payment
              - confirm
              - complete
              description: "State of the Cart in the Checkout flow. Please see <a href=\"/developer/core-concepts/orders#the-order-state-machine\">\n  The Order State machine\n</a> for a full list with description."
            email:
              type: string
              format: email
              example: spree@example.com
              nullable: true
            display_item_total:
              type: string
              example: $19.99
            display_ship_total:
              type: string
              example: $19.99
            display_adjustment_total:
              type: string
              example: $10.00
            display_included_tax_total:
              type: string
              example: $5.00
            promo_total:
              type: string
              example: '-10.0'
            promo_total_cents:
              type: integer
              example: -1000
            display_promo_total:
              type: string
              example: -$10.00
            item_count:
              type: number
              description: Total quantity number of all items added to the Cart
              example: 2
              minimum: 0
            special_instructions:
              type: string
              example: Please wrap it as a gift
              description: Message added by the Customer
              nullable: true
            display_total:
              type: string
              example: $29.99
            display_total_minus_store_credits:
              type: string
              example: $29.99
            pre_tax_item_amount:
              type: string
              example: '17.00'
            display_pre_tax_item_amount:
              type: string
              example: $17.00
            pre_tax_total:
              type: string
              example: '20.00'
            display_tax_total:
              type: string
              example: $10.00
            display_pre_tax_total:
              type: string
              example: $20.00
            shipment_state:
              type: string
              enum:
              - pending
              - backorder
              - canceled
              - partial
              - ready
              - shipped
              - null
              description: "Overall state of the Shipments. Please see <a href=\"/developer/core-concepts/orders#order-shipment-states-1\">\n  Order Shipments states\n</a> for a full list with description."
              nullable: true
            payment_state:
              type: string
              enum:
              - balance_due
              - credit_owed
              - failed
              - paid
              - void
              - null
              description: "Overall state of the Payments. Please see <a href=\"/developer/core-concepts/orders#order-payment-states\">\n  Order Payments states\n</a> for a full list with description."
              nullable: true
        relationships:
          type: object
          properties:
            line_items:
              type: object
              description: ''
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            variants:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            promotions:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            payments:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            shipments:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            user:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            billing_address:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            shipping_address:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Relation:
      type: object
      nullable: true
      properties:
        id:
          type: string
        type:
          type: string
      required:
      - id
      - type
      x-internal: false
      description: ''
    Payment:
      title: Payment
      type: object
      description: ''
      x-internal: false
      properties:
        id:
          type: string
        type:
          type: string
          default: payment
        attributes:
          type: object
          properties:
            amount:
              type: string
              default: '200.57'
            response_code:
              type: integer
              default: 192
            number:
              type: string
              default: PV7B4YH0
            cvv_response_code:
              type: integer
              default: 200
            cvv_response_message:
              type: string
              default: authorized
            payment_method_id:
              type: integer
              default: 1
            payment_method_name:
              type: string
              default: Credit Card
            state:
              type: string
              default: paid
        relationships:
          type: object
          properties:
            source:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            payment_method:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    LineItem:
      title: Line Item
      type: object
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: line_item
        attributes:
          type: object
          properties:
            name:
              type: string
              example: Sample product
            quantity:
              type: integer
              example: 1
            slug:
              type: string
              example: sample-product
            options_text:
              type: string
              example: 'Size: small, Color: red'
            price:
              type: string
              example: '125.0'
              description: Price of Product per quantity
            currency:
              type: string
              example: USD
            display_price:
              type: string
              example: $125.00
              description: Price of Product per quantity
            total:
              type: string
              example: '250.0'
              description: Total price of Line Item including adjastments, promotions and taxes
            display_total:
              type: string
              example: $250.00
              description: Total price of Line Item including adjastments, promotions and taxes
            adjustment_total:
              type: string
              example: '10.0'
              description: TBD
            display_adjustment_total:
              type: string
              example: $10.00
              description: TBD
            additional_tax_total:
              type: string
              example: '5.0'
            display_additional_tax_total:
              type: string
              example: $5.00
            discounted_amount:
              type: string
              example: '125.0'
            display_discounted_amount:
              type: string
              example: $125.00
            pre_tax_amount:
              type: string
              example: '125.0'
            display_pre_tax_amount:
              type: string
              example: $125.00
            promo_total:
              type: string
              example: '-5.0'
            display_promo_total:
              type: string
            included_tax_total:
              type: string
              example: '0.0'
              description: Taxes included in the price, eg. VAT
            display_inluded_tax_total:
              type: string
              example: $0.00
            compare_at_amount:
              type: string
              example: '290.99'
              description: Compare at price of the Line Item
            display_compare_at_amount:
              type: string
              example: $290.99
              description: Display compare at price of the Line Item
            public_metadata:
              type: object
              example:
                recommended_by_us: true
              description: The public metadata for the Line Item.
        relationships:
          type: object
          properties:
            variant:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            digital_links:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
      description: ''
    Error:
      x-internal: false
      title: Error
      type: object
      properties:
        error:
          type: string
    DigitalLink:
      title: Digital Link
      type: object
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: digital_link
        attributes:
          type: object
          properties:
            token:
              type: string
              example: Gn6srBmmR4KrWy73LRtrBKYw
        relationships:
          type: object
          properties:
            line_item:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      description: Digital links are accessible in the order includes line_items.digital_links
    CartIncludes:
      x-internal: false
      title: Cart Includes
      anyOf:
      - $ref: '#/components/schemas/LineItem'
      - $ref: '#/components/schemas/Promotion'
      - $ref: '#/components/schemas/Variant'
      - $ref: '#/components/schemas/Payment'
      - $ref: '#/components/schemas/User'
      - $ref: '#/components/schemas/Shipment'
      - $ref: '#/components/schemas/DigitalLink'
      - $ref: '#/components/schemas/Product'
      description: ''
  parameters:
    SparseFieldsCart:
      name: fields[cart]
      in: query
      description: Specify the fields you would like returned in the response body. [More information](https://jsonapi.org/format/#fetching-sparse-fieldsets).
      schema:
        type: string
      example: token,currency,number
    CartIncludeParam:
      name: include
      in: query
      schema:
        type: string
      description: Specify the related resources you would like to receive in the response body. [More Information](https://jsonapi.org/format/#fetching-includes).
      example: line_items,variants,variants.images,billing_address,shipping_address,user,payments,shipments,promotions,gift_card
  responses:
    404NotFound:
      description: 404 Not Found - Resource not found.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: The resource you were looking for could not be found.
                default: The resource you were looking for could not be found.
          examples:
            404 Example:
              value:
                error: The resource you were looking for could not be found.
    Cart:
      description: 200 Success - Returns the `cart` object.
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/Cart'
              included:
                type: array
                items:
                  $ref: '#/components/schemas/CartIncludes'
            required:
            - data
          examples:
            Empty Cart:
              value:
                data:
                  id: '17'
                  type: cart
                  attributes:
                    number: R233871560
                    item_total: '0.0'
                    total: '0.0'
                    subtotal_cents: 0
                    store_credit_total_cents: 0
                    total_cents: 0
                    total_minus_store_credits: '0.0'
                    total_minus_store_credits_cents: 0
                    ship_total: '0.0'
                    ship_total_cents: 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'
                    tax_total_cents: 0
                    currency: USD
                    state: cart
                    token: zTEpsukRq_yEUcXVCSv0uw1632867307450
                    email: null
                    display_item_total: $0.00
                    di

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-checkout-state-api-openapi.yml