{ "opencollection": "1.0.0", "info": { "name": "Admin API", "version": "v3" }, "items": [ { "info": { "name": "Configuration", "type": "folder" }, "items": [ { "info": { "name": "List staff", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/admin_users", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Show a staff member", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/admin_users/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Update a staff member", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/admin_users/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Remove a staff member from this store", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/admin_users/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "List API keys", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/api_keys", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Create an API key", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/api_keys", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Show an API key", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/api_keys/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Delete an API key", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/api_keys/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Revoke an API key", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/api_keys/:id/revoke", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "List invitations", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/invitations", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Create an invitation", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/invitations", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Revoke an invitation", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/invitations/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Resend an invitation", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/invitations/:id/resend", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "List payment methods", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/payment_methods", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., name,type,active). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "List available payment provider types", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/payment_methods/types", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Show a payment method", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/payment_methods/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., name,type,active). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "List roles", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/roles", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the roles available for staff role pickers. Roles are global, not per-store.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "List stock locations", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/stock_locations", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "q[name_cont]", "value": "", "type": "query", "description": "Filter by name (contains)" }, { "name": "q[active_eq]", "value": "", "type": "query", "description": "Filter by active status" }, { "name": "q[kind_eq]", "value": "", "type": "query", "description": "Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')" }, { "name": "q[pickup_enabled_eq]", "value": "", "type": "query", "description": "Filter by pickup-enabled flag" }, { "name": "sort", "value": "", "type": "query", "description": "Sort by field. Prefix with `-` for descending (e.g., `-created_at`)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_settings` (for " }, { "info": { "name": "Create a stock location", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/stock_locations", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Get a stock location", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/stock_locations/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Stock location ID" }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Update a stock location", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/stock_locations/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Stock location ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "Delete a stock location", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/stock_locations/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Stock location ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "List store credit categories", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/store_credit_categories", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "q[name_cont]", "value": "", "type": "query", "description": "Filter by name (contains)" }, { "name": "sort", "value": "", "type": "query", "description": "Sort by field. Prefix with `-` for descending (e.g., `-created_at`)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the configured store credit categories. Categories classify\nstore credits (e.g., \"Goodwill\", \"Gift Card\", \"Refund\") and surface\nin the admin UI as a dropdown when issuing or editing a store\ncredit. Category names matching `Spree::Config[:non_expiring_credit_types]`\nare flagged via `non_expiring: true`.\n\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Get a store credit category", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/store_credit_categories/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Store credit category ID" }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single store credit category by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Get the current store", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/store", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication)." }, { "info": { "name": "Update the current store", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/store", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication)." }, { "info": { "name": "List tags", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/tags", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "taggable_type", "value": "", "type": "query", "description": "Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)" }, { "name": "q", "value": "", "type": "query", "description": "Optional case-insensitive substring filter" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers." } ] }, { "info": { "name": "Promotions", "type": "folder" }, "items": [ { "info": { "name": "List coupon codes for a promotion", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/coupon_codes", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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.\n\n**Required scope:** `read_promotions` (for API-key authentication)." }, { "info": { "name": "List actions for a promotion", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_actions", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_promotions` (for API-key authentication)." }, { "info": { "name": "Create an action on a promotion", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_actions", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "Delete an action from a promotion", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_actions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "List rules for a promotion", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_rules", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_promotions` (for API-key authentication)." }, { "info": { "name": "Create a rule on a promotion", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_rules", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "Update a rule's preferences", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_rules/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "Delete a rule from a promotion", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/promotions/:promotion_id/promotion_rules/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "promotion_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "List promotions", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotions", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication)." }, { "info": { "name": "Create a promotion", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/promotions", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "Show a promotion", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_promotions` (for API-key authentication)." }, { "info": { "name": "Update a promotion", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/promotions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "Delete a promotion", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/promotions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_promotions` (for API-key authentication)." }, { "info": { "name": "List available promotion action types", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotion_actions/types", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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.\n\n**Required scope:** `read_promotions` (for API-key authentication)." }, { "info": { "name": "List available promotion rule types", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/promotion_rules/types", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication)." } ] }, { "info": { "name": "Custom Fields", "type": "folder" }, "items": [ { "info": { "name": "List custom field definitions", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/custom_field_definitions", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., key,label,field_type). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_custom_field_definitions` (for API-key authentication)." }, { "info": { "name": "Create a custom field definition", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/custom_field_definitions", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_custom_field_definitions` (for API-key authentication)." }, { "info": { "name": "Show a custom field definition", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/custom_field_definitions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., key,label,field_type). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_custom_field_definitions` (for API-key authentication)." }, { "info": { "name": "Update a custom field definition", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/custom_field_definitions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_custom_field_definitions` (for API-key authentication)." }, { "info": { "name": "Delete a custom field definition", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/custom_field_definitions/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_custom_field_definitions` (for API-key authentication)." } ] }, { "info": { "name": "Customers", "type": "folder" }, "items": [ { "info": { "name": "List customer groups", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customer_groups", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "q[name_cont]", "value": "", "type": "query", "description": "Filter by name (contains)" }, { "name": "sort", "value": "", "type": "query", "description": "Sort by field. Prefix with `-` for descending (e.g., `-created_at`)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Create a customer group", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customer_groups", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Get a customer group", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customer_groups/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Customer group prefixed ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to embed. Supported: `customers`." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Update a customer group", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/customer_groups/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Customer group prefixed ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Delete a customer group", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/customer_groups/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Customer group prefixed ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "List customer addresses", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/addresses", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Create a customer address", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/addresses", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Update a customer address", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/addresses/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Delete a customer address", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/addresses/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "List customer credit cards", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/credit_cards", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Show a customer credit card", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/credit_cards/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Delete a customer credit card", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/credit_cards/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "List customer store credits", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/store_credits", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication)." }, { "info": { "name": "Issue a store credit to a customer", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/store_credits", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication)." }, { "info": { "name": "Update a store credit", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/store_credits/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication)." }, { "info": { "name": "Delete a store credit", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/customers/:customer_id/store_credits/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "customer_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication)." }, { "info": { "name": "List customers", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customers", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query" }, { "name": "limit", "value": "", "type": "query" }, { "name": "q[search]", "value": "", "type": "query", "description": "Email + name full-text-ish search" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Create a customer", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Show a customer", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/customers/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Customer ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address" }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication)." }, { "info": { "name": "Update a customer", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/customers/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Delete a customer", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/customers/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Bulk-add customers to groups", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers/bulk_add_to_groups", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Bulk-remove customers from groups", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers/bulk_remove_from_groups", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Bulk-add tags to customers", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers/bulk_add_tags", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication)." }, { "info": { "name": "Bulk-remove tags from customers", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/customers/bulk_remove_tags", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication)." } ] }, { "info": { "name": "Exports", "type": "folder" }, "items": [ { "info": { "name": "List exports", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/exports", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** `read_exports` (for API-key authentication)." }, { "info": { "name": "Create an export", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/exports", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** `write_exports` (for API-key authentic" }, { "info": { "name": "Show an export", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/exports/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** `read_exports` (for API-key authentication)." }, { "info": { "name": "Delete an export", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/exports/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes the export and purges its attachment.\n\n**Required scope:** `write_exports` (for API-key authentication)." }, { "info": { "name": "Download an export", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/exports/:id/download", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "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 navigation cannot carry the JWT.\n\n**Required scope:** `read_exports` (for API-key authentication)." } ] }, { "info": { "name": "Gift Cards", "type": "folder" }, "items": [ { "info": { "name": "List gift card batches", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/gift_card_batches", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Records per page" }, { "name": "q[prefix_cont]", "value": "", "type": "query", "description": "Filter by prefix (contains)" }, { "name": "sort", "value": "", "type": "query", "description": "Sort by field. Prefix with `-` for descending." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication)." }, { "info": { "name": "Create a gift card batch", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/gift_card_batches", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication)." }, { "info": { "name": "Get a gift card batch", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/gift_card_batches/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Gift card batch prefixed ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication)." }, { "info": { "name": "List gift cards", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/gift_cards", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "q[code_cont]", "value": "", "type": "query", "description": "Filter by gift card code (contains)" }, { "name": "q[state_eq]", "value": "", "type": "query", "description": "Filter by status (active, redeemed, partially_redeemed, canceled)" }, { "name": "sort", "value": "", "type": "query", "description": "Sort by field. Prefix with `-` for descending (e.g., `-created_at`)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication)." }, { "info": { "name": "Create a gift card", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/gift_cards", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication)." }, { "info": { "name": "Get a gift card", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/gift_cards/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Gift card prefixed ID" }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include. id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication)." }, { "info": { "name": "Update a gift card", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/gift_cards/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Gift card prefixed ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication)." }, { "info": { "name": "Delete a gift card", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/gift_cards/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Gift card prefixed ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication)." } ] }, { "info": { "name": "Authentication", "type": "folder" }, "items": [ { "info": { "name": "Get current admin user and permissions", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/me", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks." } ] }, { "info": { "name": "Product Catalog", "type": "folder" }, "items": [ { "info": { "name": "List option types", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/option_types", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "q[name_cont]", "value": "", "type": "query", "description": "Filter by name (contains)" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., name,label,position). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Create an option type", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/option_types", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Get an option type", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/option_types/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Option type ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., name,label,position). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Update an option type", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/option_types/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Option type ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Delete an option type", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/option_types/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Option type ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "List products", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/products", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "sort", "value": "", "type": "query", "description": "Sort field (e.g., name, -name, price, -price, best_selling)" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included." }, { "name": "q[name_cont]", "value": "", "type": "query", "description": "Filter by name (contains)" }, { "name": "q[status_eq]", "value": "", "type": "query", "description": "Filter by status" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Create a product", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Get a product", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/products/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Product ID (e.g., prod_xxx)" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Update a product", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/products/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Product ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Delete a product", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/products/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Product ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Bulk-update product status", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/bulk_status_update", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Bulk-add products to categories", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/bulk_add_to_categories", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Attaches each product in `ids` to every category (taxon) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Bulk-remove products from categories", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/bulk_remove_from_categories", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Bulk-add tags to products", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/bulk_add_tags", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Bulk-remove tags from products", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/bulk_remove_tags", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Bulk-delete products", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/products/bulk_destroy", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "List product variants", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/variants", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path", "description": "Product ID" }, { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., sku,price,stock). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a paginated list of variants for a product, including the master variant.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Create a variant", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/variants", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path", "description": "Product ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Get a variant", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/variants/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path", "description": "Product ID" }, { "name": "id", "value": "", "type": "path", "description": "Variant ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., sku,price,stock). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Update a variant", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/variants/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path", "description": "Product ID" }, { "name": "id", "value": "", "type": "path", "description": "Variant ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Delete a variant", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/variants/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path", "description": "Product ID" }, { "name": "id", "value": "", "type": "path", "description": "Variant ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication)." } ] }, { "info": { "name": "Orders", "type": "folder" }, "items": [ { "info": { "name": "List fulfillments", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication)." }, { "info": { "name": "Show a shipment", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Fulfillment ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication)." }, { "info": { "name": "Update a shipment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Fulfillment ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates a shipment (tracking, shipping rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication)." }, { "info": { "name": "Fulfill a fulfillment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments/:id/fulfill", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Fulfillment ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication)." }, { "info": { "name": "Cancel a fulfillment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments/:id/cancel", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Fulfillment ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication)." }, { "info": { "name": "Resume a fulfillment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments/:id/resume", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Fulfillment ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication)." }, { "info": { "name": "Split a fulfillment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/fulfillments/:id/split", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Fulfillment ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication)." }, { "info": { "name": "Apply a gift card to an order", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/gift_cards", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication)." }, { "info": { "name": "Remove a gift card from an order", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/gift_cards/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Gift card ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication)." }, { "info": { "name": "List order items", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/items", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., quantity,price,total). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication)." }, { "info": { "name": "Add an item", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/items", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Show an item", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/items/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Item ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., quantity,price,total). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication)." }, { "info": { "name": "Update an item", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/items/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Item ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Remove an item", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/items/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Item ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "List payments", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/payments", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication)." }, { "info": { "name": "Create a payment", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/payments", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication)." }, { "info": { "name": "Show a payment", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/payments/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Payment ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication)." }, { "info": { "name": "Capture a payment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/payments/:id/capture", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Payment ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication)." }, { "info": { "name": "Void a payment", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/payments/:id/void", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "id", "value": "", "type": "path", "description": "Payment ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication)." }, { "info": { "name": "List refunds", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/refunds", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication)." }, { "info": { "name": "Create a refund", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/refunds", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication)." }, { "info": { "name": "Apply customer's store credit to an order", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/store_credits", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication)." }, { "info": { "name": "Remove store credit from an order", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/orders/:order_id/store_credits", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "order_id", "value": "", "type": "path", "description": "Order ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication)." }, { "info": { "name": "List orders", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number" }, { "name": "limit", "value": "", "type": "query", "description": "Number of records per page" }, { "name": "sort", "value": "", "type": "query", "description": "Sort field (e.g., created_at, -created_at, completed_at)" }, { "name": "q[state_eq]", "value": "", "type": "query", "description": "Filter by state (cart, address, delivery, payment, confirm, complete, canceled)" }, { "name": "q[email_cont]", "value": "", "type": "query", "description": "Filter by email (contains)" }, { "name": "q[number_eq]", "value": "", "type": "query", "description": "Filter by order number" }, { "name": "q[completed_at_gt]", "value": "", "type": "query", "description": "Filter by completed after date" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication)." }, { "info": { "name": "Create a draft order", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API resp" }, { "info": { "name": "Show an order", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/orders/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID (e.g., or_xxx)" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication)." }, { "info": { "name": "Update an order", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Delete a draft order", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/orders/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Complete an order", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:id/complete", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Cancel an order", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:id/cancel", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Cancels a completed order.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Approve an order", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:id/approve", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Resume a canceled order", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/orders/:id/resume", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Resumes a previously canceled order.\n\n**Required scope:** `write_orders` (for API-key authentication)." }, { "info": { "name": "Resend confirmation email", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/orders/:id/resend_confirmation", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "id", "value": "", "type": "path", "description": "Order ID" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication)." } ] }, { "info": { "name": "Products", "type": "folder" }, "items": [ { "info": { "name": "List product custom fields", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/custom_fields", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., key,value,namespace). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Create a product custom field", "type": "http" }, "http": { "method": "POST", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/custom_fields", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Show a product custom field", "type": "http" }, "http": { "method": "GET", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/custom_fields/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" }, { "name": "expand", "value": "", "type": "query", "description": "Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels)." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include (e.g., key,value,namespace). id is always included." } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `read_products` (for API-key authentication)." }, { "info": { "name": "Update a product custom field", "type": "http" }, "http": { "method": "PATCH", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/custom_fields/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" }, "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication)." }, { "info": { "name": "Delete a product custom field", "type": "http" }, "http": { "method": "DELETE", "url": "http://{defaultHost}/api/v3/admin/products/:product_id/custom_fields/:id", "headers": [ { "name": "x-spree-api-key", "value": "" }, { "name": "Authorization", "value": "" } ], "params": [ { "name": "product_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ], "auth": { "type": "apikey", "key": "x-spree-api-key", "value": "{{x-spree-api-key}}", "placement": "header" } }, "docs": "**Required scope:** `write_products` (for API-key authentication)." } ] } ], "bundled": true }