# Spree Commerce documentation: v5.x API Reference Admin API Endpoints ## Endpoints - [v5.x / API Reference / Admin API / Endpoints / Customers (28 pages)](https://spreecommerce.org/docs/_llms/v5-x/api-reference/admin-api/endpoints/customers.txt): Documentation for v5.x / API Reference / Admin API / Endpoints / Customers. - [v5.x / API Reference / Admin API / Endpoints / Orders (51 pages)](https://spreecommerce.org/docs/_llms/v5-x/api-reference/admin-api/endpoints/orders.txt): Documentation for v5.x / API Reference / Admin API / Endpoints / Orders. - [v5.x / API Reference / Admin API / Endpoints / Products (26 pages)](https://spreecommerce.org/docs/_llms/v5-x/api-reference/admin-api/endpoints/products.txt): Documentation for v5.x / API Reference / Admin API / Endpoints / Products. - [v5.x / API Reference / Admin API / Endpoints / Sellers (20 pages)](https://spreecommerce.org/docs/_llms/v5-x/api-reference/admin-api/endpoints/sellers.txt): Documentation for v5.x / API Reference / Admin API / Endpoints / Sellers. ### Authentication - [Login](https://spreecommerce.org/docs/api-reference/admin-api/authentication/login.md): Authenticates an admin user and returns a short-lived JWT access token. The rotatable refresh token is set in an HttpOnly cookie — it is not included in the response body. - [Refresh token](https://spreecommerce.org/docs/api-reference/admin-api/authentication/refresh-token.md): Exchanges the HttpOnly refresh-token cookie for a new access JWT and a rotated refresh token cookie. No request body or Authorization header is required — the cookie alone authenticates the call. - [Logout](https://spreecommerce.org/docs/api-reference/admin-api/authentication/logout.md): Revokes the refresh-token cookie, effectively logging the admin out. - [Accept an invitation](https://spreecommerce.org/docs/api-reference/admin-api/authentication/accept-an-invitation.md): Accepts a staff invitation and returns a signed-in admin session, so the new member lands in the dashboard rather than on a login form. - [Get current admin user and permissions](https://spreecommerce.org/docs/api-reference/admin-api/authentication/get-current-admin-user-and-permissions.md): Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks. - [Update the current admin profile](https://spreecommerce.org/docs/api-reference/admin-api/authentication/update-the-current-admin-profile.md): Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`). - [Request password reset](https://spreecommerce.org/docs/api-reference/admin-api/authentication/request-password-reset.md): Requests a password reset email for an admin user. Always returns `202` whether or not the email matches an account, to prevent enumeration. - [Reset password](https://spreecommerce.org/docs/api-reference/admin-api/authentication/reset-password.md): Consumes a password reset token (the `token` query param from the emailed link), sets the new password, and signs the admin in: the response carries a JWT access token and the rotatable refresh token is set in an HttpOnly cookie. The token is single-use — it invalidates as soon as the password chang… - [Check first-run setup availability](https://spreecommerce.org/docs/api-reference/admin-api/authentication/check-first-run-setup-availability.md): Reports whether first-run setup is still available — true only while the installation has no admin user. Unauthenticated; the dashboard login page uses it to offer the setup screen. - [Complete first-run setup](https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup.md): Creates the first admin account and adopts the seeded store, authorized by the one-time setup token printed at install time (rotate it with `bin/rails spree:setup:token`). Issues a JWT access token and a refresh-token cookie exactly like login. Returns 404 once any admin user exists — the flow is cl… - [List countries for first-run setup](https://spreecommerce.org/docs/api-reference/admin-api/authentication/list-countries-for-first-run-setup.md): Countries the store can be set up in, each with the currency and official languages derived from it. Unauthenticated, because the setup screen runs before any credential exists. Returns 404 once any admin user exists. ### Allowed Origins - [List allowed origins](https://spreecommerce.org/docs/api-reference/admin-api/allowed-origins/list-allowed-origins.md): Returns the CORS allowlist for the current store. Each entry is a bare `scheme://host[:port]` permitted to call the admin API from a browser. Backs the `Rack::Cors` allowlist and the CSRF boundary of the admin cookie session (see `docs/plans/5.5-admin-auth-cookie-refresh.md`). - [Create an allowed origin](https://spreecommerce.org/docs/api-reference/admin-api/allowed-origins/create-an-allowed-origin.md): Adds an origin to the admin CORS allowlist. The value must be a bare `scheme://host[:port]` (no path, query, or fragment) and use `http` or `https`. - [Get an allowed origin](https://spreecommerce.org/docs/api-reference/admin-api/allowed-origins/get-an-allowed-origin.md): Returns a single allowed origin by prefixed ID. - [Delete an allowed origin](https://spreecommerce.org/docs/api-reference/admin-api/allowed-origins/delete-an-allowed-origin.md): Removes an origin from the admin CORS allowlist. After deletion the admin SPA running at that origin will no longer be able to call the admin API from a browser. - [Update an allowed origin](https://spreecommerce.org/docs/api-reference/admin-api/allowed-origins/update-an-allowed-origin.md): Updates an existing allowed origin. ### API Keys - [List API keys](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/list-api-keys.md): Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create. - [Create an API key](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/create-an-api-key.md): Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use. - [Show an API key](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/show-an-api-key.md): **Required scope:** `read_api_keys` (for API-key authentication). - [Delete an API key](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/delete-an-api-key.md): **Required scope:** `write_api_keys` (for API-key authentication). - [Update an API key](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/update-an-api-key.md): Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one. - [Describe the current API key](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/describe-the-current-api-key.md): Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe. - [Revoke an API key](https://spreecommerce.org/docs/api-reference/admin-api/api-keys/revoke-an-api-key.md): Marks the key revoked. Future requests using its token will fail; the row is preserved for audit. ### Categories - [List categories](https://spreecommerce.org/docs/api-reference/admin-api/categories/list-categories.md): Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded). - [Create a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/create-a-category.md): Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category. - [Get a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/get-a-category.md): Returns a single category by ID. - [Delete a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/delete-a-category.md): Deletes a category and its descendants. - [Update a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/update-a-category.md): Updates a category. - [Reposition a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/reposition-a-category.md): Moves a category to a new parent and/or index within the tree. - [List category products](https://spreecommerce.org/docs/api-reference/admin-api/categories/list-category-products.md): Products classified under the category, ordered by their classification position. - [Add products to a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/add-products-to-a-category.md): Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added. - [Remove products from a category](https://spreecommerce.org/docs/api-reference/admin-api/categories/remove-products-from-a-category.md): Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed. - [Reposition a category product](https://spreecommerce.org/docs/api-reference/admin-api/categories/reposition-a-category-product.md): Moves a product to a new index among the category's products. - [List category custom fields](https://spreecommerce.org/docs/api-reference/admin-api/categories/list-category-custom-fields.md): Returns the category's custom field values. ### Channels - [List channels](https://spreecommerce.org/docs/api-reference/admin-api/channels/list-channels.md): Returns the channels configured for the current store. - [Create a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/create-a-channel.md): Creates a new channel on the current store. `code` is normalized to a URL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's derived from `name`. - [Get a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/get-a-channel.md): **Required scope:** `read_settings` (for API-key authentication). - [Delete a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/delete-a-channel.md): **Required scope:** `write_settings` (for API-key authentication). - [Update a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/update-a-channel.md): **Required scope:** `write_settings` (for API-key authentication). - [Publish products on a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/publish-products-on-a-channel.md): Publishes the listed products on this channel. Idempotent — re-publishing an already-published product updates its publication window. Products from sibling stores are silently dropped. - [Unpublish products from a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/unpublish-products-from-a-channel.md): Unpublishes the listed products from this channel. - [List order routing rules for a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/list-order-routing-rules-for-a-channel.md): Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide. - [Create an order routing rule on a channel](https://spreecommerce.org/docs/api-reference/admin-api/channels/create-an-order-routing-rule-on-a-channel.md): Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a valid… - [Delete an order routing rule](https://spreecommerce.org/docs/api-reference/admin-api/channels/delete-an-order-routing-rule.md): **Required scope:** `write_settings` (for API-key authentication). - [Update an order routing rule](https://spreecommerce.org/docs/api-reference/admin-api/channels/update-an-order-routing-rule.md): Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead. - [List available order routing rule types](https://spreecommerce.org/docs/api-reference/admin-api/channels/list-available-order-routing-rule-types.md): Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the "Add rule" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`. ### Custom Fields - [List custom field definitions](https://spreecommerce.org/docs/api-reference/admin-api/custom-fields/list-custom-field-definitions.md): Returns all defined custom fields. Filter by `?q[resource_type_eq]=product` to narrow to one parent type. - [Create a custom field definition](https://spreecommerce.org/docs/api-reference/admin-api/custom-fields/create-a-custom-field-definition.md): **Required scope:** `write_settings` (for API-key authentication). - [Show a custom field definition](https://spreecommerce.org/docs/api-reference/admin-api/custom-fields/show-a-custom-field-definition.md): **Required scope:** `read_settings` (for API-key authentication). - [Delete a custom field definition](https://spreecommerce.org/docs/api-reference/admin-api/custom-fields/delete-a-custom-field-definition.md): Deletes the definition and cascades to all custom field values referencing it. - [Update a custom field definition](https://spreecommerce.org/docs/api-reference/admin-api/custom-fields/update-a-custom-field-definition.md): **Required scope:** `write_settings` (for API-key authentication). ### Customer Groups - [List customer groups](https://spreecommerce.org/docs/api-reference/admin-api/customer-groups/list-customer-groups.md): Returns the customer groups configured for the current store. Groups segment customers for targeted promotions (see the `customer_group` promotion rule) and reporting. The list endpoint never embeds the member list — fetch a single group with `?expand=customers` if you need them inline, or query `/a… - [Create a customer group](https://spreecommerce.org/docs/api-reference/admin-api/customer-groups/create-a-customer-group.md): Creates a customer group in the current store. `customer_ids` is optional; when present, customers are attached at create time. Pass prefixed IDs (e.g. `cus_…`) — the server decodes them automatically. - [Get a customer group](https://spreecommerce.org/docs/api-reference/admin-api/customer-groups/get-a-customer-group.md): Returns a single customer group. Pass `?expand=customers` to embed the full member list inline (recommended only for single-record reads — embed cost scales with membership size). - [Delete a customer group](https://spreecommerce.org/docs/api-reference/admin-api/customer-groups/delete-a-customer-group.md): Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped. - [Update a customer group](https://spreecommerce.org/docs/api-reference/admin-api/customer-groups/update-a-customer-group.md): Updates name, description, or membership. `customer_ids` is a full-set replacement — the server reconciles the membership to match the array, adding new IDs and removing ones not present. Send `customer_ids: []` to clear all members. ### Email Templates - [List email templates](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/list-email-templates.md): Returns every email template merchants may edit: the emails customers receive, the email layout and the shared partials. Each shows what customers receive now (the store's published version, else Spree's default) and any draft in progress. Staff emails are not editable. - [Get an email template](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/get-an-email-template.md): Returns the template for one language: what customers receive now, Spree's default, and the draft with its `lock_version`. When Spree's default changed since the store's version started from it, `default_changed` is true and `base_body` holds the default it started from, to compare with `default_bod… - [Revert an email template to Spree's default](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/revert-an-email-template-to-sprees-default.md): Goes back to Spree's default for one language and discards the draft. The store's published versions are kept, so one can still be restored. - [Save an email template draft](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/save-an-email-template-draft.md): Saves the draft, in any state; customers keep receiving the published version until it is published. Send the `lock_version` the draft was loaded with: a save made from an older copy is refused with 409, naming who saved last. The first save starts from what is published, else Spree's default. - [Discard an email template draft](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/discard-an-email-template-draft.md): **Required scope:** `write_email_templates` (for API-key authentication). - [Publish an email template draft](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/publish-an-email-template-draft.md): Makes the draft what customers receive. The draft is first rendered with sample data; one that does not render (for the layout or a partial: in any email using it) is refused with 422, listing each problem with its email and line. - [Preview an email template](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/preview-an-email-template.md): Renders the template with sample data built from the store's latest matching record, or the one `record_id` names, and returns the email with the variables it was rendered with. An unsaved `subject` and `body` take the place of the current version. The layout and partials render inside an email, `em… - [Send a test email](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/send-a-test-email.md): Sends the template, rendered as the preview renders it, to the signed-in admin, and never to another address: the sample data comes from a real customer's records. Takes the same body as the preview. - [List records to preview an email template with](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/list-records-to-preview-an-email-template-with.md): The store's five latest records the template can be previewed with, newest first, to pass as `record_id` to the preview. For the layout and partials, those of the email `email_key` names. Empty for an email that needs no record. - [List email template revisions](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/list-email-template-revisions.md): Every version of the template published in one language, newest first. Reverting to Spree's default keeps them. - [Restore an email template revision](https://spreecommerce.org/docs/api-reference/admin-api/email-templates/restore-an-email-template-revision.md): Copies the revision into the draft, to be published like any change. Send the draft's `lock_version` when one is open, as when saving it. ### Exports - [List exports](https://spreecommerce.org/docs/api-reference/admin-api/exports/list-exports.md): Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`). - [Create an export](https://spreecommerce.org/docs/api-reference/admin-api/exports/create-an-export.md): Queues a CSV export. The `type` selects the dataset; `search_params` is an optional Ransack query (same shape used by the `q[...]` params on list endpoints) that filters which records are exported. Pass `record_selection: "all"` to clear the filter server-side and export everything in scope. - [Show an export](https://spreecommerce.org/docs/api-reference/admin-api/exports/show-an-export.md): Returns export status. While `done` is `false`, the SPA continues polling. - [Delete an export](https://spreecommerce.org/docs/api-reference/admin-api/exports/delete-an-export.md): Removes the export and purges its attachment. - [Download an export](https://spreecommerce.org/docs/api-reference/admin-api/exports/download-an-export.md): Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level na… ### Files - [Upload a file](https://spreecommerce.org/docs/api-reference/admin-api/files/upload-a-file.md): Accepts a file and returns a `signed_id` to send to the endpoint that uses it — `signed_id` on product media, `avatar_signed_id` on a customer, `attachment_signed_id` on an import, and so on. ### Fulfillments - [List fulfillments](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/list-fulfillments.md): Returns all shipments for an order. - [Create a fulfillment](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/create-a-fulfillment.md): Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange an… - [Show a shipment](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/show-a-shipment.md): Returns details of a specific shipment. - [Update a shipment](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/update-a-shipment.md): Updates a fulfillment (tracking, delivery rate). - [Fulfill a fulfillment](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/fulfill-a-fulfillment.md): Marks a fulfillment as fulfilled. - [Mark a fulfillment delivered](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/mark-a-fulfillment-delivered.md): Records that the customer received the goods. Only a fulfilled shipment can be marked delivered. - [Cancel a fulfillment](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/cancel-a-fulfillment.md): Cancels a fulfillment. - [Split a fulfillment](https://spreecommerce.org/docs/api-reference/admin-api/fulfillments/split-a-fulfillment.md): Transfers items from this shipment to a new shipment at a different stock location. ### Gift Cards - [List gift card batches](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/list-gift-card-batches.md): Returns the gift card batches issued by the current store. Each batch groups the cards generated together for a campaign or bulk-issuance — the cards themselves live under `/admin/gift_cards` and reference the batch via `gift_card_batch_id`. - [Create a gift card batch](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/create-a-gift-card-batch.md): Issues a batch of gift cards in a single call. The server generates `codes_count` cards inline for small batches (configurable via `Spree.config.gift_card_batch_web_limit`, default 500) or enqueues a background job for larger ones. Each card's code is the batch `prefix` followed by random hex. - [Get a gift card batch](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/get-a-gift-card-batch.md): Returns a single batch. - [List gift cards](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/list-gift-cards.md): Returns the gift cards issued by the current store. Filter by `q[code_cont]` for code search, `q[customer_id_eq]` for cards issued to a specific customer, or `q[status_eq]` for status filtering. - [Create a gift card](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/create-a-gift-card.md): Issues a gift card scoped to the current store. The code is auto-generated when omitted. `currency` defaults to the store's configured currency. Pass `customer_id` (prefixed ID) to attach the card to a specific customer. - [Get a gift card](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/get-a-gift-card.md): Returns a single gift card. - [Delete a gift card](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/delete-a-gift-card.md): Deletes an unused gift card. Cards that have been redeemed or partially redeemed cannot be deleted and return 422. - [Update a gift card](https://spreecommerce.org/docs/api-reference/admin-api/gift-cards/update-a-gift-card.md): Updates an active gift card's editable attributes. Redeemed or partially-redeemed cards cannot be edited. ### Imports - [List imports](https://spreecommerce.org/docs/api-reference/admin-api/imports/list-imports.md): Returns CSV imports queued or completed for the current store. - [Create an import](https://spreecommerce.org/docs/api-reference/admin-api/imports/create-an-import.md): Queues a CSV import. Upload the file first via `POST /api/v3/admin/files` and pass the returned `signed_id` as `attachment_signed_id`. On success the import is in the `mapping` state and the response carries the mapping payload: `schema_fields` (the canonical columns for the type), `csv_headers`, a… - [Download an import template](https://spreecommerce.org/docs/api-reference/admin-api/imports/download-an-import-template.md): Returns a CSV header row for the given import type, including the custom field columns available for the model. - [Download an example import file](https://spreecommerce.org/docs/api-reference/admin-api/imports/download-an-example-import-file.md): Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file. - [Show an import](https://spreecommerce.org/docs/api-reference/admin-api/imports/show-an-import.md): Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status`… - [Delete an import](https://spreecommerce.org/docs/api-reference/admin-api/imports/delete-an-import.md): Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed. - [Download the originally uploaded file](https://spreecommerce.org/docs/api-reference/admin-api/imports/download-the-originally-uploaded-file.md): Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL. - [Complete mapping and start processing](https://spreecommerce.org/docs/api-reference/admin-api/imports/complete-mapping-and-start-processing.md): Applies the submitted column mappings, then starts row processing. Omit `mappings` to accept the auto-assigned ones from the create response. Returns 422 when a required schema field is left unmapped (`details.missing_required_fields`) or a file column is assigned twice. - [Retry failed rows](https://spreecommerce.org/docs/api-reference/admin-api/imports/retry-failed-rows.md): Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows. - [List import rows](https://spreecommerce.org/docs/api-reference/admin-api/imports/list-import-rows.md): Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`. ### Markets - [List markets](https://spreecommerce.org/docs/api-reference/admin-api/markets/list-markets.md): Returns the markets configured for the current store. Markets are store-scoped and ordered by `position` (an `acts_as_list` column — update the order via `PATCH /markets/{id}` with `position`). - [Create a market](https://spreecommerce.org/docs/api-reference/admin-api/markets/create-a-market.md): Creates a new market for the current store. - [Get a market](https://spreecommerce.org/docs/api-reference/admin-api/markets/get-a-market.md): **Required scope:** `read_settings` (for API-key authentication). - [Delete a market](https://spreecommerce.org/docs/api-reference/admin-api/markets/delete-a-market.md): Soft-deletes the market (sets `deleted_at`). The default market and the last remaining market in a store cannot be deleted — both return 422 with a `validation_error`. - [Update a market](https://spreecommerce.org/docs/api-reference/admin-api/markets/update-a-market.md): Updates an existing market. Pass `country_codes` to replace the market's country list (full-set update), `supported_locales` to replace the supported locales, or `position` to reorder the market within the store. ### Option Types - [List option type custom fields](https://spreecommerce.org/docs/api-reference/admin-api/option-types/list-option-type-custom-fields.md): Returns the option type's custom field values. - [List option types](https://spreecommerce.org/docs/api-reference/admin-api/option-types/list-option-types.md): Returns a paginated list of option types. - [Create an option type](https://spreecommerce.org/docs/api-reference/admin-api/option-types/create-an-option-type.md): Creates a new option type. Supports nested option values. - [Get an option type](https://spreecommerce.org/docs/api-reference/admin-api/option-types/get-an-option-type.md): Returns a single option type by ID, including its option values. - [Delete an option type](https://spreecommerce.org/docs/api-reference/admin-api/option-types/delete-an-option-type.md): Deletes an option type. - [Update an option type](https://spreecommerce.org/docs/api-reference/admin-api/option-types/update-an-option-type.md): Updates an option type. Supports updating nested option values. ### Payment Methods - [List payment methods](https://spreecommerce.org/docs/api-reference/admin-api/payment-methods/list-payment-methods.md): Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source. - [Create a payment method](https://spreecommerce.org/docs/api-reference/admin-api/payment-methods/create-a-payment-method.md): Adds a payment method to the store. `type` is a shorthand from the payment method types endpoint, and `preferences` takes the values its preference schema declares (gateway credentials among them). - [List available payment provider types](https://spreecommerce.org/docs/api-reference/admin-api/payment-methods/list-available-payment-provider-types.md): Returns every registered payment provider with the JSON Schema of its `preferences`. `installed` marks a provider the store already has, which a "Provider" picker leaves out. - [Show a payment method](https://spreecommerce.org/docs/api-reference/admin-api/payment-methods/show-a-payment-method.md): Returns a payment method by ID. - [Update a payment method](https://spreecommerce.org/docs/api-reference/admin-api/payment-methods/update-a-payment-method.md): Updates a payment method. Its `type` is fixed once created. ### Payments - [List payments](https://spreecommerce.org/docs/api-reference/admin-api/payments/list-payments.md): Returns all payments for an order. - [Create a payment](https://spreecommerce.org/docs/api-reference/admin-api/payments/create-a-payment.md): Creates a new payment for the order. - [Show a payment](https://spreecommerce.org/docs/api-reference/admin-api/payments/show-a-payment.md): Returns details of a specific payment. - [Capture a payment](https://spreecommerce.org/docs/api-reference/admin-api/payments/capture-a-payment.md): Captures a pending payment, in full or for part of the authorized amount. - [Void a payment](https://spreecommerce.org/docs/api-reference/admin-api/payments/void-a-payment.md): Voids a payment. ### Pricing - [List price lists](https://spreecommerce.org/docs/api-reference/admin-api/pricing/list-price-lists.md): Returns the price lists configured for the current store. - [Create a price list](https://spreecommerce.org/docs/api-reference/admin-api/pricing/create-a-price-list.md): Creates a new draft price list. - [Get a price list](https://spreecommerce.org/docs/api-reference/admin-api/pricing/get-a-price-list.md): **Required scope:** `read_products` (for API-key authentication). - [Delete a price list](https://spreecommerce.org/docs/api-reference/admin-api/pricing/delete-a-price-list.md): Soft-deletes the price list. Associated prices are removed asynchronously. - [Update a price list](https://spreecommerce.org/docs/api-reference/admin-api/pricing/update-a-price-list.md): Updates a price list. The optional `rules:` array reconciles nested STI-typed price rules in a single round-trip — existing rules update by `id`, new rules build, missing rules destroy. Mirrors the promotion editor's "save the whole thing on Save" pattern. - [Activate a price list](https://spreecommerce.org/docs/api-reference/admin-api/pricing/activate-a-price-list.md): Transitions a draft / inactive list to `active`. If `starts_at` is in the future the list is marked `scheduled` instead, matching the legacy admin behaviour. - [Deactivate a price list](https://spreecommerce.org/docs/api-reference/admin-api/pricing/deactivate-a-price-list.md): **Required scope:** `write_products` (for API-key authentication). - [List prices](https://spreecommerce.org/docs/api-reference/admin-api/pricing/list-prices.md): Generic prices endpoint covering both base prices and price-list overrides. Filter with Ransack: `q[price_list_id_eq]=…`, `q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only). - [Create a price](https://spreecommerce.org/docs/api-reference/admin-api/pricing/create-a-price.md): Creates a single price. Omit `price_list_id` to create a base price. For more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`. - [Get a price](https://spreecommerce.org/docs/api-reference/admin-api/pricing/get-a-price.md): **Required scope:** `read_products` (for API-key authentication). - [Delete a price](https://spreecommerce.org/docs/api-reference/admin-api/pricing/delete-a-price.md): Soft-deletes the price (acts_as_paranoid). - [Update a price](https://spreecommerce.org/docs/api-reference/admin-api/pricing/update-a-price.md): **Required scope:** `write_products` (for API-key authentication). - [Bulk-upsert prices](https://spreecommerce.org/docs/api-reference/admin-api/pricing/bulk-upsert-prices.md): Upserts a batch of prices in a single SQL round trip. - [Bulk-delete prices](https://spreecommerce.org/docs/api-reference/admin-api/pricing/bulk-delete-prices.md): Soft-deletes each price in `ids`. Returns the count actually destroyed. ### Policies - [List policies](https://spreecommerce.org/docs/api-reference/admin-api/policies/list-policies.md): Returns the store's policy documents — terms of service, privacy policy, returns policy, shipping policy, and any others the merchant has written. Every store is created with the four standard policies, named but empty. - [Create a policy](https://spreecommerce.org/docs/api-reference/admin-api/policies/create-a-policy.md): Creates a policy. `body` accepts HTML and is sanitized before it is stored; the stored markup is returned as `body_html`, and `body` reads back as plain text. - [Get a policy](https://spreecommerce.org/docs/api-reference/admin-api/policies/get-a-policy.md): Returns a single policy, addressed by prefixed ID or by slug. - [Delete a policy](https://spreecommerce.org/docs/api-reference/admin-api/policies/delete-a-policy.md): Deletes a policy. The four policies a store is created with can be deleted like any other — they are conventions, not fixtures. - [Update a policy](https://spreecommerce.org/docs/api-reference/admin-api/policies/update-a-policy.md): Updates a policy. `body` accepts HTML and is sanitized before it is stored. ### Reasons - [List claim reasons](https://spreecommerce.org/docs/api-reference/admin-api/reasons/list-claim-reasons.md): Why a customer raised a claim — what the merchant got wrong, rather than a change of mind. - [Create a claim reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/create-a-claim-reason.md): Adds a claim reason to this store. Names are unique per store, ignoring case. - [Get a claim reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/get-a-claim-reason.md): Returns a single claim reason by prefixed ID. - [Delete a claim reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/delete-a-claim-reason.md): Removes a claim reason the store no longer uses. A reason already recorded on a document is refused — deactivate it instead, so the history it explains stays readable. - [Update a claim reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/update-a-claim-reason.md): Renames a claim reason or retires it. Deactivating keeps it on the records that already carry it while removing it from the pickers. - [List order cancellation reasons](https://spreecommerce.org/docs/api-reference/admin-api/reasons/list-order-cancellation-reasons.md): Why an order was called off before it shipped. Staff pick one when canceling. - [Create a order cancellation reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/create-a-order-cancellation-reason.md): Adds a order cancellation reason to this store. Names are unique per store, ignoring case. - [Get a order cancellation reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/get-a-order-cancellation-reason.md): Returns a single order cancellation reason by prefixed ID. - [Delete a order cancellation reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/delete-a-order-cancellation-reason.md): Removes a order cancellation reason the store no longer uses. A reason already recorded on a document is refused — deactivate it instead, so the history it explains stays readable. - [Update a order cancellation reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/update-a-order-cancellation-reason.md): Renames a order cancellation reason or retires it. Deactivating keeps it on the records that already carry it while removing it from the pickers. - [List refund reasons](https://spreecommerce.org/docs/api-reference/admin-api/reasons/list-refund-reasons.md): Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion. - [Create a refund reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/create-a-refund-reason.md): Adds a refund reason to this store. Names are unique per store, ignoring case. - [Get a refund reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/get-a-refund-reason.md): Returns a single refund reason by prefixed ID. - [Delete a refund reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/delete-a-refund-reason.md): Removes a refund reason the store no longer uses. A reason already recorded on a document is refused — deactivate it instead, so the history it explains stays readable. - [Update a refund reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/update-a-refund-reason.md): Renames a refund reason or retires it. Deactivating keeps it on the records that already carry it while removing it from the pickers. - [List return reasons](https://spreecommerce.org/docs/api-reference/admin-api/reasons/list-return-reasons.md): Why a customer is sending items back. Shared by returns and exchanges. - [Create a return reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/create-a-return-reason.md): Adds a return reason to this store. Names are unique per store, ignoring case. - [Get a return reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/get-a-return-reason.md): Returns a single return reason by prefixed ID. - [Delete a return reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/delete-a-return-reason.md): Removes a return reason the store no longer uses. A reason already recorded on a document is refused — deactivate it instead, so the history it explains stays readable. - [Update a return reason](https://spreecommerce.org/docs/api-reference/admin-api/reasons/update-a-return-reason.md): Renames a return reason or retires it. Deactivating keeps it on the records that already carry it while removing it from the pickers. ### Promotions - [List coupon codes for a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/list-coupon-codes-for-a-promotion.md): Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them. - [List actions for a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/list-actions-for-a-promotion.md): **Required scope:** `read_promotions` (for API-key authentication). - [Create an action on a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/create-an-action-on-a-promotion.md): Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). - [Delete an action from a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/delete-an-action-from-a-promotion.md): **Required scope:** `write_promotions` (for API-key authentication). - [Update an action on a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/update-an-action-on-a-promotion.md): Changes an action's settings. For adjustment actions, `calculator` sets the calculator and its preferences; sending a different calculator `type` swaps it. The action's own `type` is fixed once created. - [List rules for a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/list-rules-for-a-promotion.md): **Required scope:** `read_promotions` (for API-key authentication). - [Create a rule on a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/create-a-rule-on-a-promotion.md): Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). - [Delete a rule from a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/delete-a-rule-from-a-promotion.md): **Required scope:** `write_promotions` (for API-key authentication). - [Update a rule's preferences](https://spreecommerce.org/docs/api-reference/admin-api/promotions/update-a-rules-preferences.md): **Required scope:** `write_promotions` (for API-key authentication). - [List promotions](https://spreecommerce.org/docs/api-reference/admin-api/promotions/list-promotions.md): Returns the store's promotions, including manual coupon and automatic promotions. - [Create a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/create-a-promotion.md): Creates a new promotion. `code` is required for single-code coupon promotions; pass `multi_codes: true` with `number_of_codes` to auto-generate a batch. - [Show a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/show-a-promotion.md): **Required scope:** `read_promotions` (for API-key authentication). - [Delete a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/delete-a-promotion.md): **Required scope:** `write_promotions` (for API-key authentication). - [Update a promotion](https://spreecommerce.org/docs/api-reference/admin-api/promotions/update-a-promotion.md): Updates a promotion. The `rules` and `actions` arrays are treated as a *desired set* — rows with `id` update in place, rows without `id` are built fresh, and any existing row not present in the array is destroyed. Pass `rules: []` or `actions: []` to clear them. - [List available promotion action types](https://spreecommerce.org/docs/api-reference/admin-api/promotions/list-available-promotion-action-types.md): Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the "Add action" picker and render generic preference forms. - [List available promotion rule types](https://spreecommerce.org/docs/api-reference/admin-api/promotions/list-available-promotion-rule-types.md): Returns the registered Spree::PromotionRule subclasses with their preference schemas. ### Refunds - [List refunds](https://spreecommerce.org/docs/api-reference/admin-api/refunds/list-refunds.md): Returns all refunds for an order. - [Create a refund](https://spreecommerce.org/docs/api-reference/admin-api/refunds/create-a-refund.md): Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway. ### Settings - [List supported locales](https://spreecommerce.org/docs/api-reference/admin-api/settings/list-supported-locales.md): Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags. - [Get the current store](https://spreecommerce.org/docs/api-reference/admin-api/settings/get-the-current-store.md): Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter. - [Update the current store](https://spreecommerce.org/docs/api-reference/admin-api/settings/update-the-current-store.md): Updates the current store configuration. - [List tags](https://spreecommerce.org/docs/api-reference/admin-api/settings/list-tags.md): Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers. - [List tax categories](https://spreecommerce.org/docs/api-reference/admin-api/settings/list-tax-categories.md): Returns the tax categories products and delivery methods can be assigned to, which tax rates then apply to. - [Create a tax category](https://spreecommerce.org/docs/api-reference/admin-api/settings/create-a-tax-category.md): Creates a tax category. `tax_code` is the code a tax provider uses to classify the goods in it. - [Update a tax category](https://spreecommerce.org/docs/api-reference/admin-api/settings/update-a-tax-category.md): **Required scope:** `write_settings` (for API-key authentication). - [List tax rates](https://spreecommerce.org/docs/api-reference/admin-api/settings/list-tax-rates.md): Returns the store's tax rates. Rates are the entire configuration of the built-in tax provider: each pairs a tax category with a jurisdiction (a country, optionally narrowed to one state) and a percentage, and decides whether the tax is already included in the product price (VAT-style) or added on t… - [Create a tax rate](https://spreecommerce.org/docs/api-reference/admin-api/settings/create-a-tax-rate.md): Creates a tax rate for the current store. Give either `rate` as a decimal string (`"0.19"`) or `rate_percent` as a percentage string (`"19"`). - [Get a tax rate](https://spreecommerce.org/docs/api-reference/admin-api/settings/get-a-tax-rate.md): **Required scope:** `read_settings` (for API-key authentication). - [Delete a tax rate](https://spreecommerce.org/docs/api-reference/admin-api/settings/delete-a-tax-rate.md): Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot. - [Update a tax rate](https://spreecommerce.org/docs/api-reference/admin-api/settings/update-a-tax-rate.md): **Required scope:** `write_settings` (for API-key authentication). - [List translatable resources](https://spreecommerce.org/docs/api-reference/admin-api/settings/list-translatable-resources.md): Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically. - [Batch upsert translations](https://spreecommerce.org/docs/api-reference/admin-api/settings/batch-upsert-translations.md): Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do. - [Check for a newer Spree release](https://spreecommerce.org/docs/api-reference/admin-api/settings/check-for-a-newer-spree-release.md): Whether a newer Spree release exists. The server asks spreecloud.io when it has no cached answer, for at most two seconds. A successful answer is kept for a day; a failed check is retried after an hour, so the call that retries it waits on it again. `checked_at` is null when the update check is turn… ### Staff - [List staff](https://spreecommerce.org/docs/api-reference/admin-api/staff/list-staff.md): Returns admin users with at least one role assignment on the current store. - [Show a staff member](https://spreecommerce.org/docs/api-reference/admin-api/staff/show-a-staff-member.md): **Required scope:** `read_staff` (for API-key authentication). - [Remove a staff member from this store](https://spreecommerce.org/docs/api-reference/admin-api/staff/remove-a-staff-member-from-this-store.md): Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores. Removing a role needs the same rights as granting it, and the store always keeps at least one admin. - [Update a staff member](https://spreecommerce.org/docs/api-reference/admin-api/staff/update-a-staff-member.md): Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store. - [List invitations](https://spreecommerce.org/docs/api-reference/admin-api/staff/list-invitations.md): Returns invitations for the current store, including pending and accepted. - [Create an invitation](https://spreecommerce.org/docs/api-reference/admin-api/staff/create-an-invitation.md): Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback. - [Revoke an invitation](https://spreecommerce.org/docs/api-reference/admin-api/staff/revoke-an-invitation.md): **Required scope:** `write_staff` (for API-key authentication). - [Get an invitation acceptance link](https://spreecommerce.org/docs/api-reference/admin-api/staff/get-an-invitation-acceptance-link.md): Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it. - [Resend an invitation](https://spreecommerce.org/docs/api-reference/admin-api/staff/resend-an-invitation.md): Issues a fresh token and dispatches the invitation email again. - [List the permission catalog](https://spreecommerce.org/docs/api-reference/admin-api/staff/list-the-permission-catalog.md): Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential. - [List roles](https://spreecommerce.org/docs/api-reference/admin-api/staff/list-roles.md): Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows. - [Create a role](https://spreecommerce.org/docs/api-reference/admin-api/staff/create-a-role.md): Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold. - [Delete a role](https://spreecommerce.org/docs/api-reference/admin-api/staff/delete-a-role.md): Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations. - [Update a role](https://spreecommerce.org/docs/api-reference/admin-api/staff/update-a-role.md): Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes. ### Stock Locations - [List stock locations](https://spreecommerce.org/docs/api-reference/admin-api/stock-locations/list-stock-locations.md): Returns the configured stock locations. Stock locations are global (shared across stores). Filter with Ransack predicates such as `q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or `q[name_cont]`. - [Create a stock location](https://spreecommerce.org/docs/api-reference/admin-api/stock-locations/create-a-stock-location.md): Creates a new stock location. - [Get a stock location](https://spreecommerce.org/docs/api-reference/admin-api/stock-locations/get-a-stock-location.md): Returns a single stock location by prefixed ID. - [Delete a stock location](https://spreecommerce.org/docs/api-reference/admin-api/stock-locations/delete-a-stock-location.md): Soft-deletes the stock location (sets `deleted_at`). Existing fulfillments that referenced it keep the historical record via `Spree::StockLocation.with_deleted`. - [Update a stock location](https://spreecommerce.org/docs/api-reference/admin-api/stock-locations/update-a-stock-location.md): Updates an existing stock location. Same address-field conventions as the create endpoint. ### Store Credits - [List store credits](https://spreecommerce.org/docs/api-reference/admin-api/store-credits/list-store-credits.md): Returns every store credit in the current store, across all customers. Read-only: issuing, editing and deleting a credit stays nested under the customer that holds it. - [Retrieve a store credit](https://spreecommerce.org/docs/api-reference/admin-api/store-credits/retrieve-a-store-credit.md): **Required scope:** `read_store_credits` (for API-key authentication). - [List a store credit's ledger](https://spreecommerce.org/docs/api-reference/admin-api/store-credits/list-a-store-credits-ledger.md): Every movement of the credit's balance, newest first: allocated when issued, authorized when a checkout starts against it, captured when that order is paid, and voided or credited back if it is cancelled. ### Variants - [List variant custom fields](https://spreecommerce.org/docs/api-reference/admin-api/variants/list-variant-custom-fields.md): Returns the variant's custom field values. - [List product variants](https://spreecommerce.org/docs/api-reference/admin-api/variants/list-product-variants.md): Returns a paginated list of variants for a product, including the default variant. - [Create a variant](https://spreecommerce.org/docs/api-reference/admin-api/variants/create-a-variant.md): Creates a new variant for a product. Supports nested prices and stock items. - [Get a variant](https://spreecommerce.org/docs/api-reference/admin-api/variants/get-a-variant.md): Returns a single variant by ID. - [Delete a variant](https://spreecommerce.org/docs/api-reference/admin-api/variants/delete-a-variant.md): Soft-deletes a variant. - [Update a variant](https://spreecommerce.org/docs/api-reference/admin-api/variants/update-a-variant.md): Updates a variant. Only provided fields are updated. - [List variants](https://spreecommerce.org/docs/api-reference/admin-api/variants/list-variants.md): Returns every variant in the store across all products, for pickers and stock views that are not tied to one product. ### Webhooks - [List webhook deliveries](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/list-webhook-deliveries.md): Returns delivery attempts for the given endpoint, most recent first. Each row carries the original request payload, the response code (when the receiver replied), the execution time, and any transport error — everything needed to audit failures and decide whether to redeliver. - [Get a webhook delivery](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/get-a-webhook-delivery.md): Returns a single delivery attempt with the full request payload and the response body the receiver returned. Use this for ad-hoc debug of failed deliveries. - [Redeliver a webhook delivery](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/redeliver-a-webhook-delivery.md): Creates a new delivery row with the same payload + event_name and queues it. The original row is preserved for audit history. - [List webhook endpoints](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/list-webhook-endpoints.md): Returns outbound webhook subscriptions for the current store. Each endpoint receives a signed POST when any subscribed event fires. `secret_key` is `null` on list reads — the plaintext is delivered exactly once on create. - [Create a webhook endpoint](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/create-a-webhook-endpoint.md): Creates a new outbound webhook subscription. The plaintext `secret_key` is returned **once** in this response — persist it immediately to verify incoming webhook signatures. Subsequent reads return `null` for the secret. Pass an empty `subscriptions` array or omit it to receive every event. - [Get a webhook endpoint](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/get-a-webhook-endpoint.md): Returns a single webhook endpoint by prefixed ID. - [Delete a webhook endpoint](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/delete-a-webhook-endpoint.md): Soft-deletes the endpoint and stops future deliveries. - [Update a webhook endpoint](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/update-a-webhook-endpoint.md): Updates name, URL, active flag, or the event subscription list. Toggling `active` here is equivalent to calling `disable`/`enable` without an audit reason. - [Send a test delivery](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/send-a-test-delivery.md): Creates a `webhook.test` delivery record and queues it. Use this to verify the endpoint is reachable and your signature verification accepts Spree's payloads. - [Re-enable a webhook endpoint](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/re-enable-a-webhook-endpoint.md): Re-enables an endpoint that was manually or automatically disabled. - [Disable a webhook endpoint](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/disable-a-webhook-endpoint.md): Manually pauses an endpoint. Unlike auto-disable (triggered after repeated delivery failures), no notification email is sent. - [List webhook events](https://spreecommerce.org/docs/api-reference/admin-api/webhooks/list-webhook-events.md): Returns every event a webhook endpoint can subscribe to, including those installed extensions declare. Credential events reach only endpoints that name them, and subscribing to one needs the permission listed; deprecated events name their replacement. ### Catalogs - [List catalogs](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/list-catalogs.md): Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments. - [Create a catalog](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/create-a-catalog.md): Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards. - [Update a catalog](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/update-a-catalog.md): Updates a catalog and its commercial terms. Only the attributes sent change. - [Assign a catalog to an audience](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/assign-a-catalog-to-an-audience.md): Shows the catalog to an audience. A company assignment covers the node and its whole subtree. - [List catalog products](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/list-catalog-products.md): The catalog's curated assortment, listed by product name — membership carries no order. - [Add products to a catalog](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/add-products-to-a-catalog.md): Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added. - [Remove products from a catalog](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/remove-products-from-a-catalog.md): Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed. - [List catalog order minimums](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/list-catalog-order-minimums.md): The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted. - [Create a catalog order minimum](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/create-a-catalog-order-minimum.md): Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it. - [Delete a catalog order minimum](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/delete-a-catalog-order-minimum.md): Lifts the threshold for one currency, so orders in it may come to any total. - [Update a catalog order minimum](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/update-a-catalog-order-minimum.md): Restates one currency's threshold. - [Set catalog quantity rules](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/set-catalog-quantity-rules.md): Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term… - [Activate a catalog](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/activate-a-catalog.md): Puts the agreement into effect: its audience starts seeing its assortment and paying its prices. Refused for a catalog nobody is assigned to, since activating it would reach no buyer — a channel's default catalog is reached through the channel instead, so it needs no assignment. - [Deactivate a catalog](https://spreecommerce.org/docs/api-reference/admin-api/catalogs/deactivate-a-catalog.md): Takes the agreement out of effect. Everything it holds — assignments, commercial terms, its price list — survives, so activating again resumes exactly what was there. ### Collections - [List collections](https://spreecommerce.org/docs/api-reference/admin-api/collections/list-collections.md): Returns a paginated list of the store's collections. - [Create a collection](https://spreecommerce.org/docs/api-reference/admin-api/collections/create-a-collection.md): Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`. - [Get a collection](https://spreecommerce.org/docs/api-reference/admin-api/collections/get-a-collection.md): Returns a single collection by ID, including its rules. - [Delete a collection](https://spreecommerce.org/docs/api-reference/admin-api/collections/delete-a-collection.md): Deletes a collection. - [Update a collection](https://spreecommerce.org/docs/api-reference/admin-api/collections/update-a-collection.md): Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules. - [List collection products](https://spreecommerce.org/docs/api-reference/admin-api/collections/list-collection-products.md): Products curated in the collection, ordered by their membership position. - [Add products to a collection](https://spreecommerce.org/docs/api-reference/admin-api/collections/add-products-to-a-collection.md): Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added. - [Remove products from a collection](https://spreecommerce.org/docs/api-reference/admin-api/collections/remove-products-from-a-collection.md): Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed. - [Reposition a collection product](https://spreecommerce.org/docs/api-reference/admin-api/collections/reposition-a-collection-product.md): Moves a product to a new index among the collection's products. - [List available collection rule types](https://spreecommerce.org/docs/api-reference/admin-api/collections/list-available-collection-rule-types.md): Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when wri… - [List collection custom fields](https://spreecommerce.org/docs/api-reference/admin-api/collections/list-collection-custom-fields.md): Returns the collection's custom field values. ### Commission Lines - [List commission lines](https://spreecommerce.org/docs/api-reference/admin-api/commission-lines/list-commission-lines.md): What each sale actually earned the marketplace, frozen when the order was placed. A later change to a commission rate never reaches these. - [Get a commission line](https://spreecommerce.org/docs/api-reference/admin-api/commission-lines/get-a-commission-line.md): **Required scope:** `read_commissions` (for API-key authentication). ### Commission Rates - [List commission rates](https://spreecommerce.org/docs/api-reference/admin-api/commission-rates/list-commission-rates.md): What the marketplace charges its sellers. - [Create a commission rate](https://spreecommerce.org/docs/api-reference/admin-api/commission-rates/create-a-commission-rate.md): Sets what the marketplace charges, and which sales it applies to. - [List the commission rule kinds](https://spreecommerce.org/docs/api-reference/admin-api/commission-rates/list-the-commission-rule-kinds.md): Every rule kind a rate can be narrowed by, with the schema describing the configuration it takes — so a client builds its editor from what this marketplace has rather than a list hardcoded to match core's. - [Get a commission rate](https://spreecommerce.org/docs/api-reference/admin-api/commission-rates/get-a-commission-rate.md): **Required scope:** `read_commissions` (for API-key authentication). - [Delete a commission rate](https://spreecommerce.org/docs/api-reference/admin-api/commission-rates/delete-a-commission-rate.md): **Required scope:** `write_commissions` (for API-key authentication). - [Update a commission rate](https://spreecommerce.org/docs/api-reference/admin-api/commission-rates/update-a-commission-rate.md): Editing a rate changes what the next sale is charged, never what a past one was: commission lines keep their own snapshot of the rate that applied. ### Companies - [List company addresses](https://spreecommerce.org/docs/api-reference/admin-api/companies/list-company-addresses.md): Returns the business's addresses: its sites, billing address and delivery points. - [Create a company address](https://spreecommerce.org/docs/api-reference/admin-api/companies/create-a-company-address.md): Adds an address to the business. Pass `default_billing: true` or `default_shipping: true` to make it the default of that kind. - [Update a company address](https://spreecommerce.org/docs/api-reference/admin-api/companies/update-a-company-address.md): Changes an address of the business. Pass `default_billing` or `default_shipping` to move that default to it, or `false` to give it up. - [List company invitations](https://spreecommerce.org/docs/api-reference/admin-api/companies/list-company-invitations.md): Returns the invitations into this business that are still waiting to be accepted. - [List company members](https://spreecommerce.org/docs/api-reference/admin-api/companies/list-company-members.md): Returns the people with standing over this node. Standing covers the node and everything below it in the tree. - [Add a member by email](https://spreecommerce.org/docs/api-reference/admin-api/companies/add-a-member-by-email.md): Adds a person to the node by email. An email matching an existing customer becomes a membership immediately (a `cmem_…` id); an unknown email becomes an invitation (a `cinv_…` id) and the invite email goes out. - [List tax exemption certificates](https://spreecommerce.org/docs/api-reference/admin-api/companies/list-tax-exemption-certificates.md): Returns a business's exemption evidence. `active` is the field that decides whether a certificate exempts a sale: a verified certificate stops counting once its expiry date passes, so the status alone does not answer it. - [Create a tax exemption certificate](https://spreecommerce.org/docs/api-reference/admin-api/companies/create-a-tax-exemption-certificate.md): Records exemption evidence against a business. Certificates start `pending` and exempt nothing until verified. - [Update a tax exemption certificate](https://spreecommerce.org/docs/api-reference/admin-api/companies/update-a-tax-exemption-certificate.md): Corrects the details recorded for a certificate, such as its issuing authority or expiry date. - [Verify a tax exemption certificate](https://spreecommerce.org/docs/api-reference/admin-api/companies/verify-a-tax-exemption-certificate.md): Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending certificate can be accepted — re-accepting a revoked one would restore evidence that was deliberately withdrawn. An installation that checks numbers against a registry, or requires a second approval, can refuse… - [Revoke a tax exemption certificate](https://spreecommerce.org/docs/api-reference/admin-api/companies/revoke-a-tax-exemption-certificate.md): Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out. - [Download a certificate document](https://spreecommerce.org/docs/api-reference/admin-api/companies/download-a-certificate-document.md): Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so the same credentials apply to every read of a confidential document. Requires only read access. - [List company tax registrations](https://spreecommerce.org/docs/api-reference/admin-api/companies/list-company-tax-registrations.md): Returns the business's tax registrations, one per kind. A business registration takes precedence over the buyer's own when a sale is for that business, because the invoice is addressed to the entity rather than the person who placed the order. - [Create a company tax registration](https://spreecommerce.org/docs/api-reference/admin-api/companies/create-a-company-tax-registration.md): Registers a tax number against the business. Verification against the relevant registry runs in the background where a validator is installed for the kind; a stock installation registers none, leaving the status unattempted. - [Re-check a company tax registration](https://spreecommerce.org/docs/api-reference/admin-api/companies/re-check-a-company-tax-registration.md): Asks the registry again. Manual because a registry answers only "valid now" — a number verified last year may have been deregistered since — and because a check that came back unavailable cannot otherwise be retried without editing the number. - [List companies](https://spreecommerce.org/docs/api-reference/admin-api/companies/list-companies.md): Returns the business customers of the current store. - [Create a company](https://spreecommerce.org/docs/api-reference/admin-api/companies/create-a-company.md): Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes. - [Update a company](https://spreecommerce.org/docs/api-reference/admin-api/companies/update-a-company.md): Updates a company node. Only the attributes sent change. ### Custom Field Definitions - [List what custom fields can be attached to](https://spreecommerce.org/docs/api-reference/admin-api/custom-field-definitions/list-what-custom-fields-can-be-attached-to.md): The resources a definition can describe, from the server's own registry (`Spree.custom_fields.enabled_resources`). ### Delivery - [List delivery profiles](https://spreecommerce.org/docs/api-reference/admin-api/delivery/list-delivery-profiles.md): Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile. - [Create a delivery profile](https://spreecommerce.org/docs/api-reference/admin-api/delivery/create-a-delivery-profile.md): Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location. - [List origin groups](https://spreecommerce.org/docs/api-reference/admin-api/delivery/list-origin-groups.md): Returns the profile's origin groups: the sets of warehouses that each quote their own delivery rates. - [Create an origin group](https://spreecommerce.org/docs/api-reference/admin-api/delivery/create-an-origin-group.md): Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location. - [Delete a delivery profile](https://spreecommerce.org/docs/api-reference/admin-api/delivery/delete-a-delivery-profile.md): The default profile and profiles still referenced by products cannot be deleted. - [Update a delivery profile](https://spreecommerce.org/docs/api-reference/admin-api/delivery/update-a-delivery-profile.md): **Required scope:** `write_settings` (for API-key authentication). - [List delivery methods](https://spreecommerce.org/docs/api-reference/admin-api/delivery/list-delivery-methods.md): Returns all delivery methods with calculator and zone configuration. - [Create delivery method](https://spreecommerce.org/docs/api-reference/admin-api/delivery/create-delivery-method.md): Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider. - [Update delivery method](https://spreecommerce.org/docs/api-reference/admin-api/delivery/update-delivery-method.md): Updates a delivery method. Only the attributes sent change. - [List delivery calculators](https://spreecommerce.org/docs/api-reference/admin-api/delivery/list-delivery-calculators.md): Registered delivery calculator classes with preference schemas for building configuration forms. - [List delivery zones](https://spreecommerce.org/docs/api-reference/admin-api/delivery/list-delivery-zones.md): Returns the areas delivery methods ship to, each made of countries, states or postal code ranges. - [Create delivery zone](https://spreecommerce.org/docs/api-reference/admin-api/delivery/create-delivery-zone.md): Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range). - [Update delivery zone](https://spreecommerce.org/docs/api-reference/admin-api/delivery/update-delivery-zone.md): Updates a delivery zone. Sending `members` replaces the whole member list; leaving it out keeps the current members. - [List delivery method rules](https://spreecommerce.org/docs/api-reference/admin-api/delivery/list-delivery-method-rules.md): Returns the conditions a delivery method must meet to be offered at checkout, such as an order total or weight range. - [Create a delivery method rule](https://spreecommerce.org/docs/api-reference/admin-api/delivery/create-a-delivery-method-rule.md): Adds a condition to a delivery method. `type` is a rule kind from the delivery method rule types endpoint, and `preferences` takes the values its schema declares. - [Update a delivery method rule](https://spreecommerce.org/docs/api-reference/admin-api/delivery/update-a-delivery-method-rule.md): Changes a rule's settings or turns it off. Its `type` is fixed once created. ### Integrations - [List integrations](https://spreecommerce.org/docs/api-reference/admin-api/integrations/list-integrations.md): Returns the integrations connected to the current store. Secret preference values are masked. - [Connect integration](https://spreecommerce.org/docs/api-reference/admin-api/integrations/connect-integration.md): Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret. - [List integration types](https://spreecommerce.org/docs/api-reference/admin-api/integrations/list-integration-types.md): Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations. - [Update integration](https://spreecommerce.org/docs/api-reference/admin-api/integrations/update-integration.md): Changes an integration's credentials or turns it on or off. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret. - [Test integration connection](https://spreecommerce.org/docs/api-reference/admin-api/integrations/test-integration-connection.md): Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message. ### Media - [List media](https://spreecommerce.org/docs/api-reference/admin-api/media/list-media.md): Returns every file in the store's media library, whether or not it has been placed on a product. Filter with `q[unattached]=true` for files not yet in use, `q[media_type_eq]` for images or video, and `q[filename_cont]` to search by file name. - [Upload a file to the library](https://spreecommerce.org/docs/api-reference/admin-api/media/upload-a-file-to-the-library.md): Adds a file to the library without placing it on anything. Upload the file first through `POST /api/v3/admin/files`, then send the signed id here. Put the file on a product by posting to that product's media with this record's id as `source_media_id`. - [Update a library file](https://spreecommerce.org/docs/api-reference/admin-api/media/update-a-library-file.md): Edits a file in the library, such as its alt text. - [Where a file is used](https://spreecommerce.org/docs/api-reference/admin-api/media/where-a-file-is-used.md): Lists everywhere this file appears: products it is placed on, image fields that picked it, and descriptions embedding it. Reusing a file shares it rather than copying it, so deleting one placement can leave others pointing at the same file — check this first. - [List product media](https://spreecommerce.org/docs/api-reference/admin-api/media/list-product-media.md): Returns the files placed on a product, in their display order. - [Place a library file on a product](https://spreecommerce.org/docs/api-reference/admin-api/media/place-a-library-file-on-a-product.md): Puts a file that is already in the library onto this product. The new record shares the source's file rather than copying it, so nothing is uploaded and no image is reprocessed; it carries its own alt text, position and variant links from here on. - [Update product media](https://spreecommerce.org/docs/api-reference/admin-api/media/update-product-media.md): Edits a file placed on a product: its alt text, position and focal point, and which of the product's variants it shows for (`variant_ids`). - [List variant media](https://spreecommerce.org/docs/api-reference/admin-api/media/list-variant-media.md): Returns the files placed on one of a product's variants, in their display order. ### Deliveries - [List deliveries](https://spreecommerce.org/docs/api-reference/admin-api/deliveries/list-deliveries.md): The consignments of a parcel — one per tracking number, each with the carrier status last reported. - [Record a delivery](https://spreecommerce.org/docs/api-reference/admin-api/deliveries/record-a-delivery.md): Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text. - [Delete a delivery](https://spreecommerce.org/docs/api-reference/admin-api/deliveries/delete-a-delivery.md): Removes a hand-entered consignment. One a label minted is refused — refund the label instead. - [Correct a delivery](https://spreecommerce.org/docs/api-reference/admin-api/deliveries/correct-a-delivery.md): Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over. - [Mark a delivery delivered](https://spreecommerce.org/docs/api-reference/admin-api/deliveries/mark-a-delivery-delivered.md): Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has. ### Shipping Labels - [List shipping labels](https://spreecommerce.org/docs/api-reference/admin-api/shipping-labels/list-shipping-labels.md): Every label bought or uploaded for a parcel, refunded ones included. - [Buy or record a shipping label](https://spreecommerce.org/docs/api-reference/admin-api/shipping-labels/buy-or-record-a-shipping-label.md): With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel. - [Get a shipping label](https://spreecommerce.org/docs/api-reference/admin-api/shipping-labels/get-a-shipping-label.md): One label, with what it cost and where to print it from. - [Delete an uploaded label](https://spreecommerce.org/docs/api-reference/admin-api/shipping-labels/delete-an-uploaded-label.md): Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest. - [Refund a shipping label](https://spreecommerce.org/docs/api-reference/admin-api/shipping-labels/refund-a-shipping-label.md): Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped. ### Package Types - [List package types](https://spreecommerce.org/docs/api-reference/admin-api/package-types/list-package-types.md): Returns the store's packaging vocabulary: the box it ships parcels in and the cartons, pallets and containers a wholesale order leaves on. - [Create a package type](https://spreecommerce.org/docs/api-reference/admin-api/package-types/create-a-package-type.md): Adds a kind of packaging to the store. - [Get a package type](https://spreecommerce.org/docs/api-reference/admin-api/package-types/get-a-package-type.md): Returns a single package type by prefixed ID. - [Delete a package type](https://spreecommerce.org/docs/api-reference/admin-api/package-types/delete-a-package-type.md): Removes a kind of packaging. Refused while any variant is packed into it — repack those products first. - [Update a package type](https://spreecommerce.org/docs/api-reference/admin-api/package-types/update-a-package-type.md): Updates a package type. Every product packed in it follows the new geometry. ### Price Lists - [List price list products](https://spreecommerce.org/docs/api-reference/admin-api/price-lists/list-price-list-products.md): The products the list prices, listed by name — membership is derived from the price rows. `expand=price_list_price` adds what the list charges for each variant, with its quantity breaks as tiers, the same reading a catalog's products carry. - [Add products to a price list](https://spreecommerce.org/docs/api-reference/admin-api/price-lists/add-products-to-a-price-list.md): Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped. - [Remove products from a price list](https://spreecommerce.org/docs/api-reference/admin-api/price-lists/remove-products-from-a-price-list.md): Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored. ### Product Types - [List product types](https://spreecommerce.org/docs/api-reference/admin-api/product-types/list-product-types.md): Returns a paginated list of product types. - [Create a product type](https://spreecommerce.org/docs/api-reference/admin-api/product-types/create-a-product-type.md): Creates a product type. - [Retrieve a product type](https://spreecommerce.org/docs/api-reference/admin-api/product-types/retrieve-a-product-type.md): Returns a single product type with its option types, categories and custom fields. - [Delete a product type](https://spreecommerce.org/docs/api-reference/admin-api/product-types/delete-a-product-type.md): Deletes a product type. Types still used by products cannot be deleted. - [Update a product type](https://spreecommerce.org/docs/api-reference/admin-api/product-types/update-a-product-type.md): Updates a product type. - [Apply a product type to its existing products](https://spreecommerce.org/docs/api-reference/admin-api/product-types/apply-a-product-type-to-its-existing-products.md): Backfills the type's option types and categories onto the products that already carry it. Additive and idempotent — nothing is removed, and re-running is safe. ### Purchase Orders - [List purchase orders](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/list-purchase-orders.md): Stock bought from suppliers. A purchase order carries what a purchase has and a stock transfer does not: a supplier, a unit cost per line and an expected arrival date. - [Create a purchase order](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/create-a-purchase-order.md): Drafts an order. Nothing is on order and nothing touches availability until the order is marked as ordered and then received. - [Get a purchase order](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/get-a-purchase-order.md): **Required scope:** `read_purchasing` (for API-key authentication). - [Update a purchase order](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/update-a-purchase-order.md): Edits a draft: its supplier, destination, dates, reference, notes and lines. Sending `items` replaces every line the order holds. Status moves through the order's own actions, never through this endpoint. - [Place the order with the supplier](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/place-the-order-with-the-supplier.md): Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is stamped. Availability is still untouched — ordered stock is not stock the merchant has. - [List the deliveries booked against an order](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/list-the-deliveries-booked-against-an-order.md): Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused. - [Book in a delivery](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/book-in-a-delivery.md): The moment purchased goods first count toward availability. Records one delivery as a stock receipt: what this delivery brought, per line, not a running total — a second delivery adds to the first. - [Take an order back to draft](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/take-an-order-back-to-draft.md): Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared. - [Close an order short](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/close-an-order-short.md): Ends a partially received order whose balance the supplier will not deliver. Nothing moves: what arrived stays on the shelf, the outstanding count stays on each line, and the order settles in `received` with `closed_short_at` and the `reason` recorded. - [Cancel a purchase order](https://spreecommerce.org/docs/api-reference/admin-api/purchase-orders/cancel-a-purchase-order.md): Closes what is still outstanding. Nothing is unwound: a purchase order never moved stock until units were received, and units already received stay on the shelf because the merchant has them. ### Reports - [List saved reports](https://spreecommerce.org/docs/api-reference/admin-api/reports/list-saved-reports.md): Returns the store's saved reports, each a named query staff can run again. - [Create a saved report](https://spreecommerce.org/docs/api-reference/admin-api/reports/create-a-saved-report.md): Saves a reporting query under a name so staff can run it again. The query is validated against the reporting registry. - [Update a saved report](https://spreecommerce.org/docs/api-reference/admin-api/reports/update-a-saved-report.md): **Required scope:** `write_reports` (for API-key authentication). - [Run a reporting query](https://spreecommerce.org/docs/api-reference/admin-api/reports/run-a-reporting-query.md): Runs a query against the store's registered metrics and dimensions, in the store's time zone. A metric or dimension the registry does not know is refused with the names that are valid, and an API key needs the read scope of every resource the query touches. ### Seller Requirements - [List seller requirements](https://spreecommerce.org/docs/api-reference/admin-api/seller-requirements/list-seller-requirements.md): What this marketplace asks of a seller before it will let them trade, in the order sellers work through it. - [Add a seller requirement](https://spreecommerce.org/docs/api-reference/admin-api/seller-requirements/add-a-seller-requirement.md): Adds something the marketplace asks of its sellers. - [List seller requirement kinds](https://spreecommerce.org/docs/api-reference/admin-api/seller-requirements/list-seller-requirement-kinds.md): The kinds you can add, and the shape of each one's configuration form. - [Delete a seller requirement](https://spreecommerce.org/docs/api-reference/admin-api/seller-requirements/delete-a-seller-requirement.md): Stops asking for this. Anything sellers already submitted against it goes too — to keep the record while pausing the ask, set `active` to false instead. - [Update a seller requirement](https://spreecommerce.org/docs/api-reference/admin-api/seller-requirements/update-a-seller-requirement.md): Changes how a requirement is worded, what it asks for, where it sits in the checklist, and whether it blocks approval. ### Stock - [List stock levels](https://spreecommerce.org/docs/api-reference/admin-api/stock/list-stock-levels.md): One row per variant per stock location, carrying every figure the Inventory page shows: `count_on_hand` (on hand), `allocated_count` (committed to placed orders), `reserved_count` (held by checkouts in progress), `available_count` (on hand minus committed) and `incoming_count` (on its way on an open… - [Bulk-upsert stock levels](https://spreecommerce.org/docs/api-reference/admin-api/stock/bulk-upsert-stock-levels.md): Sets stock levels for many (variant, location) pairs at once — what a warehouse or ERP feed posts on a schedule. - [Update a stock level](https://spreecommerce.org/docs/api-reference/admin-api/stock/update-a-stock-level.md): Corrects one shelf. Send `count_on_hand` for the count the shelf should end at, or `adjustment` for a signed change; either is recorded as a stock movement labelled with `reason`. - [List stock reservations](https://spreecommerce.org/docs/api-reference/admin-api/stock/list-stock-reservations.md): Returns the stock held for orders that are being checked out, so it cannot be sold twice before they complete or the hold expires. ### Stock Movements - [List stock movements](https://spreecommerce.org/docs/api-reference/admin-api/stock-movements/list-stock-movements.md): Returns the stock ledger, newest first. Every row says what happened to stock (`kind`) and carries a direct reference to what caused it, so a merchant can answer "why is this number what it is?" from the data. - [Get a stock movement](https://spreecommerce.org/docs/api-reference/admin-api/stock-movements/get-a-stock-movement.md): Returns a single stock movement by prefixed ID. ### Stock Transfers - [List stock transfers](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/list-stock-transfers.md): Stock moving between two of the merchant's own warehouses. - [Create a stock transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/create-a-stock-transfer.md): Persists a draft — a packing list the merchant can still edit. Nothing moves until the transfer is marked in transit. - [Get a stock transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/get-a-stock-transfer.md): **Required scope:** `read_stock` (for API-key authentication). - [Delete a stock transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/delete-a-stock-transfer.md): Drafts only. Past `draft` the transfer describes a box that physically exists, so it is cancelled rather than deleted — a 422 says so. - [Update a stock transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/update-a-stock-transfer.md): Edits a draft: its reference, notes, either end, and its lines. Sending `items` replaces every line the draft holds. Status moves through the transfer's own actions, never through this endpoint. - [Mark a transfer ready to ship](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/mark-a-transfer-ready-to-ship.md): Freezes the lines so the warehouse and the merchant are looking at the same list. Nothing leaves the shelf yet. - [Send a transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/send-a-transfer.md): The moment stock leaves the source warehouse: `shipped` movements are written against the source's levels and `shipped_at` is stamped. The destination is deliberately untouched — the units are in flight. - [List the deliveries counted in against a transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/list-the-deliveries-counted-in-against-a-transfer.md): Each delivery the destination counted in, with what it accepted and refused. - [Count a delivery in](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/count-a-delivery-in.md): Records one delivery the destination warehouse counted in, as a stock receipt. Partial receipt is the normal case: ten left, eight arrived, two were crushed in transit. Quantities are this delivery's counts — a second box adds to the first rather than restating it. - [Take a transfer back to draft](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/take-a-transfer-back-to-draft.md): Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone. - [Close a transfer short](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/close-a-transfer-short.md): Ends a partially received transfer whose missing units are not going to turn up. Nothing moves — they already left the source — and the transfer settles in `received` with `closed_short_at` and the `reason` recorded, the outstanding count left on each line. - [Cancel a stock transfer](https://spreecommerce.org/docs/api-reference/admin-api/stock-transfers/cancel-a-stock-transfer.md): Calls the trip off. ### Suppliers - [List suppliers](https://spreecommerce.org/docs/api-reference/admin-api/suppliers/list-suppliers.md): Who the merchant buys stock from. A supplier is an address-book entry with a purchasing history — not a party that sells on the store, which is a seller. - [Create a supplier](https://spreecommerce.org/docs/api-reference/admin-api/suppliers/create-a-supplier.md): Adds a supplier to this store's address book. The address is inline — street, city, state and country live on the supplier itself, the same shape a stock location uses. - [Get a supplier](https://spreecommerce.org/docs/api-reference/admin-api/suppliers/get-a-supplier.md): **Required scope:** `read_purchasing` (for API-key authentication). - [Delete a supplier](https://spreecommerce.org/docs/api-reference/admin-api/suppliers/delete-a-supplier.md): Soft-deletes the supplier, so the purchase orders naming it stay readable. Refused with a 422 while a purchase order still points at it. - [Update a supplier](https://spreecommerce.org/docs/api-reference/admin-api/suppliers/update-a-supplier.md): **Required scope:** `write_purchasing` (for API-key authentication). ## OpenAPI Specs - [admin](/docs/api-reference/admin.yaml)