# Spree Commerce documentation: v6.x API Reference Store API

## Store API

### API basics

- [Store API](https://spreecommerce.org/docs/api-reference/store-api/introduction.md)
- [Authentication](https://spreecommerce.org/docs/api-reference/store-api/authentication.md): How to authenticate requests to the Store API
- [Errors](https://spreecommerce.org/docs/api-reference/store-api/errors.md): Reference for Spree Store API error responses — JSON format, machine-readable codes, HTTP status codes, validation details, and retry strategies.
- [Idempotency](https://spreecommerce.org/docs/api-reference/store-api/idempotency.md): Use Idempotency-Key headers on Spree Store API mutations to safely retry carts, checkouts, and payments without creating duplicate side effects.
- [Rate Limiting](https://spreecommerce.org/docs/api-reference/store-api/rate-limitting.md): Rate limits and throttling for the Store API
- [Querying](https://spreecommerce.org/docs/api-reference/store-api/querying.md): How to filter, sort, and paginate Store API results using Ransack
- [Relations](https://spreecommerce.org/docs/api-reference/store-api/relations.md): How to include related resources in API responses
- [Metadata](https://spreecommerce.org/docs/api-reference/store-api/metadata.md): How to store and retrieve custom metadata on carts, orders, and line items
- [Localization](https://spreecommerce.org/docs/api-reference/store-api/localization.md): How to set locale, currency, and country for API requests
- [Monetary Amounts](https://spreecommerce.org/docs/api-reference/store-api/monetary-amounts.md): How monetary values are represented in API responses
- [Migrating from Storefront API v2](https://spreecommerce.org/docs/api-reference/store-api/migrating-from-storefront-api-v2.md): Map every Storefront API v2 endpoint, concept, and SDK call to its Store API v3 equivalent.

### Endpoints

#### Authentication

- [Login](https://spreecommerce.org/docs/api-reference/store-api/authentication/login.md): Authenticates a customer and returns a JWT access token + refresh token.
- [Refresh token](https://spreecommerce.org/docs/api-reference/store-api/authentication/refresh-token.md): Exchanges a refresh token for a new access JWT and rotated refresh token. No Authorization header needed.
- [Logout](https://spreecommerce.org/docs/api-reference/store-api/authentication/logout.md): Revokes the submitted refresh token. The refresh token itself is the credential — no Authorization header is required, so a client with an expired access JWT can still log out.
- [Request a password reset](https://spreecommerce.org/docs/api-reference/store-api/authentication/request-a-password-reset.md): Sends a password reset email if an account exists for the given email address. Always returns 202 Accepted to prevent email enumeration.
- [Reset password with token](https://spreecommerce.org/docs/api-reference/store-api/authentication/reset-password-with-token.md): Resets the password using a token received via email. Returns a JWT token on success (auto-login).

#### Product Catalog

- [List categories](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/list-categories.md): Returns a paginated list of categories for the current store
- [Get a category](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/get-a-category.md): Returns a single category by permalink or prefix ID
- [List collections](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/list-collections.md): Returns a paginated list of collections for the current store.
- [Get a collection](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/get-a-collection.md): Returns a single collection by permalink or prefix ID.
- [List collection products](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/list-collection-products.md): Products in the collection. Defaults to the collection's own sort order and accepts the same filters, sort, and pagination as the products endpoint.
- [List products](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/list-products.md): Returns a paginated list of active products for the current store
- [Get a product](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/get-a-product.md): Returns a single product by slug or prefix ID
- [Get product filters](https://spreecommerce.org/docs/api-reference/store-api/product-catalog/get-product-filters.md): Returns available filters for products with their options and counts. Use this endpoint to build filter UIs for product listing pages.

#### Carts

- [Upload a purchase order document](https://spreecommerce.org/docs/api-reference/store-api/carts/upload-a-purchase-order-document.md): Prepares an upload for the buyer's signed purchase order document. Send the file's metadata, then `PUT` the bytes to `upload.url` with exactly `upload.headers`, and attach the file by sending the returned `signed_id` as `po_document_signed_id` on a cart update. Files are stored privately. `checksum`…
- [Set the cart tax identifier](https://spreecommerce.org/docs/api-reference/store-api/carts/set-the-cart-tax-identifier.md): Sets the tax registration this cart is taxed against, overriding the one on the customer's profile — for a buyer paying through a different company than the one on their account. Send both `kind` and `value` every time. The cart's totals are recalculated. Returns 201 when the cart had no override ye…
- [List active carts](https://spreecommerce.org/docs/api-reference/store-api/carts/list-active-carts.md): Returns all active (incomplete) carts for the authenticated user.
- [Create a new cart](https://spreecommerce.org/docs/api-reference/store-api/carts/create-a-new-cart.md): Creates a new shopping cart. Can be created by guests or authenticated customers. Returns a `token` that must be used for guest access to the cart.
- [Get a cart](https://spreecommerce.org/docs/api-reference/store-api/carts/get-a-cart.md): Returns a shopping cart by prefixed ID. Authorize via x-spree-token header (guest) or JWT Bearer token (authenticated user).
- [Delete a cart](https://spreecommerce.org/docs/api-reference/store-api/carts/delete-a-cart.md): Deletes/abandons the cart.
- [Update a cart](https://spreecommerce.org/docs/api-reference/store-api/carts/update-a-cart.md): Updates cart info (email, addresses, customer note). When addresses change, the order state is reverted to address to ensure shipments are recalculated.
- [Associate guest cart with authenticated user](https://spreecommerce.org/docs/api-reference/store-api/carts/associate-guest-cart-with-authenticated-user.md): Associates a guest cart with the currently authenticated user. Requires JWT authentication and possession of the cart's token (x-spree-token) — the token authorizes claiming the cart.
- [Complete cart](https://spreecommerce.org/docs/api-reference/store-api/carts/complete-cart.md): Completes the cart and finalizes the purchase. Returns an Order (not Cart).
- [Apply discount code](https://spreecommerce.org/docs/api-reference/store-api/carts/apply-discount-code.md): Applies a promotion discount code to the cart. The code is matched case-insensitively.
- [Remove discount code](https://spreecommerce.org/docs/api-reference/store-api/carts/remove-discount-code.md): Removes a previously applied discount code from the cart. The ID is the discount code string itself.
- [Select delivery rate for fulfillment](https://spreecommerce.org/docs/api-reference/store-api/carts/select-delivery-rate-for-fulfillment.md): Selects a delivery rate for a specific fulfillment and auto-advances checkout.
- [Apply gift card](https://spreecommerce.org/docs/api-reference/store-api/carts/apply-gift-card.md): Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount — the cart `total` remains unchanged while `amount_due` is reduced.
- [Remove gift card](https://spreecommerce.org/docs/api-reference/store-api/carts/remove-gift-card.md): Removes a previously applied gift card from the cart.
- [Add item to cart](https://spreecommerce.org/docs/api-reference/store-api/carts/add-item-to-cart.md): Adds a variant to the cart. Creates a new line item or increases quantity if variant already in cart.
- [Remove line item from cart](https://spreecommerce.org/docs/api-reference/store-api/carts/remove-line-item-from-cart.md): Removes a line item from the cart
- [Update line item quantity](https://spreecommerce.org/docs/api-reference/store-api/carts/update-line-item-quantity.md): Updates the quantity of a line item in the cart
- [Create payment session](https://spreecommerce.org/docs/api-reference/store-api/carts/create-payment-session.md): Creates a new payment session for the cart. Delegates to the payment gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent, Adyen session, PayPal order).
- [Get payment session](https://spreecommerce.org/docs/api-reference/store-api/carts/get-payment-session.md): Returns a single payment session with its current status and provider data.
- [Update payment session](https://spreecommerce.org/docs/api-reference/store-api/carts/update-payment-session.md): Updates a payment session. Delegates to the payment gateway to sync changes with the provider.
- [Complete payment session](https://spreecommerce.org/docs/api-reference/store-api/carts/complete-payment-session.md): Completes a payment session by confirming the payment with the provider. This triggers payment capture/authorization and order completion.
- [Create payment](https://spreecommerce.org/docs/api-reference/store-api/carts/create-payment.md): Creates a payment for a non-session payment method (e.g. Check, Cash on Delivery, Bank Transfer). For payment methods that require a session (e.g. Stripe, PayPal), use the payment sessions endpoint instead.
- [Apply store credit](https://spreecommerce.org/docs/api-reference/store-api/carts/apply-store-credit.md): Applies store credit to the cart during checkout.
- [Remove store credit](https://spreecommerce.org/docs/api-reference/store-api/carts/remove-store-credit.md): Removes store credit from the cart.

#### Orders

- [List claims](https://spreecommerce.org/docs/api-reference/store-api/orders/list-claims.md): The damage or missing-item claims opened on one of the customer's orders, newest first. Accessible via JWT or the order token header for guests.
- [Open a claim](https://spreecommerce.org/docs/api-reference/store-api/orders/open-a-claim.md): Reports a damaged, missing or wrong item on one of the customer's orders. Approving, denying and resolving it are the merchant's. Accessible via JWT or the order token header for guests.
- [Get an order](https://spreecommerce.org/docs/api-reference/store-api/orders/get-an-order.md): Returns a completed purchase. Accessible via JWT (authenticated users) or order token header (guests).
- [List returns](https://spreecommerce.org/docs/api-reference/store-api/orders/list-returns.md): The returns opened on one of the customer's orders, newest first. Accessible via JWT or the order token header for guests.
- [Open a return](https://spreecommerce.org/docs/api-reference/store-api/orders/open-a-return.md): Opens a return for shipped units of one of the customer's orders. Approving, receiving and refunding it are the merchant's. Accessible via JWT or the order token header for guests.

#### Customers

- [List customer addresses](https://spreecommerce.org/docs/api-reference/store-api/customers/list-customer-addresses.md): Returns all addresses in the customer address book
- [Create an address](https://spreecommerce.org/docs/api-reference/store-api/customers/create-an-address.md): Adds a new address to the customer address book
- [Get an address](https://spreecommerce.org/docs/api-reference/store-api/customers/get-an-address.md)
- [Delete an address](https://spreecommerce.org/docs/api-reference/store-api/customers/delete-an-address.md)
- [Update an address](https://spreecommerce.org/docs/api-reference/store-api/customers/update-an-address.md)
- [List saved credit cards](https://spreecommerce.org/docs/api-reference/store-api/customers/list-saved-credit-cards.md): Returns the authenticated customer's saved credit cards for the current store's payment methods
- [Get a credit card](https://spreecommerce.org/docs/api-reference/store-api/customers/get-a-credit-card.md): Returns a saved credit card by its ID
- [Delete a credit card](https://spreecommerce.org/docs/api-reference/store-api/customers/delete-a-credit-card.md): Removes a saved credit card from the customer account
- [List orders](https://spreecommerce.org/docs/api-reference/store-api/customers/list-orders.md): Returns a paginated list of completed orders for the authenticated customer.
- [Get an order](https://spreecommerce.org/docs/api-reference/store-api/customers/get-an-order.md): Returns a single completed order for the authenticated customer.
- [Register a new customer](https://spreecommerce.org/docs/api-reference/store-api/customers/register-a-new-customer.md): Creates a new customer account and returns a JWT token
- [Get current customer profile](https://spreecommerce.org/docs/api-reference/store-api/customers/get-current-customer-profile.md): Returns the profile of the currently authenticated customer
- [Update current customer profile](https://spreecommerce.org/docs/api-reference/store-api/customers/update-current-customer-profile.md): Updates the profile of the currently authenticated customer
- [List data requests](https://spreecommerce.org/docs/api-reference/store-api/customers/list-data-requests.md): Returns the authenticated customer's GDPR data requests, most recent first
- [Open a data request](https://spreecommerce.org/docs/api-reference/store-api/customers/open-a-data-request.md): Opens a GDPR request for a copy of the customer's personal data (`access`) or its erasure (`erasure`). The work happens in the background and the response is the pending request.
- [Get a data request](https://spreecommerce.org/docs/api-reference/store-api/customers/get-a-data-request.md): Returns one of the customer's own data requests, with a download link once the export is ready
- [List gift cards](https://spreecommerce.org/docs/api-reference/store-api/customers/list-gift-cards.md): Returns all gift cards for the authenticated customer
- [Get a gift card](https://spreecommerce.org/docs/api-reference/store-api/customers/get-a-gift-card.md): Returns a gift card by its ID
- [Create payment setup session](https://spreecommerce.org/docs/api-reference/store-api/customers/create-payment-setup-session.md): Creates a new payment setup session for saving a payment method for future use. Delegates to the payment gateway to initialize a provider-specific setup flow (e.g. Stripe SetupIntent, Adyen zero-auth tokenization).
- [Get payment setup session](https://spreecommerce.org/docs/api-reference/store-api/customers/get-payment-setup-session.md): Returns a payment setup session with its current status and provider data.
- [Complete payment setup session](https://spreecommerce.org/docs/api-reference/store-api/customers/complete-payment-setup-session.md): Completes a payment setup session by confirming the setup with the provider, resulting in a saved payment method.
- [List store credits](https://spreecommerce.org/docs/api-reference/store-api/customers/list-store-credits.md): Returns store credits for the authenticated customer, filtered by current store and currency. Supports Ransack filtering.
- [Get a store credit](https://spreecommerce.org/docs/api-reference/store-api/customers/get-a-store-credit.md)

#### Markets

- [List countries](https://spreecommerce.org/docs/api-reference/store-api/markets/list-countries.md): Returns countries available in the store. Use ?expand=market to include market details (currency, locale, tax_inclusive).
- [Get a country](https://spreecommerce.org/docs/api-reference/store-api/markets/get-a-country.md): Returns a single country by ISO code. Supports ?expand=states for address forms and ?expand=market for market details.
- [List supported currencies](https://spreecommerce.org/docs/api-reference/store-api/markets/list-supported-currencies.md): Returns currencies supported by the store (derived from markets)
- [List supported locales](https://spreecommerce.org/docs/api-reference/store-api/markets/list-supported-locales.md): Returns locales supported by the store (derived from markets)
- [List markets](https://spreecommerce.org/docs/api-reference/store-api/markets/list-markets.md): Returns all markets for the current store with their countries, currency, locales, and tax configuration.
- [Get a market](https://spreecommerce.org/docs/api-reference/store-api/markets/get-a-market.md): Returns a single market by prefixed ID with its countries, currency, locales, and tax configuration.
- [Resolve market by country](https://spreecommerce.org/docs/api-reference/store-api/markets/resolve-market-by-country.md): Determine which market applies for a given country ISO code. Useful for auto-selecting the correct currency and locale when a customer's location is known.
- [List countries in a market](https://spreecommerce.org/docs/api-reference/store-api/markets/list-countries-in-a-market.md): Returns countries belonging to a specific market. Use this for address form country dropdowns during checkout.
- [Get a country in a market](https://spreecommerce.org/docs/api-reference/store-api/markets/get-a-country-in-a-market.md): Returns a single country by ISO code within a market. Supports ?expand=states for address forms.

#### Wishlists

- [List wishlists](https://spreecommerce.org/docs/api-reference/store-api/wishlists/list-wishlists.md): Returns all wishlists for the authenticated customer
- [Create a wishlist](https://spreecommerce.org/docs/api-reference/store-api/wishlists/create-a-wishlist.md): Creates a new wishlist for the customer
- [Get a wishlist](https://spreecommerce.org/docs/api-reference/store-api/wishlists/get-a-wishlist.md)
- [Delete a wishlist](https://spreecommerce.org/docs/api-reference/store-api/wishlists/delete-a-wishlist.md)
- [Update a wishlist](https://spreecommerce.org/docs/api-reference/store-api/wishlists/update-a-wishlist.md)
- [Add item to wishlist](https://spreecommerce.org/docs/api-reference/store-api/wishlists/add-item-to-wishlist.md): Adds a variant to the wishlist
- [Remove item from wishlist](https://spreecommerce.org/docs/api-reference/store-api/wishlists/remove-item-from-wishlist.md)
- [Update a wishlist item](https://spreecommerce.org/docs/api-reference/store-api/wishlists/update-a-wishlist-item.md): Changes the quantity of a wishlist item, or moves it to another variant

#### Newsletter Subscribers

- [Subscribe to the newsletter](https://spreecommerce.org/docs/api-reference/store-api/newsletter-subscribers/subscribe-to-the-newsletter.md): Subscribes an email address to the newsletter for the current store.
- [Verify a newsletter subscription](https://spreecommerce.org/docs/api-reference/store-api/newsletter-subscribers/verify-a-newsletter-subscription.md): Confirms a pending newsletter subscription using the verification token sent by email.
- [Unsubscribe from the newsletter](https://spreecommerce.org/docs/api-reference/store-api/newsletter-subscribers/unsubscribe-from-the-newsletter.md): Destroys the newsletter subscription, firing the `newsletter_subscriber.deleted` lifecycle event. Two authorization paths are accepted:
- [Request an unsubscribe token](https://spreecommerce.org/docs/api-reference/store-api/newsletter-subscribers/request-an-unsubscribe-token.md): Publishes a `newsletter_subscriber.unsubscribe_requested` event carrying an unsubscribe token in the payload. Always returns 202 Accepted to prevent email enumeration.

#### Policies

- [List store policies](https://spreecommerce.org/docs/api-reference/store-api/policies/list-store-policies.md): Returns all policies for the current store (e.g., return policy, privacy policy, terms of service). Policies are managed in Spree Admin and contain rich text content.
- [Get a policy](https://spreecommerce.org/docs/api-reference/store-api/policies/get-a-policy.md): Returns a single policy by slug or prefixed ID. Includes the full rich text body.

#### Channel

- [Get the current channel](https://spreecommerce.org/docs/api-reference/store-api/channel/get-the-current-channel.md): Returns the channel this request resolved to (key binding → X-Spree-Channel header → store default), including the resolved storefront access posture. Reachable before authentication so gated storefronts can render a sign-in wall.

#### Companies

- [List my company memberships](https://spreecommerce.org/docs/api-reference/store-api/companies/list-my-company-memberships.md): Returns the authenticated customer's company memberships, each with the node it is held on and the path of nodes above it. Standing covers the node and every node below it, so a membership on a parent authorizes buying for its divisions.
- [Get a company node](https://spreecommerce.org/docs/api-reference/store-api/companies/get-a-company-node.md): Returns one node of the buyer's organization. Requires standing — a membership on the node or on one of its ancestors; any other node is not found rather than refused, so its existence is not disclosed.
- [Update a company node](https://spreecommerce.org/docs/api-reference/store-api/companies/update-a-company-node.md): Renames the node. Structure — the parent and the kind — is managed by the merchant, not by buyers.
- [List company members](https://spreecommerce.org/docs/api-reference/store-api/companies/list-company-members.md): The people with standing over this node. Within a company every member may read and manage the directory.
- [Add a member by email](https://spreecommerce.org/docs/api-reference/store-api/companies/add-a-member-by-email.md): Invites a person to the node by email (a `cinv_...` id) and sends the invite email. This is an invitation even when the email already belongs to a customer: they join by accepting the emailed token, which proves they own the address and agree to join. The response is the same either way, so it does…
- [List pending company invitations](https://spreecommerce.org/docs/api-reference/store-api/companies/list-pending-company-invitations.md): The invitations to this node that nobody has accepted or revoked yet. Requires standing over the node.
- [List the company address book](https://spreecommerce.org/docs/api-reference/store-api/companies/list-the-company-address-book.md): The labeled ship-to and bill-to sites this node owns. A node with no default of its own falls back to its nearest ancestor when prefilling checkout.
- [Add an address book entry](https://spreecommerce.org/docs/api-reference/store-api/companies/add-an-address-book-entry.md): Adds a labeled site to the node. Pass `default_billing: true` or `default_shipping: true` to make it the default of that kind.
- [Remove an address book entry](https://spreecommerce.org/docs/api-reference/store-api/companies/remove-an-address-book-entry.md): Takes the site out of the address book. Orders already placed to it keep their own copy of the address.
- [Update an address book entry](https://spreecommerce.org/docs/api-reference/store-api/companies/update-an-address-book-entry.md): Renames a site or moves the default ship-to or bill-to flag to it. Only one entry per node holds each default.
- [Revoke an invitation](https://spreecommerce.org/docs/api-reference/store-api/companies/revoke-an-invitation.md): Withdraws a pending invitation, spending its token. Any member with standing over the node may revoke.
- [List the company purchases](https://spreecommerce.org/docs/api-reference/store-api/companies/list-the-company-purchases.md): Completed orders placed for this node and every node below it, so a parent sees what its divisions bought.
- [Look up an invitation](https://spreecommerce.org/docs/api-reference/store-api/companies/look-up-an-invitation.md): Shows what is being joined, so the acceptance page can render before the invitee has an account. Deliberately unauthenticated — the token from the email is the credential. Spent, revoked and expired tokens are not found.
- [Accept an invitation](https://spreecommerce.org/docs/api-reference/store-api/companies/accept-an-invitation.md): Turns the invitation into a membership. Send a registration payload to create the account — it is always created with the invited email — or call it authenticated as the customer who owns that email to bind the invitation to the existing account.

#### Delivery

- [List delivery methods](https://spreecommerce.org/docs/api-reference/store-api/delivery/list-delivery-methods.md): Storefront-visible delivery methods. Filter by fulfillment_type to discover pickup options.
- [List pickup locations](https://spreecommerce.org/docs/api-reference/store-api/delivery/list-pickup-locations.md): Pickup-enabled stock locations for a pickup delivery method. Pass cart_id to keep only locations that can fulfill the whole cart from local stock.

#### Digital Links

- [List my digital links](https://spreecommerce.org/docs/api-reference/store-api/digital-links/list-my-digital-links.md): The signed-in customer's downloads in this store, newest first.
- [Download a digital product](https://spreecommerce.org/docs/api-reference/store-api/digital-links/download-a-digital-product.md): Downloads a digital product file using the digital link token. The token is provided via the `download_url` field on digital links returned with order line items. No API key or authentication required — the token itself grants access.

#### Sellers

- [List sellers](https://spreecommerce.org/docs/api-reference/store-api/sellers/list-sellers.md): Returns the sellers on this marketplace that a shopper can currently buy from. A seller still onboarding, suspended, or away on holiday is not listed — showing them would advertise a seller whose products cannot be bought.
- [Get a seller](https://spreecommerce.org/docs/api-reference/store-api/sellers/get-a-seller.md): Returns a single seller's public profile, by slug or prefixed ID, so a storefront can route `/sellers/sparks-audio` without holding an id.

## OpenAPI Specs

- [store](/docs/api-reference/store.yaml)