Spree Commerce Cart / Other API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Storefront Cart / Other API
  description: 'Storefront API is a modern REST API based on the [JSON API spec](https://jsonapi.org/) which provides you with all the necessary endpoints to build amazing user interfaces either in JavaScript frameworks or native mobile libraries.


    Import to [Postman](https://raw.githubusercontent.com/spree/spree/main/docs/api-reference/storefront.yaml)'
  contact:
    name: Vendo Connect Inc.
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  license:
    name: BSD-3-Clause
    url: https://github.com/spree/spree/blob/main/LICENSE.md
servers:
- url: https://demo.spreecommerce.org
  description: demo
- url: http://localhost:3000
  description: localhost
tags:
- name: Cart / Other
paths:
  /api/v2/storefront/cart/empty:
    patch:
      description: This endpoint removed all line items from the cart. Inventory that was previously taken by this order will be re-stocked.
      operationId: empty-cart
      responses:
        '200':
          $ref: '#/components/responses/Cart'
        '404':
          $ref: '#/components/responses/404NotFound'
      security:
      - orderToken: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CartIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsCart'
      summary: Empty the Cart
      tags:
      - Cart / Other
  /api/v2/storefront/cart/estimate_shipping_rates:
    get:
      description: Returns a list of shipping rates for the current cart. The rates given are only estimates and can vary from the final shipping rates.
      operationId: estimate-shipping-rates
      parameters:
      - name: country_iso
        in: query
        description: Pass country ISO or ISO3 symbol to get estimations for this destination. If no code is passed we'll try to use Cart shipping address country or the default Country for the current Store.
        schema:
          type: string
          example: USA
        example: USA
        required: true
      - $ref: '#/components/parameters/SparseFieldsShippingRate'
      responses:
        '200':
          $ref: '#/components/responses/EstimatedShippingRates'
        '404':
          $ref: '#/components/responses/404NotFound'
      security:
      - orderToken: []
      - bearerAuth: []
      summary: List Estimated Shipping Rates
      tags:
      - Cart / Other
  /api/v2/storefront/cart/associate:
    patch:
      description: Associates a guest cart with the currently signed in user.
      operationId: associate-cart
      parameters:
      - name: guest_order_token
        in: query
        description: Token of the guest cart to be associated with user.
        schema:
          type: string
          example: bd7SHdOAQqTsQHsjnhoWIw1633364692479
        required: true
      - $ref: '#/components/parameters/CartIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsCart'
      responses:
        '200':
          $ref: '#/components/responses/Cart'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - bearerAuth: []
      summary: Associate a Cart with a User
      tags:
      - Cart / Other
  /api/v2/storefront/cart/change_currency:
    patch:
      description: Changes the cart currency and recalculates the cart values.
      operationId: change-currency
      parameters:
      - name: new_currency
        in: query
        description: The currency to change the cart to.
        schema:
          type: string
          example: USD
        required: true
      - $ref: '#/components/parameters/CartIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsCart'
      responses:
        '200':
          $ref: '#/components/responses/Cart'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
      - bearerAuth: []
      summary: Change Cart Currency
      tags:
      - Cart / Other
components:
  schemas:
    Error:
      x-internal: false
      title: Error
      type: object
      properties:
        error:
          type: string
    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
    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
              - 'null'
              example: https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels=4123412434%2C
              description: Tracking URL to the service provider website
            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
              - 'null'
              format: date-time
              example: '2021-01-02 13:42:12'
              description: Date when Shipment was being sent from the warehouse
        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
    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
              - 'null'
              example: Example description
            available_on:
              type:
              - string
              - 'null'
              example: '2012-10-17T03:43:57Z'
            slug:
              type: string
              example: example-product
            price:
              type:
              - string
              - 'null'
              example: '15.99'
            currency:
              type: string
              example: USD
            display_price:
              type:
              - string
              - 'null'
              example: $15.99
            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
              - 'null'
              example: Example product
            meta_keywords:
              type:
              - string
              - 'null'
              example: example, product
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            sku:
              type: string
              example: 9238-WS
            available:
              type: boolean
            compare_at_price:
              type:
              - string
              - 'null'
              example: '49.99'
            display_compare_at_price:
              type:
              - string
              - 'null'
              example: $49.99
            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
    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: ''
    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
              - 'null'
              example: '10'
            height:
              type:
              - string
              - 'null'
              example: '10'
            width:
              type:
              - string
              - 'null'
              example: '10'
            depth:
              type:
              - string
              - 'null'
              example: '10'
            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
    Relation:
      type:
      - object
      - 'null'
      properties:
        id:
          type: string
        type:
          type: string
      required:
      - id
      - type
      x-internal: false
      description: ''
    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
    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
    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'
    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
    ShippingRate:
      type: object
      title: Shipping Rate
      description: ''
      x-internal: false
      properties:
        id:
          type:
          - string
          - 'null'
          example: '1'
        type:
          type: string
          default: shipping_rate
        attributes:
          type: object
          properties:
            name:
              type: string
              example: USPS Ground
            selected:
              type: boolean
              example: true
            cost:
              type: string
              example: '10.0'
              description: Price of the service without discounts applied
            tax_amount:
              type: string
              example: '0.0'
              description: Eligible tax for service (if any)
            shipping_method_id:
              type: integer
              example: 1
              description: ID of a Shipping Method. You will need this for the Checkout Update action
            final_price:
              type: string
              example: '10.0'
              description: Price to be presented for the Customer
            display_cost:
              type: string
              example: $10.00
            display_final_price:
              type: string
              example: $10.00
            display_tax_amount:
              type: string
              example: $0.00
            free:
              type: boolean
              example: true
              description: Indicates if the Shipping Rate is free, eg. when Free shipping promo applied to Cart
        relationships:
          type: object
          properties:
            shipping_method:
              type: object
              description: Shipping method for which this shipping rate belongs to
              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: ''
    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
              - 'null'
              format: date-time
            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
              - 'null'
              format: email
              example: spree@example.com
            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
              - 'null'
              example: Please wrap it as a gift
              description: Message added by the Customer
            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
              - 'null'
              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."
            payment_state:
              type:
              - string
              - 'null'
              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."
        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
  parameters:
    SparseFieldsCart:
      name: fields[cart]
      in: query
      description: Specify the fields you would like returned in the response body. [More inf

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