Storefront API
- Authentication
- Account
- Account / Address
- Account / Credit Cards
- Account / Orders
- Order Status
- Cart
- Cart / Line Items
- Cart / Other
- Cart / Coupons
- Checkout
- Checkout / State
- Checkout / Shipments
- Checkout / Payments
- Checkout / Store Credit
- Products
- Stores
- Taxons
- Countries
- CMS Pages
- Menus
- Wishlists
- Wishlists / Wished Items
- Digital Downloads
Platform API
- Authentication
- Addresses
- Adjustments
- Classifications
- CMS Pages
- CMS Sections
- Countries
- Data Feeds
- Digital Links
- Digital Assets
- Line Items
- Menu Items
- Menus
- Option Types
- Option Values
- Orders
- Payment Methods
- Payments
- Products
- Promotion Actions
- Promotion Categories
- Promotion Rules
- Promotions
- Roles
- Shipments
- Shipping Categories
- Shipping Methods
- States
- Stock Items
- Stock Locations
- Store Credit Categories
- Store Credit Types
- Store Credits
- Tax Categories
- Tax Rates
- Taxonomies
- Taxons
- Users
- Variants
- Webhook Events
- Webhook Subscribers
- Wished Items
- Wishlists
- Zones
Create new Payment
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).
Order token to authorize Cart and Checkout requests.
Specify the related resources you would like to receive in the response body. More Information.
Specify the fields you would like returned in the response body. More information.
ID of the selected Payment Method
ID of the selected Payment Source (eg. Credit Card, only for signed in users)
Amount for the newly created payment, when left blank will use the entire Order Total (reduced by used Store Credits / Gift Cards)
Payment source authorization token, more details for Stripe implementation
Last 4 digits of CC number
Expiration date month
Expiration date year
Card holder name
curl --request POST \
--url https://demo.spreecommerce.org/api/v2/storefront/checkout/create_payment \
--header 'Content-Type: application/vnd.api+json' \
--header 'X-Spree-Order-Token: <api-key>' \
--data '{
"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"
}
}'{
"data": {
"id": "17",
"type": "cart",
"attributes": {
"number": "R233871560",
"item_total": "0.0",
"total": "0.0",
"ship_total": "0.0",
"adjustment_total": "0.0",
"created_at": "2021-09-28T22:15:07.471Z",
"updated_at": "2021-09-28T22:15:07.471Z",
"completed_at": null,
"included_tax_total": "0.0",
"additional_tax_total": "0.0",
"display_additional_tax_total": "$0.00",
"display_included_tax_total": "$0.00",
"tax_total": "0.0",
"currency": "USD",
"state": "cart",
"token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
"email": null,
"display_item_total": "$0.00",
"display_ship_total": "$0.00",
"display_adjustment_total": "$0.00",
"display_tax_total": "$0.00",
"promo_total": "0.0",
"display_promo_total": "$0.00",
"item_count": 0,
"special_instructions": null,
"display_total": "$0.00",
"pre_tax_item_amount": "0.0",
"display_pre_tax_item_amount": "$0.00",
"pre_tax_total": "0.0",
"display_pre_tax_total": "$0.00",
"shipment_state": null,
"payment_state": null
},
"relationships": {
"line_items": {
"data": []
},
"variants": {
"data": []
},
"promotions": {
"data": []
},
"payments": {
"data": []
},
"shipments": {
"data": []
},
"user": {
"data": null
},
"billing_address": {
"data": null
},
"shipping_address": {
"data": null
}
}
}
}Authorizations
Order token to authorize Cart and Checkout requests.
Query Parameters
Specify the related resources you would like to receive in the response body. More Information.
Specify the fields you would like returned in the response body. More information.
Body
ID of the selected Payment Method
ID of the selected Payment Source (eg. Credit Card, only for signed in users)
Amount for the newly created payment, when left blank will use the entire Order Total (reduced by used Store Credits / Gift Cards)
Payment source authorization token, more details for Stripe implementation
Card holder name
visa, mastercard, amex Last 4 digits of CC number
Expiration date month
Expiration date year
Response
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
Used as the {order_number} value in the URI to identify a completed order.
Used for authorizing actions through the X-Spree-Order-Token API Key.
State of the Cart in the Checkout flow. Please see <a href="/developer/core-concepts/orders#the-order-state-machine"> The Order State machine </a> for a full list with description.
cart, address, delivery, payment, confirm, complete Total quantity number of all items added to the Cart
x > 0Message added by the Customer
Overall state of the Shipments. Please see <a href="/developer/core-concepts/orders#order-shipment-states-1"> Order Shipments states </a> for a full list with description.
pending, backorder, canceled, partial, ready, shipped Overall state of the Payments. Please see <a href="/developer/core-concepts/orders#order-payment-states"> Order Payments states </a> for a full list with description.
balance_due, credit_owed, failed, paid, void Price of Product per quantity
Price of Product per quantity
Total price of Line Item including adjastments, promotions and taxes
Total price of Line Item including adjastments, promotions and taxes
TBD
TBD
Taxes included in the price, eg. VAT
The public metadata for the Line Item.
Was this page helpful?
curl --request POST \
--url https://demo.spreecommerce.org/api/v2/storefront/checkout/create_payment \
--header 'Content-Type: application/vnd.api+json' \
--header 'X-Spree-Order-Token: <api-key>' \
--data '{
"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"
}
}'{
"data": {
"id": "17",
"type": "cart",
"attributes": {
"number": "R233871560",
"item_total": "0.0",
"total": "0.0",
"ship_total": "0.0",
"adjustment_total": "0.0",
"created_at": "2021-09-28T22:15:07.471Z",
"updated_at": "2021-09-28T22:15:07.471Z",
"completed_at": null,
"included_tax_total": "0.0",
"additional_tax_total": "0.0",
"display_additional_tax_total": "$0.00",
"display_included_tax_total": "$0.00",
"tax_total": "0.0",
"currency": "USD",
"state": "cart",
"token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
"email": null,
"display_item_total": "$0.00",
"display_ship_total": "$0.00",
"display_adjustment_total": "$0.00",
"display_tax_total": "$0.00",
"promo_total": "0.0",
"display_promo_total": "$0.00",
"item_count": 0,
"special_instructions": null,
"display_total": "$0.00",
"pre_tax_item_amount": "0.0",
"display_pre_tax_item_amount": "$0.00",
"pre_tax_total": "0.0",
"display_pre_tax_total": "$0.00",
"shipment_state": null,
"payment_state": null
},
"relationships": {
"line_items": {
"data": []
},
"variants": {
"data": []
},
"promotions": {
"data": []
},
"payments": {
"data": []
},
"shipments": {
"data": []
},
"user": {
"data": null
},
"billing_address": {
"data": null
},
"shipping_address": {
"data": null
}
}
}
}