{ "openapi": "3.1.0", "info": { "title": "RM Ecommerce API", "version": "1.0.0", "summary": "REST API v1 for connectors, ERPs and integrations.", "description": "REST API of RM, a multi-tenant ecommerce platform. Each API key belongs to one store and only sees that store's data.\n\n- **Authentication:** `Authorization: Bearer rk__`. A back office session does not work.\n- **Permissions:** per area (`products`, `inventory`, `prices`, `customers`, `orders`, `integrations`); `GET` requires `read_`, everything else `write_` (ADR 0007).\n- **Cursor pagination** (ADR 0008): `?limit=` (1 to 500) and the `next` URL as is; there is no `offset` or `count`.\n- **Rate limit:** 600 requests per minute per key; `429` with `Retry-After`.\n- **Decimals** as strings; **public IDs** (UUID) for anything without a code.\n- Outgoing webhooks (`order.*`, `inventory.changed`): see the `webhooks` section and `docs/api.en.md`.\n\nFull business rules: `docs/api.en.md`.", "license": { "name": "Propietaria" } }, "servers": [ { "url": "{base_url}", "description": "API base URL (includes `/api/v1`).", "variables": { "base_url": { "default": "https://retail-s.online/api/v1", "description": "VPS: `https://retail-s.online/api/v1`. Local: `http://127.0.0.1:8000/api/v1`." } } } ], "tags": [ { "name": "Connection", "description": "Test the key and see its permissions." }, { "name": "Catalog", "description": "Products, variants, images, categories, brands, collections, attributes, templates, modifiers and translations. Permission `products`." }, { "name": "Bulk catalog", "description": "Bulk creation and NDJSON import of products. Permission `products`." }, { "name": "Inventory", "description": "Stock levels and locations. Permission `inventory`." }, { "name": "Prices", "description": "Prices and price lists. Permission `prices`." }, { "name": "Customers", "description": "Customers and customer groups. Permission `customers`." }, { "name": "Orders", "description": "Orders, status changes, payments, returns, refunds, carriers and payment methods. Permission `orders`." }, { "name": "Integrations", "description": "Connections, sync runs and external references. Permission `integrations`." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/": { "get": { "tags": [ "Connection" ], "summary": "Test connection", "security": [ { "bearerAuth": [] } ], "description": "Returns the store, the key name and its permissions. Any valid key works, whatever its scopes.", "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Root" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_root", "x-postman-name": "Test connection" } }, "/categories/": { "get": { "tags": [ "Catalog" ], "summary": "List categories", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_categories" }, "post": { "tags": [ "Catalog" ], "summary": "Create the category", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "example": { "code": "EXAMPLE", "name": "T-shirts", "parent": "CLOTHING", "is_active": true } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_categories" } }, "/categories/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get the category", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the category (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_categories_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace the category (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the category (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "example": { "name": "T-shirts", "parent": "CLOTHING", "is_active": true } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_categories_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update fields of the category", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the category (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "example": { "name": "T-shirts" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_categories_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete the category", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the category (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_categories_code" } }, "/variant-templates/": { "get": { "tags": [ "Catalog" ], "summary": "List variant-templates", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_VariantTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variant_templates" }, "post": { "tags": [ "Catalog" ], "summary": "Create the variant template", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" }, "example": { "code": "EXAMPLE", "name": "Clothing", "options": [ { "name": "Size", "values": [ "S", "M", "L" ] } ] } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_variant_templates" } }, "/variant-templates/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get the variant template", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the variant template (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variant_templates_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace the variant template (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the variant template (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" }, "example": { "name": "Clothing", "options": [ { "name": "Size", "values": [ "S", "M", "L" ] } ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_variant_templates_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update fields of the variant template", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the variant template (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" }, "example": { "name": "Clothing" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_variant_templates_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete the variant template", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the variant template (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_variant_templates_code" } }, "/brands/": { "get": { "tags": [ "Catalog" ], "summary": "List brands", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Brand" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_brands" }, "post": { "tags": [ "Catalog" ], "summary": "Create the brand", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" }, "example": { "code": "EXAMPLE", "name": "Example Brand", "is_active": true } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_brands" } }, "/brands/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get the brand", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the brand (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_brands_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace the brand (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the brand (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" }, "example": { "name": "Example Brand", "is_active": true } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_brands_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update fields of the brand", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the brand (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" }, "example": { "name": "Example Brand" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_brands_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete the brand", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the brand (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_brands_code" } }, "/collections/": { "get": { "tags": [ "Catalog" ], "summary": "List collections", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_collections" }, "post": { "tags": [ "Catalog" ], "summary": "Create the collection", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "code": "EXAMPLE", "name": "New arrivals", "is_active": true, "featured": false, "products": [ "PLY-001" ] } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_collections" } }, "/collections/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get the collection", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the collection (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_collections_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace the collection (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the collection (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "name": "New arrivals", "is_active": true, "featured": false, "products": [ "PLY-001" ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_collections_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update fields of the collection", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the collection (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "name": "New arrivals" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_collections_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete the collection", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the collection (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_collections_code" } }, "/modifier-groups/": { "get": { "tags": [ "Catalog" ], "summary": "List modifier-groups", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ModifierGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_modifier_groups" }, "post": { "tags": [ "Catalog" ], "summary": "Create the modifier group", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" }, "example": { "code": "EXAMPLE", "name": "Extras", "min_select": 0, "max_select": 2, "modifiers": [ { "code": "CHEESE", "name": "Cheese", "price": "0.75" }, { "code": "BACON", "name": "Bacon", "price": "1.25" } ] } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_modifier_groups" } }, "/modifier-groups/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get the modifier group", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the modifier group (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_modifier_groups_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace the modifier group (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the modifier group (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" }, "example": { "name": "Extras", "min_select": 0, "max_select": 2, "modifiers": [ { "code": "CHEESE", "name": "Cheese", "price": "0.75" }, { "code": "BACON", "name": "Bacon", "price": "1.25" } ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_modifier_groups_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update fields of the modifier group", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the modifier group (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" }, "example": { "name": "Extras" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_modifier_groups_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete the modifier group", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the modifier group (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_modifier_groups_code" } }, "/attributes/": { "get": { "tags": [ "Catalog" ], "summary": "List attributes", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Attribute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_attributes" }, "post": { "tags": [ "Catalog" ], "summary": "Create the attribute", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" }, "example": { "code": "EXAMPLE", "name": "Material", "type": "option", "scope": "product", "options": [ "Cotton", "Polyester" ], "is_filterable": true } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_attributes" } }, "/attributes/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get the attribute", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the attribute (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_attributes_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace the attribute (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the attribute (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" }, "example": { "name": "Material", "type": "option", "scope": "product", "options": [ "Cotton", "Polyester" ], "is_filterable": true } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_attributes_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update fields of the attribute", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the attribute (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" }, "example": { "name": "Material" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_attributes_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete the attribute", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the attribute (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_attributes_code" } }, "/locations/": { "get": { "tags": [ "Inventory" ], "summary": "List locations", "x-required-scope": "read_inventory", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_inventory`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Location" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_locations" }, "post": { "tags": [ "Inventory" ], "summary": "Create the location", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_inventory`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "code": "EXAMPLE", "name": "Distribution center", "kind": "warehouse", "allows_pickup": false, "ships_orders": true, "hours": [ { "weekday": 0, "opens": "09:00", "closes": "18:00" } ] } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_locations" } }, "/locations/{code}/": { "get": { "tags": [ "Inventory" ], "summary": "Get the location", "x-required-scope": "read_inventory", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the location (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_locations_code" }, "put": { "tags": [ "Inventory" ], "summary": "Create or replace the location (upsert)", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the location (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "name": "Distribution center", "kind": "warehouse", "allows_pickup": false, "ships_orders": true, "hours": [ { "weekday": 0, "opens": "09:00", "closes": "18:00" } ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_locations_code" }, "patch": { "tags": [ "Inventory" ], "summary": "Update fields of the location", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the location (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "name": "Distribution center" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_locations_code" }, "delete": { "tags": [ "Inventory" ], "summary": "Delete the location", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the location (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_locations_code" } }, "/price-lists/": { "get": { "tags": [ "Prices" ], "summary": "List price-lists", "x-required-scope": "read_prices", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_prices`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PriceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_price_lists" }, "post": { "tags": [ "Prices" ], "summary": "Create the price list", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_prices`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" }, "example": { "code": "EXAMPLE", "name": "Wholesale", "currency": "USD", "prices_include_tax": false, "priority": 10, "customer_groups": [ "WHOLESALE" ] } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_price_lists" } }, "/price-lists/{code}/": { "get": { "tags": [ "Prices" ], "summary": "Get the price list", "x-required-scope": "read_prices", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the price list (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_price_lists_code" }, "put": { "tags": [ "Prices" ], "summary": "Create or replace the price list (upsert)", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the price list (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" }, "example": { "name": "Wholesale", "currency": "USD", "prices_include_tax": false, "priority": 10, "customer_groups": [ "WHOLESALE" ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_price_lists_code" }, "patch": { "tags": [ "Prices" ], "summary": "Update fields of the price list", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the price list (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" }, "example": { "name": "Wholesale" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_price_lists_code" }, "delete": { "tags": [ "Prices" ], "summary": "Delete the price list", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the price list (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_price_lists_code" } }, "/customer-groups/": { "get": { "tags": [ "Customers" ], "summary": "List customer-groups", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_customers`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CustomerGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customer_groups" }, "post": { "tags": [ "Customers" ], "summary": "Create the customer group", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "The body carries `code`. `409`/`400` if the code already exists. Permission: `write_customers`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" }, "example": { "code": "EXAMPLE", "name": "Wholesalers", "description": "Buys by the case" } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_customer_groups" } }, "/customer-groups/{code}/": { "get": { "tags": [ "Customers" ], "summary": "Get the customer group", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the customer group (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customer_groups_code" }, "put": { "tags": [ "Customers" ], "summary": "Create or replace the customer group (upsert)", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "`201` if it creates it, `200` if it replaces it. The code in the path takes precedence over the one in the body. Permission: `write_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the customer group (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" }, "example": { "name": "Wholesalers", "description": "Buys by the case" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_customer_groups_code" }, "patch": { "tags": [ "Customers" ], "summary": "Update fields of the customer group", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Only the fields sent; `404` if it does not exist. Permission: `write_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the customer group (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" }, "example": { "name": "Wholesalers" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_customer_groups_code" }, "delete": { "tags": [ "Customers" ], "summary": "Delete the customer group", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "`400` if other records depend on it. Permission: `write_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the customer group (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_customer_groups_code" } }, "/products/": { "get": { "tags": [ "Catalog" ], "summary": "List products", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Status.", "schema": { "type": "string", "enum": [ "draft", "active", "archived" ] } }, { "name": "category", "in": "query", "description": "Category code.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Text in name, code or SKU.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products" }, "post": { "tags": [ "Catalog" ], "summary": "Create product", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "code": "PLY-001", "name": "Basic T-shirt", "status": "active", "category": "TSHIRTS", "short_description": "100 % cotton", "base_unit": "PC", "tax_exempt": false, "track_inventory": true, "options": [ { "name": "Color", "values": [ "Black", "White" ] }, { "name": "Size", "values": [ "S", "M", "L" ] } ], "variants": [ { "code": "NEGRO-CH", "sku": "PLY-001-N-CH", "barcode": "7501234567890" } ], "attributes": { "MATERIAL": "Cotton" } } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products" } }, "/products/{code}/": { "get": { "tags": [ "Catalog" ], "summary": "Get product", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Includes variants with their options, stock by location and prices, images and attributes. Permission: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_code" }, "put": { "tags": [ "Catalog" ], "summary": "Create or replace product (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201`/`200`. `options` and `attributes` are declarative; it is applied in full or not at all. See `variants_mode: exact` in `docs/api.en.md`. Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "name": "Basic T-shirt", "status": "active", "category": "TSHIRTS", "short_description": "100 % cotton", "base_unit": "PC", "tax_exempt": false, "track_inventory": true, "options": [ { "name": "Color", "values": [ "Black", "White" ] }, { "name": "Size", "values": [ "S", "M", "L" ] } ], "variants": [ { "code": "NEGRO-CH", "sku": "PLY-001-N-CH", "barcode": "7501234567890" } ], "attributes": { "MATERIAL": "Cotton" } } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_products_code" }, "patch": { "tags": [ "Catalog" ], "summary": "Update product fields", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "status": "archived" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_products_code" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete product", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_products_code" } }, "/products/{code}/duplicate/": { "post": { "tags": [ "Catalog" ], "summary": "Duplicate product", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateInput" }, "example": { "code": "PLY-001-COPY", "name": "Basic T-shirt (copy)", "copy_images": true, "copy_prices": true } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_code_duplicate" } }, "/products/{code}/images/": { "post": { "tags": [ "Catalog" ], "summary": "Add or replace image", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`multipart/form-data` with `image`, or JSON with `url` (https, not downloaded). A repeated `external_key` replaces the image (`200`). Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUrl" }, "example": { "url": "https://cdn.example.com/tshirt.jpg", "external_key": "LS-1", "alt_text": "Black T-shirt, front view", "variant_skus": [ "PLY-001-N-CH" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageUpload" } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductImage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_code_images" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete image by external key", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } }, { "name": "external_key", "in": "query", "description": "External key of the image.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_products_code_images" } }, "/products/{code}/images/{image_id}/": { "delete": { "tags": [ "Catalog" ], "summary": "Delete image by id", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the product (stored in uppercase).", "schema": { "type": "string" } }, { "name": "image_id", "in": "path", "required": true, "description": "`id` (UUID) of the image.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_products_code_images_image_id" } }, "/variants/": { "get": { "tags": [ "Catalog" ], "summary": "List variants", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "product", "in": "query", "description": "Product code.", "schema": { "type": "string" } }, { "name": "barcode", "in": "query", "description": "Exact barcode.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Variant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variants" } }, "/variants/{sku}/": { "get": { "tags": [ "Catalog" ], "summary": "Get variant", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "SKU of the variant.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variants_sku" }, "patch": { "tags": [ "Catalog" ], "summary": "Update variant", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Only `sku`, `barcode`, `weight`, `is_active` and `attributes`; combinations come from the product options. Permission: `write_products`.", "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "SKU of the variant.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" }, "example": { "barcode": "7501234567890", "is_active": true } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_variants_sku" }, "delete": { "tags": [ "Catalog" ], "summary": "Delete variant", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`409` if it has orders (deactivate it with `is_active: false`) or if it is the product's only variant. Permission: `write_products`.", "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "SKU of the variant.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminada.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_variants_sku" } }, "/translations/": { "get": { "tags": [ "Catalog" ], "summary": "Get translations", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "object_type", "in": "query", "description": "Tipo.", "schema": { "type": "string", "enum": [ "product", "category", "collection", "brand", "attribute" ] }, "required": true }, { "name": "object_key", "in": "query", "description": "Record code.", "schema": { "type": "string" }, "required": true }, { "name": "language", "in": "query", "description": "Language, e.g. `en`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_translations" }, "put": { "tags": [ "Catalog" ], "summary": "Save translations", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "The language must be enabled as an extra language in the store. An empty value deletes the translation. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationInput" }, "example": { "object_type": "product", "object_key": "PLY-001", "language": "en", "fields": { "name": "Basic T-shirt" } } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_translations" } }, "/products/bulk/": { "post": { "tags": [ "Bulk catalog" ], "summary": "Bulk create products (up to 500)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Upsert by code, processed by the worker. One bad product does not fail the others. Permission: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsBulkInput" }, "example": { "items": [ { "code": "PLY-001", "name": "Basic T-shirt" }, { "code": "PLY-002", "name": "Printed T-shirt" } ] } } } }, "responses": { "202": { "description": "Job queued.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_bulk" } }, "/products/bulk/{id}/": { "get": { "tags": [ "Bulk catalog" ], "summary": "Status and result of a bulk creation", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the job.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RowStatus" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_bulk_id" } }, "/products/import/": { "post": { "tags": [ "Bulk catalog" ], "summary": "Import NDJSON catalog (create only)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`multipart/form-data` with `file` (NDJSON, up to 256 MB). Meant for first loads of tens or hundreds of thousands of products. Permission: `write_products`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImportUpload" } } } }, "responses": { "202": { "description": "Job queued.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_import" } }, "/products/import/{id}/": { "get": { "tags": [ "Bulk catalog" ], "summary": "Status of an import", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_products`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the import.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RowStatus" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_import_id" } }, "/products/import/{id}/rows/": { "get": { "tags": [ "Bulk catalog" ], "summary": "Full result of an import (NDJSON)", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "One row per line (`application/x-ndjson`), in order and unpaginated. Permission: `read_products`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the import.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RowStatus" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "One JSON object per line." } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_import_id_rows" } }, "/inventory/": { "get": { "tags": [ "Inventory" ], "summary": "Get stock levels", "x-required-scope": "read_inventory", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_inventory`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "sku", "in": "query", "description": "SKU.", "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Location code.", "schema": { "type": "string" } }, { "name": "product", "in": "query", "description": "Product code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_InventoryRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_inventory" } }, "/inventory/bulk/": { "post": { "tags": [ "Inventory" ], "summary": "Set stock levels in bulk (absolute)", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "`on_hand` is the ERP's absolute stock, not an adjustment. Up to 1000 rows. All or nothing, unless `partial=true`. Permission: `write_inventory`.", "parameters": [ { "$ref": "#/components/parameters/Partial" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryBulkInput" }, "example": { "items": [ { "sku": "PLY-001-N-CH", "location": "DC", "on_hand": "12" }, { "sku": "PLY-001-N-CH", "location": "TDA-CENTRO", "on_hand": "3", "reference": "ERP 2026-10-14" } ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_inventory_bulk" } }, "/prices/": { "get": { "tags": [ "Prices" ], "summary": "Get prices", "x-required-scope": "read_prices", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_prices`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "price_list", "in": "query", "description": "Price list code.", "schema": { "type": "string" } }, { "name": "sku", "in": "query", "description": "SKU.", "schema": { "type": "string" } }, { "name": "product", "in": "query", "description": "Product code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PriceRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_prices" } }, "/prices/bulk/": { "post": { "tags": [ "Prices" ], "summary": "Set prices in bulk", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "Up to 1000 rows; `price: null` deletes the line. All or nothing, unless `partial=true`. Permission: `write_prices`.", "parameters": [ { "$ref": "#/components/parameters/Partial" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesBulkInput" }, "example": { "items": [ { "price_list": "GENERAL", "sku": "PLY-001-N-CH", "price": "249.00", "compare_at_price": "299.00" }, { "price_list": "GENERAL", "sku": "PLY-001-N-CH", "price": "220.00", "min_quantity": "6" }, { "price_list": "MAYOREO", "sku": "PLY-001-N-M", "price": null } ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_prices_bulk" } }, "/customers/": { "get": { "tags": [ "Customers" ], "summary": "List customers", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_customers`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "q", "in": "query", "description": "Text in first name, last name, email or company.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Exact email.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "Customer code.", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "Group code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customers" }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_customers`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "code": "C-100", "first_name": "Carlos", "last_name": "Hernández", "company": "Bajío Uniforms", "email": "purchasing@example.com", "phone": "477 555 0101", "group": "WHOLESALE", "accepts_marketing": false, "addresses": [ { "label": "Headquarters", "line1": "Blvd. López Mateos 3401", "city": "León", "state": "Guanajuato", "postal_code": "37160", "country": "MX" } ] } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_customers" } }, "/customers/{id}/": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customers_id" }, "put": { "tags": [ "Customers" ], "summary": "Replace customer", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "`addresses` is declarative: if you send it, it replaces all addresses. Permission: `write_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "code": "C-100", "first_name": "Carlos", "last_name": "Hernández", "company": "Bajío Uniforms", "email": "purchasing@example.com", "phone": "477 555 0101", "group": "WHOLESALE", "accepts_marketing": false, "addresses": [ { "label": "Headquarters", "line1": "Blvd. López Mateos 3401", "city": "León", "state": "Guanajuato", "postal_code": "37160", "country": "MX" } ] } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_customers_id" }, "patch": { "tags": [ "Customers" ], "summary": "Update customer fields", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "phone": "477 555 0102" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_customers_id" }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_customers_id" } }, "/orders/": { "get": { "tags": [ "Orders" ], "summary": "List orders", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Creation order (not by number). For the ERP pull use `updated_since` or `placed_since`. Permission: `read_orders`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "number", "in": "query", "description": "Number the store sees (`1001` or `#1001`).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Status.", "schema": { "type": "string", "enum": [ "open", "cancelled", "archived" ] } }, { "name": "payment_status", "in": "query", "description": "Payment status.", "schema": { "type": "string", "enum": [ "pending", "authorized", "paid", "partially_refunded", "refunded", "failed" ] } }, { "name": "fulfillment_status", "in": "query", "description": "Fulfillment status.", "schema": { "type": "string", "enum": [ "unfulfilled", "prepared", "ready_for_pickup", "shipped", "delivered" ] } }, { "name": "delivery_type", "in": "query", "description": "Delivery type.", "schema": { "type": "string", "enum": [ "shipping", "pickup", "takeout", "dine_in", "delivery_app" ] } }, { "name": "customer", "in": "query", "description": "`id` (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "placed_since", "in": "query", "description": "Orders placed since this date (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_orders" }, "post": { "tags": [ "Orders" ], "summary": "Create order", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "`201` the first time; with a repeated `Idempotency-Key` and the same data, `200` with the same order. Rejects (400) without stock or without a price. Permission: `write_orders`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "example": { "customer_email": "purchasing@example.com", "lines": [ { "sku": "PLY-001-N-CH", "quantity": "6" }, { "sku": "COC-002", "quantity": "1", "unit_price": "14.50" } ], "shipping_address": { "line1": "Blvd. Los Próceres 12", "city": "Antiguo Cuscatlán", "state": "La Libertad", "country": "SV" }, "location": "DC", "discount": "0", "shipping": "8.00", "notes": "" } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders" } }, "/orders/{id}/": { "get": { "tags": [ "Orders" ], "summary": "Get order", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_orders_id" } }, "/orders/{id}/pay/": { "post": { "tags": [ "Orders" ], "summary": "Record payment", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. With `Idempotency-Key` it always returns `200` and does not record another payment. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayInput" }, "example": { "method": "transfer", "reference": "T-123" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_pay" } }, "/orders/{id}/prepare/": { "post": { "tags": [ "Orders" ], "summary": "Mark as prepared / accepted by the ERP", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. Sets the informational stamp `erp_accepted_at`; it neither releases nor deducts stock. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_prepare" } }, "/orders/{id}/ship/": { "post": { "tags": [ "Orders" ], "summary": "Mark as shipped (deducts stock)", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. With `carrier_code` it computes `tracking_url`; with `carrier` (text) it first looks among the store's carriers. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipInput" }, "example": { "carrier_code": "C807", "tracking_number": "ABC123" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_ship" } }, "/orders/{id}/ready/": { "post": { "tags": [ "Orders" ], "summary": "Mark as ready for pickup (deducts stock)", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. `pickup` orders. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_ready" } }, "/orders/{id}/deliver/": { "post": { "tags": [ "Orders" ], "summary": "Mark as delivered", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. From `shipped` or `ready_for_pickup`. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_deliver" } }, "/orders/{id}/cancel/": { "post": { "tags": [ "Orders" ], "summary": "Cancel order", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. Releases reserved stock; refunds the payment if it was already charged. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInput" }, "example": { "reason": "Requested by the customer" } } } }, "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_cancel" } }, "/orders/{id}/archive/": { "post": { "tags": [ "Orders" ], "summary": "Archive order", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. Only cancelled, delivered or refunded orders. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_archive" } }, "/orders/{id}/unarchive/": { "post": { "tags": [ "Orders" ], "summary": "Unarchive order", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Returns the full order, or `409` if the step does not apply. Restores it to how it was. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_unarchive" } }, "/orders/{id}/returns/": { "post": { "tags": [ "Orders" ], "summary": "Record return", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "`201`, then `200` when repeated with the same `Idempotency-Key`. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnInput" }, "example": { "lines": [ { "line_id": "0192f3a4-6b1c-7d2e-9f00-1a2b3c4d5e6f", "quantity": "1" } ], "reason": "Size", "restock": true } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_returns" } }, "/orders/{id}/refunds/": { "post": { "tags": [ "Orders" ], "summary": "Refund a payment", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Synchronous: with a payment gateway it is requested in the same call and, if it fails, `409` with no trace. `200` when repeated with the same key. Permission: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" }, "example": { "amount": "25.00", "reason": "Damaged product" } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_refunds" } }, "/orders/{id}/payments/": { "get": { "tags": [ "Orders" ], "summary": "List order payments", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Read only; each payment includes its `refunds`. Permission: `read_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_orders_id_payments" } }, "/carriers/": { "get": { "tags": [ "Orders" ], "summary": "List carriers", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Read only. Includes deactivated ones. Permission: `read_orders`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Carrier" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_carriers" } }, "/carriers/{code}/": { "get": { "tags": [ "Orders" ], "summary": "Get carrier", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_orders`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the carrier (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Carrier" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_carriers_code" } }, "/payment-methods/": { "get": { "tags": [ "Orders" ], "summary": "List payment methods", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Read only. Includes deactivated ones. Permission: `read_orders`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PaymentMethod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_payment_methods" } }, "/payment-methods/{code}/": { "get": { "tags": [ "Orders" ], "summary": "Get payment method", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_orders`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code of the payment method (stored in uppercase).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_payment_methods_code" } }, "/connections/": { "get": { "tags": [ "Integrations" ], "summary": "List connections", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Read only; connections are created in the back office. Permission: `read_integrations`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Connection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_connections" } }, "/connections/{id}/": { "get": { "tags": [ "Integrations" ], "summary": "Get connection", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the connection.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_connections_id" } }, "/connections/{id}/sync-runs/": { "get": { "tags": [ "Integrations" ], "summary": "List sync runs", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the connection.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "kind", "in": "query", "description": "Run type (`products`, `inventory`…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SyncRun" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_connections_id_sync_runs" }, "post": { "tags": [ "Integrations" ], "summary": "Report a sync run", "x-required-scope": "write_integrations", "security": [ { "bearerAuth": [] } ], "description": "Sets the connection's `last_sync_at` to `finished_at` (never moves it back; a `failed` run does not move it). Permission: `write_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the connection.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRunInput" }, "example": { "kind": "inventory", "started_at": "2026-10-17T10:00:00Z", "finished_at": "2026-10-17T10:05:00Z", "records": 1200, "errors": 3, "message": "3 SKUs without a variant" } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_connections_id_sync_runs" } }, "/external-references/": { "get": { "tags": [ "Integrations" ], "summary": "Search external references", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permission: `read_integrations`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "connection", "in": "query", "description": "`id` (UUID) of the connection.", "schema": { "type": "string", "format": "uuid" } }, { "name": "object_type", "in": "query", "description": "Local object type.", "schema": { "type": "string" } }, { "name": "object_key", "in": "query", "description": "Code (or SKU, or number) of the object; requires `object_type`.", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "description": "ID in the external system.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExternalReference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_external_references" }, "post": { "tags": [ "Integrations" ], "summary": "Save external reference (upsert)", "x-required-scope": "write_integrations", "security": [ { "bearerAuth": [] } ], "description": "Upsert by (connection, local record): `201` if it creates, `200` if it updates. An `external_id` cannot be linked to two records. Permission: `write_integrations`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceInput" }, "example": { "connection": "0192f3a4-6b1c-7d2e-9f00-1a2b3c4d5e6f", "object_type": "product", "object_key": "PLY-001", "external_id": "5c2e0000-0000-0000-0000-000000000000", "external_code": "1000" } } } }, "responses": { "201": { "description": "Successful.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_external_references" } }, "/external-references/{id}/": { "delete": { "tags": [ "Integrations" ], "summary": "Delete external reference", "x-required-scope": "write_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permission: `write_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public `id` (UUID) of the reference.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_external_references_id" } } }, "webhooks": { "rmEvent": { "post": { "summary": "Event from the store to your system", "description": "Sent by the store's Webhooks app to the configured `https` URL. Headers: `X-RM-Event`, `X-RM-Event-Id` (= `id`), `X-RM-Signature` (hex HMAC-SHA256 of the exact body with the app secret) and `User-Agent: RM-Webhooks/1`. Reply `2xx` to acknowledge; on `5xx`, `429`, `408` or a network error it is retried (up to 8 times in ~2 h, same body, `id` and signature). At least once and with no guaranteed order.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "6f1c0000-0000-0000-0000-000000000000", "event": "order.created", "store": "mia", "occurred_at": "2026-10-15T20:31:02+00:00", "data": { "number": 1001, "payment_status": "pending" } } } } }, "responses": { "200": { "description": "Recibido." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "rk__", "description": "The store's API key (Settings → API keys)." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "Page size (1 to 500, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor; use the `next` URL as is.", "schema": { "type": "string" } }, "UpdatedSince": { "name": "updated_since", "in": "query", "description": "Only records modified since this date (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-14T00:00:00Z" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Safe retries (up to 100 characters, no control characters). Same key and same data: the operation is not repeated; different data: `409`.", "schema": { "type": "string", "maxLength": 100 } }, "Partial": { "name": "partial", "in": "query", "description": "`true`: applies the valid rows and reports the rest (also `\"partial\": true` in the body).", "schema": { "type": "boolean", "default": false } }, "RowStatus": { "name": "status", "in": "query", "description": "`error` keeps only the rows with errors.", "schema": { "type": "string", "enum": [ "error" ] } }, "Offset": { "name": "offset", "in": "query", "description": "First row of the result (a job's rows are paginated this way, not by cursor).", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed per minute (per key).", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Second (Unix epoch) at which the oldest slot is freed.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds left until you can retry.", "schema": { "type": "integer" } } }, "responses": { "Unauthorized": { "description": "No key, or an invalid or deactivated key. No `X-RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the area permission (`read_` or `write_`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Does not exist in the key's store (also if it belongs to another store).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Validation: details per field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Conflict": { "description": "The step does not apply to the current status, or the `Idempotency-Key` was used with different data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "The key's budget is used up. Wait `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "detail": { "type": "string" } }, "description": "Authentication, permission or business rule error." }, "ValidationError": { "type": "object", "properties": {}, "description": "Validation error (`400`): field -> list of messages (or a message). Bulk operations use `errors` by index.", "additionalProperties": true }, "Root": { "type": "object", "properties": { "api_version": { "type": "string" }, "tenant": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "default_currency": { "type": "string" }, "prices_include_tax": { "type": "boolean" } } }, "api_key": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Key permissions: `read_` and `write_` (`products`, `inventory`, `prices`, `customers`, `orders`, `integrations`)." } } }, "Page_Category": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } }, "required": [ "next", "results" ] }, "Page_Brand": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } } }, "required": [ "next", "results" ] }, "Page_Collection": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } }, "required": [ "next", "results" ] }, "Page_Attribute": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } }, "required": [ "next", "results" ] }, "Page_Location": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } }, "required": [ "next", "results" ] }, "Page_PriceList": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PriceList" } } }, "required": [ "next", "results" ] }, "Page_CustomerGroup": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerGroup" } } }, "required": [ "next", "results" ] }, "Page_VariantTemplate": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VariantTemplate" } } }, "required": [ "next", "results" ] }, "Page_ModifierGroup": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ModifierGroup" } } }, "required": [ "next", "results" ] }, "Page_Customer": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } }, "required": [ "next", "results" ] }, "Page_ProductRead": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRead" } } }, "required": [ "next", "results" ] }, "Page_Variant": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } } }, "required": [ "next", "results" ] }, "Page_Order": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } }, "required": [ "next", "results" ] }, "Page_Carrier": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Carrier" } } }, "required": [ "next", "results" ] }, "Page_PaymentMethod": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } }, "required": [ "next", "results" ] }, "Page_Connection": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } }, "required": [ "next", "results" ] }, "Page_SyncRun": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRun" } } }, "required": [ "next", "results" ] }, "Page_ExternalReference": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } }, "required": [ "next", "results" ] }, "Page_PriceRow": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PriceRow" } } }, "required": [ "next", "results" ] }, "Page_InventoryRow": { "type": "object", "description": "Cursor-paginated page of results. `next` is the URL of the next page (request it as is) or `null` on the last one.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryRow" } } }, "required": [ "next", "results" ] }, "Category": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "position": { "type": "integer" }, "is_active": { "type": "boolean" }, "attributes": { "type": "array", "items": { "type": "string" }, "description": "Attribute codes." }, "variant_template": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "code", "name" ] }, "Brand": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "logo": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Collection": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "image": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "featured": { "type": "boolean" }, "position": { "type": "integer" }, "products": { "type": "array", "items": { "type": "string" }, "description": "Product codes; declarative." }, "is_automatic": { "type": "boolean", "readOnly": true }, "rules": { "readOnly": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Attribute": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "integer", "decimal", "date", "boolean", "option" ] }, "scope": { "type": "string", "enum": [ "product", "variant" ] }, "unit": { "type": "string" }, "is_filterable": { "type": "boolean" }, "position": { "type": "integer" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Declarative: only for `type` `option`." }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "LocationHours": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 = Monday … 6 = Sunday." }, "opens": { "type": "string" }, "closes": { "type": "string" } }, "required": [ "weekday", "opens", "closes" ], "description": "Time range `HH:MM`; if `closes` < `opens` it crosses midnight." }, "Location": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "store", "warehouse" ] }, "address": { "type": "string" }, "allows_pickup": { "type": "boolean" }, "ships_orders": { "type": "boolean" }, "fulfills_online_orders": { "type": "boolean" }, "is_active": { "type": "boolean" }, "position": { "type": "integer" }, "hours": { "type": "array", "items": { "$ref": "#/components/schemas/LocationHours" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "PriceList": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "prices_include_tax": { "type": "boolean" }, "starts_on": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "ends_on": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "is_default": { "type": "boolean" }, "priority": { "type": "integer" }, "is_active": { "type": "boolean" }, "customer_groups": { "type": "array", "items": { "type": "string" }, "description": "Group codes; empty = all." }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "CustomerGroup": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "VariantTemplate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionInput" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Modifier": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, "is_active": { "type": "boolean" } }, "required": [ "code", "name" ] }, "ModifierGroup": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "min_select": { "type": "integer" }, "max_select": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "position": { "type": "integer" }, "modifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Modifier" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Address": { "type": "object", "properties": { "label": { "type": "string" }, "recipient": { "type": "string" }, "company": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "description": "2-letter country code (MX, SV, US…)." }, "phone": { "type": "string" }, "is_default_shipping": { "type": "boolean" }, "is_default_billing": { "type": "boolean" } }, "required": [ "line1", "city", "country" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "code": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "type": "string" }, "tax_id": { "type": "string" }, "group": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "accepts_marketing": { "type": "boolean" }, "notes": { "type": "string" }, "is_active": { "type": "boolean" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "first_name" ] }, "ProductOptionInput": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string" }, "color": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "value" ] } ] }, "description": "Strings or `{value, color}` with a `#RRGGBB` color." } }, "required": [ "name", "values" ] }, "VariantInput": { "type": "object", "properties": { "code": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Only with `variants_mode: exact`: `{\"Color\": \"Black\"}`." }, "attributes": { "type": "object", "additionalProperties": true, "description": "`{CODE: value}` of attributes with `scope` `variant`; `null` deletes." } } }, "Variant": { "type": "object", "properties": { "product": { "type": "string" }, "code": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "type": "string" } }, "option_colors": { "type": "object", "additionalProperties": true }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "attributes": { "type": "object", "additionalProperties": true }, "position": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProductImage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "url": { "type": "string", "readOnly": true }, "thumbnail_url": { "type": "string", "readOnly": true }, "external_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "readOnly": true }, "external_key": { "type": "string", "readOnly": true }, "alt_text": { "type": "string", "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "width": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "readOnly": true }, "height": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "readOnly": true }, "variant_skus": { "type": "array", "items": { "type": "string" }, "readOnly": true } } }, "Product": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "short_description": { "type": "string" }, "description": { "type": "string" }, "base_unit": { "type": "string" }, "tax_exempt": { "type": "boolean" }, "tax_code": { "type": "string" }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "track_inventory": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionInput" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/VariantInput" } }, "variants_mode": { "type": "string", "enum": [ "exact" ], "description": "Optional; see `docs/api.en.md` (#68)." }, "attributes": { "type": "object", "additionalProperties": true }, "units": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "modifier_groups": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ], "description": "On read, `variants` also includes stock by location and prices, and `images` the images." }, "ProductOptionRead": { "type": "object", "properties": { "name": { "type": "string", "readOnly": true }, "values": { "type": "array", "items": { "type": "string" }, "readOnly": true }, "colors": { "type": "object", "additionalProperties": { "type": "string" }, "description": "`{value: #RRGGBB}`, only the values that have a color.", "readOnly": true } } }, "VariantInventory": { "type": "object", "properties": { "location": { "type": "string", "readOnly": true }, "on_hand": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "reserved": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "available": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true } } }, "VariantPrice": { "type": "object", "properties": { "price_list": { "type": "string", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "compare_at_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ], "readOnly": true }, "min_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true } } }, "ProductVariantRead": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "sku": { "type": "string", "readOnly": true }, "barcode": { "type": "string", "readOnly": true }, "title": { "type": "string", "readOnly": true }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "readOnly": true }, "option_colors": { "type": "object", "additionalProperties": true, "readOnly": true }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ], "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "attributes": { "type": "object", "additionalProperties": true, "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "inventory": { "type": "array", "items": { "$ref": "#/components/schemas/VariantInventory" }, "readOnly": true }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/VariantPrice" }, "readOnly": true } } }, "ProductRead": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "short_description": { "type": "string" }, "description": { "type": "string" }, "base_unit": { "type": "string" }, "tax_exempt": { "type": "boolean" }, "tax_code": { "type": "string" }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "track_inventory": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionRead" }, "readOnly": true }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantRead" }, "readOnly": true }, "attributes": { "type": "object", "additionalProperties": true }, "units": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "modifier_groups": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "readOnly": true }, "collections": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "Codes of the product's collections." } }, "description": "What the API returns for a product. To write, see `Product`." }, "OrderAddress": { "type": "object", "properties": { "label": { "type": "string" }, "recipient": { "type": "string" }, "company": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "description": "2-letter country code (MX, SV, US…)." }, "phone": { "type": "string" }, "is_default_shipping": { "type": "boolean" }, "is_default_billing": { "type": "boolean" } }, "required": [ "line1", "city", "country" ] }, "OrderLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "parent_line": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "readOnly": true }, "sku": { "type": "string", "readOnly": true }, "product_name": { "type": "string", "readOnly": true }, "variant_title": { "type": "string", "readOnly": true }, "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "unit_code": { "type": "string", "readOnly": true }, "unit_name": { "type": "string", "readOnly": true }, "unit_factor": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "unit_price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "line_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "returned_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true } } }, "OrderReturn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "reason": { "type": "string", "readOnly": true }, "restock": { "type": "boolean", "readOnly": true }, "refund_amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ], "readOnly": true }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "number": { "type": "integer", "readOnly": true }, "status": { "type": "string", "enum": [ "open", "cancelled", "archived" ], "readOnly": true }, "payment_status": { "type": "string", "enum": [ "pending", "authorized", "paid", "partially_refunded", "refunded", "failed" ], "readOnly": true }, "fulfillment_status": { "type": "string", "enum": [ "unfulfilled", "prepared", "ready_for_pickup", "shipped", "delivered" ], "readOnly": true }, "delivery_type": { "type": "string", "enum": [ "shipping", "pickup", "takeout", "dine_in", "delivery_app" ], "readOnly": true }, "table_number": { "type": "string", "readOnly": true }, "source": { "type": "string", "readOnly": true }, "customer": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "readOnly": true }, "customer_name": { "type": "string", "readOnly": true }, "email": { "type": "string", "readOnly": true }, "phone": { "type": "string", "readOnly": true }, "shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/OrderAddress" }, { "type": "null" } ], "readOnly": true }, "billing_address": { "oneOf": [ { "$ref": "#/components/schemas/OrderAddress" }, { "type": "null" } ], "readOnly": true }, "location": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "prices_include_tax": { "type": "boolean", "readOnly": true }, "tax_rate": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "subtotal": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "discount_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "shipping_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "tax_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "refunded_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "payment_method": { "type": "string", "readOnly": true }, "payment_method_name": { "type": "string", "readOnly": true }, "payment_reference": { "type": "string", "readOnly": true }, "carrier": { "type": "string", "readOnly": true }, "carrier_code": { "type": "string", "readOnly": true }, "carrier_service_code": { "type": "string", "readOnly": true }, "carrier_service_name": { "type": "string", "readOnly": true }, "carrier_fee": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "tracking_number": { "type": "string", "readOnly": true }, "tracking_url": { "type": "string", "readOnly": true }, "notes": { "type": "string", "readOnly": true }, "cancel_reason": { "type": "string", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" }, "readOnly": true }, "returns": { "type": "array", "items": { "$ref": "#/components/schemas/OrderReturn" }, "readOnly": true }, "placed_at": { "type": "string", "format": "date-time", "readOnly": true }, "paid_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "shipped_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "delivered_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "cancelled_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "archived_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "reservation_expires_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "erp_accepted_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Informational stamp: the ERP received the order.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "OrderLineInput": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, "unit_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "unit": { "type": "string" }, "modifiers": { "type": "array", "items": { "type": "string" }, "description": "Modifier codes." } }, "required": [ "sku", "quantity" ] }, "OrderCreate": { "type": "object", "properties": { "customer": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customer_email": { "type": "string" }, "customer_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineInput" }, "minItems": 1 }, "shipping_address": { "$ref": "#/components/schemas/OrderAddress" }, "billing_address": { "$ref": "#/components/schemas/OrderAddress" }, "location": { "type": "string" }, "discount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, "shipping": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, "notes": { "type": "string" }, "delivery_type": { "type": "string", "enum": [ "shipping", "pickup", "dine_in", "takeout", "delivery_app" ], "default": "shipping", "description": "Depends on what the store has enabled; an unsupported type returns `400`." }, "table_number": { "type": "string" }, "payment_method": { "type": "string" }, "carrier_code": { "type": "string" }, "carrier_service_code": { "type": "string" } }, "required": [ "lines" ] }, "PayInput": { "type": "object", "properties": { "method": { "type": "string" }, "reference": { "type": "string" } } }, "ShipInput": { "type": "object", "properties": { "carrier": { "type": "string" }, "carrier_code": { "type": "string" }, "tracking_number": { "type": "string" } } }, "CancelInput": { "type": "object", "properties": { "reason": { "type": "string" } } }, "ReturnInput": { "type": "object", "properties": { "lines": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "line_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." } }, "required": [ "line_id", "quantity" ] } }, "reason": { "type": "string" }, "restock": { "type": "boolean" }, "refund_amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] } }, "required": [ "lines", "reason" ] }, "RefundInput": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, "reason": { "type": "string" }, "payment": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "amount", "reason" ] }, "DuplicateInput": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "copy_images": { "type": "boolean" }, "copy_prices": { "type": "boolean" } } }, "PaymentRefund": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "pending", "done", "failed" ], "readOnly": true }, "reason": { "type": "string", "readOnly": true }, "provider_reference": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "completed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "provider": { "type": "string", "readOnly": true }, "method": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "pending", "authorized", "paid", "partially_refunded", "refunded", "failed", "expired" ], "readOnly": true }, "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "refunded_amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "provider_reference": { "type": "string", "readOnly": true }, "needs_review": { "type": "boolean", "readOnly": true }, "review_reason": { "type": "string", "enum": [ "late", "amount_mismatch", "duplicate", "" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "paid_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "failed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRefund" }, "readOnly": true } } }, "CarrierService": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "level": { "type": "string", "enum": [ "standard", "express" ], "readOnly": true }, "fee": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "position": { "type": "integer", "readOnly": true } } }, "Carrier": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "tracking_url_template": { "type": "string", "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierService" }, "readOnly": true } } }, "PaymentMethod": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "kind": { "type": "string", "enum": [ "card", "payment_link", "transfer", "cash_on_delivery", "in_store", "other" ], "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "reservation_hours": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "readOnly": true } } }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "kind": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "config": { "type": "object", "additionalProperties": true, "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true } } }, "SyncRunInput": { "type": "object", "properties": { "kind": { "type": "string", "maxLength": 30 }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "records": { "type": "integer" }, "errors": { "type": "integer" }, "status": { "type": "string", "enum": [ "ok", "partial", "failed" ] }, "message": { "type": "string", "maxLength": 2000 } }, "required": [ "kind", "started_at", "finished_at" ] }, "SyncRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "records": { "type": "integer" }, "errors": { "type": "integer" }, "status": { "type": "string", "enum": [ "ok", "partial", "failed" ] }, "message": { "type": "string" } } }, "ExternalReferenceInput": { "type": "object", "properties": { "connection": { "type": "string", "format": "uuid" }, "object_type": { "type": "string", "enum": [ "product", "variant", "category", "brand", "collection", "modifier_group", "modifier", "attribute", "location", "price_list", "customer_group", "customer", "order" ] }, "object_key": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Code; SKU for variants; number (integer) for orders." }, "external_id": { "type": "string" }, "external_code": { "type": "string" }, "data_hash": { "type": "string" }, "synced_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "connection", "object_type", "object_key", "external_id" ] }, "ExternalReference": { "type": "object", "properties": { "connection": { "type": "string", "format": "uuid" }, "object_type": { "type": "string", "enum": [ "product", "variant", "category", "brand", "collection", "modifier_group", "modifier", "attribute", "location", "price_list", "customer_group", "customer", "order" ] }, "object_key": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Code; SKU for variants; number (integer) for orders." }, "external_id": { "type": "string" }, "external_code": { "type": "string" }, "data_hash": { "type": "string" }, "synced_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "readOnly": true } }, "required": [ "connection", "object_type", "object_key", "external_id" ] }, "Translation": { "type": "object", "properties": { "language": { "type": "string" }, "field": { "type": "string" }, "value": { "type": "string" } } }, "TranslationInput": { "type": "object", "properties": { "object_type": { "type": "string", "enum": [ "product", "category", "collection", "brand", "attribute" ] }, "object_key": { "type": "string" }, "language": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field -> text (name, description…). Empty deletes." } }, "required": [ "object_type", "object_key", "language", "fields" ] }, "PriceRow": { "type": "object", "properties": { "price_list": { "type": "string", "readOnly": true }, "sku": { "type": "string", "readOnly": true }, "price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "compare_at_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ], "readOnly": true }, "min_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "PriceBulkItem": { "type": "object", "properties": { "price_list": { "type": "string" }, "sku": { "type": "string" }, "price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "compare_at_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, { "type": "null" } ] }, "min_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." } }, "required": [ "price_list", "sku", "price" ] }, "PricesBulkInput": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/PriceBulkItem" } }, "partial": { "type": "boolean" } }, "required": [ "items" ] }, "InventoryRow": { "type": "object", "properties": { "sku": { "type": "string", "readOnly": true }, "location": { "type": "string", "readOnly": true }, "on_hand": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "reserved": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "available": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "InventoryBulkItem": { "type": "object", "properties": { "sku": { "type": "string" }, "location": { "type": "string" }, "on_hand": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal as a string." }, "reference": { "type": "string" } }, "required": [ "sku", "location", "on_hand" ] }, "InventoryBulkInput": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/InventoryBulkItem" } }, "partial": { "type": "boolean" } }, "required": [ "items" ] }, "BulkRowReport": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "BulkResult": { "type": "object", "properties": { "updated": { "type": "integer" }, "deleted": { "type": "integer" }, "received": { "type": "integer" }, "changed": { "type": "integer" }, "failed": { "type": "integer" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BulkRowReport" } } }, "description": "Prices returns `updated`/`deleted`; inventory `received`/`changed`. `failed` and `rows` only with `partial`." }, "BulkJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "error": { "type": "string" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "updated", "error" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "sku": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Asynchronous bulk creation job. `rows` only on lookup, paginated with `offset`/`limit`." }, "ImportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "error": { "type": "string" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "updated", "error" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "sku": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Asynchronous NDJSON import job (create only). `updated` is always 0." }, "ProductsBulkInput": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "allOf": [ { "$ref": "#/components/schemas/Product" } ], "required": [ "code" ] } } }, "required": [ "items" ] }, "ImportUpload": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "UTF-8 NDJSON, up to 256 MB." } }, "required": [ "file" ] }, "ImageUpload": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPG, PNG, WEBP or GIF, up to 10 MB." }, "alt_text": { "type": "string" }, "external_key": { "type": "string", "maxLength": 100 }, "variant_skus": { "type": "string", "description": "Comma-separated SKUs (or a JSON list)." } } }, "ImageUrl": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500, "description": "https only; stored without downloading." }, "external_key": { "type": "string" }, "alt_text": { "type": "string" }, "variant_skus": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Same on every retry: deduplicate by this value." }, "event": { "type": "string", "enum": [ "order.created", "order.updated", "order.paid", "order.payment_failed", "order.shipped", "order.ready_for_pickup", "order.delivered", "order.cancelled", "order.returned", "order.refunded", "inventory.changed" ] }, "store": { "type": "string", "description": "Store slug." }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "description": "Order (`id`, `number`, statuses, lines, shipping…) or, for `inventory.changed`, `sku`, `product_code`, `product_name` and `available`. `order.refunded` adds `refund`." } }, "required": [ "id", "event", "store", "occurred_at", "data" ], "description": "Body of each delivery." } } } }