Spree Commerce Checkout / Payments API
The Checkout / Payments API from Spree Commerce — 2 operation(s) for checkout / payments.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Checkout / Payments 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 / Payments
paths:
/api/v2/storefront/checkout/create_payment:
post:
description: 'Creates new Payment for the current checkout.
You can either create new payment source (eg. a Credit Card) or use an existing (for signed in users only).
Newly created payment source will be associated to the current signed in user.
System will automatically invalidate previous (non-finalized) payments (excluding store credit / gift card payments).
[More details on payment system](/developer/core-concepts/payments)'
operationId: create-payment
responses:
'200':
$ref: '#/components/responses/Cart'
'404':
$ref: '#/components/responses/404NotFound'
'422':
$ref: '#/components/responses/422UnprocessableEntity'
security:
- orderToken: []
- bearerAuth: []
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
payment_method_id:
type: string
description: ID of the selected Payment Method
source_id:
type: string
description: ID of the selected Payment Source (eg. Credit Card, only for signed in users)
amount:
type: number
description: Amount for the newly created payment, when left blank will use the entire Order Total (reduced by used Store Credits / Gift Cards)
source_attributes:
type: object
properties:
gateway_payment_profile_id:
type: string
description: Payment source authorization token, more details for [Stripe implementation](https://stripe.com/docs/payments/accept-a-payment-charges#web-create-token)
cc_type:
type: string
enum:
- visa
- mastercard
- amex
last_digits:
type: string
description: Last 4 digits of CC number
month:
type: number
description: Expiration date month
year:
type: number
description: Expiration date year
name:
type: string
description: Card holder name
required:
- gateway_payment_profile_id
- name
required:
- payment_method_id
examples:
Create new Credit Card:
value:
payment_method_id: '1'
source_attributes:
gateway_payment_profile_id: card_1JqvNB2eZvKYlo2C5OlqLV7S
cc_type: visa
last_digits: '1111'
month: 10
year: 2026
name: John Snow
Use existing Credit Card:
value:
payment_method_id: '1'
source_id: '1'
description: ''
parameters:
- $ref: '#/components/parameters/CartIncludeParam'
- $ref: '#/components/parameters/SparseFieldsCart'
summary: Create new Payment
tags:
- Checkout / Payments
/api/v2/storefront/checkout/payment_methods:
get:
description: Returns a list of available payment methods for this checkout.
tags:
- Checkout / Payments
operationId: payment-methods
responses:
'200':
$ref: '#/components/responses/PaymentMethodList'
'404':
$ref: '#/components/responses/404NotFound'
security:
- orderToken: []
- bearerAuth: []
summary: List Payment Methods
components:
schemas:
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: ''
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'
Error:
x-internal: false
title: Error
type: object
properties:
error:
type: string
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
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
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: ''
Relation:
type: object
nullable: true
properties:
id:
type: string
type:
type: string
required:
- id
- type
x-internal: false
description: ''
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
PaymentMethod:
title: Payment Method
description: ''
type: object
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: payment_method
attributes:
type: object
properties:
type:
type: string
example: Spree::Gateway::StripeGateway
name:
type: string
example: Stripe
description:
type: string
example: Stripe Payments
nullable: true
preferences:
type: object
required:
- id
- type
- attributes
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
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
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
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.
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/openapi/spree-checkout-payments-api-openapi.yml