{ "openapi": "3.1.0", "info": { "title": "Cartenvo Integration Hub sync API", "version": "1", "description": "The calls an ERP, warehouse or automation tool needs to stay in sync with a nopCommerce store: what changed, orders, products, customers, bulk stock and prices, statuses, shipments, ERP numbers and webhook registration. Keys are made in admin under Configuration → Integration Hub → API keys; each operation's x-scope names the scope it needs. JSON uses camelCase, dates are UTC, and amounts are in the store's primary currency.", "license": { "name": "Cartenvo Integration Hub licence", "url": "https://cartenvo.com/plugins/integration-hub/license" } }, "servers": [ { "url": "https://your-store.example.com/api/cartenvo/v1" } ], "tags": [ { "name": "Keys" }, { "name": "Changes" }, { "name": "Orders" }, { "name": "Catalog" }, { "name": "Customers" }, { "name": "References" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "summary": "The key that is calling", "operationId": "getMe", "tags": [ "Keys" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInfo" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/changes": { "get": { "summary": "What changed since the last call", "operationId": "getChanges", "tags": [ "Changes" ], "description": "Pass the cursor from the previous answer as since. An empty since starts at the beginning; since=latest returns no items and the newest cursor, to start from now. Changes are recorded while any enabled key has changes:read. Changes from the last 2 seconds wait for the next call.", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A cursor, \"latest\", or empty." }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated: order, product, stock, customer. Default all." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesPage" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "changes:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/orders": { "get": { "summary": "List orders, oldest first", "operationId": "listOrders", "tags": [ "Orders" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pending, Processing, Complete or Cancelled." }, { "name": "paymentStatus", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shippingStatus", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "createdSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "paidSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "externalSystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With externalReference: find by a number in another system." }, { "name": "externalReference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "afterId", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The nextAfterId of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/orders/{id}": { "get": { "summary": "Get an order", "operationId": "getOrder", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/orders/{id}/status": { "post": { "summary": "Set the order or payment status", "operationId": "setOrderStatus", "tags": [ "Orders" ], "description": "Through nopCommerce's order processing: Cancelled returns stock; Paid, Refunded (offline, whole order) and Voided follow the payment rules. Shipping status follows shipments. Answers with the order.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The order's state doesn't allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/orders/{id}/shipments": { "post": { "summary": "Add a shipment", "operationId": "addShipment", "tags": [ "Orders" ], "description": "As admin's Add shipment, optionally shipped (or ready for pickup) and delivered at once, with nopCommerce's emails.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Nothing left to ship.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Quantities or warehouses don't fit.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/orders/{id}/notes": { "post": { "summary": "Add an order note", "operationId": "addOrderNote", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderNoteRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderNote" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/shipments/{id}": { "get": { "summary": "Get a shipment", "operationId": "getShipment", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "summary": "Set tracking, or mark shipped or delivered", "operationId": "updateShipment", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentUpdateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not shipped yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "orders:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/products": { "get": { "summary": "List products, oldest first", "operationId": "listProducts", "tags": [ "Catalog" ], "parameters": [ { "name": "sku", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A product's or a combination's SKU." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "includeDeleted", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "externalSystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With externalReference: find by a number in another system." }, { "name": "externalReference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "afterId", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The nextAfterId of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPage" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "catalog:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/products/{id}": { "get": { "summary": "Get a product with its combinations", "operationId": "getProduct", "tags": [ "Catalog" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "catalog:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/stock": { "post": { "summary": "Set stock by SKU, up to 1,000 lines", "operationId": "setStock", "tags": [ "Catalog" ], "description": "Each line is applied on its own and reported. Uses nopCommerce's stock history and back-in-stock emails, as the product page in admin does.", "parameters": [ { "name": "dryRun", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Check and report without changing anything. Same as \"dryRun\": true in the body." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "stock:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/prices": { "post": { "summary": "Set prices, old prices and costs by SKU, up to 1,000 lines", "operationId": "setPrices", "tags": [ "Catalog" ], "parameters": [ { "name": "dryRun", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Check and report without changing anything. Same as \"dryRun\": true in the body." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "prices:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/customers": { "get": { "summary": "List registered customers, oldest first", "operationId": "listCustomers", "tags": [ "Customers" ], "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "createdSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "externalSystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With externalReference: find by a number in another system." }, { "name": "externalReference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "afterId", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The nextAfterId of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPage" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "customers:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/customers/{id}": { "get": { "summary": "Get a customer", "operationId": "getCustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "customers:read", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/webhooks/events": { "get": { "summary": "The events a webhook can receive", "operationId": "listEvents", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventInfo" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "webhooks:manage", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/webhooks/targets": { "get": { "summary": "The webhooks this key registered", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Target" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "webhooks:manage", "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "summary": "Register a webhook", "operationId": "addWebhook", "tags": [ "Webhooks" ], "description": "For Zapier, Make and n8n instant triggers. The answer has the signing secret, once.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Target" } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "webhooks:manage", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/webhooks/targets/{id}": { "delete": { "summary": "Remove a webhook this key registered", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "responses": { "204": { "description": "Removed" }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "webhooks:manage", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/orders/{id}/external-references/{system}": { "put": { "summary": "Save a order's number in another system", "operationId": "setOrderReference", "tags": [ "References" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9._-]{1,40}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "references:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "delete": { "summary": "Remove a order's number in another system", "operationId": "deleteOrderReference", "tags": [ "References" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "system", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "references:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/products/{id}/external-references/{system}": { "put": { "summary": "Save a product's number in another system", "operationId": "setProductReference", "tags": [ "References" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9._-]{1,40}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "references:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "delete": { "summary": "Remove a product's number in another system", "operationId": "deleteProductReference", "tags": [ "References" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "system", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "references:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/customers/{id}/external-references/{system}": { "put": { "summary": "Save a customer's number in another system", "operationId": "setCustomerReference", "tags": [ "References" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9._-]{1,40}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "references:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "delete": { "summary": "Remove a customer's number in another system", "operationId": "deleteCustomerReference", "tags": [ "References" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "system", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any unique string, such as a UUID. A repeat within 24 hours returns the first answer (with Idempotent-Replayed: true) instead of applying it again." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } } }, "400": { "description": "The request isn't valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No API key, or not a valid one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not over HTTPS, not from an allowed address, or the key lacks the scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (or another store's, for a key bound to one store).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many calls: wait for Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-scope": "references:write", "security": [ { "bearer": [] }, { "apiKey": [] } ] } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "Every error, as RFC 9457 problem details (application/problem+json).", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "code": { "type": "string", "description": "unauthorized, forbidden, https_required, ip_not_allowed, not_found, invalid_request, too_many_lines, not_allowed, rate_limited, idempotency_key_reused, idempotency_key_in_progress, server_error" }, "errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Field errors: the field and what is wrong with it." } }, "required": [ "title", "status", "code" ] }, "KeyInfo": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "storeId": { "type": "integer" }, "rateLimitPerMinute": { "type": "integer" }, "apiVersion": { "type": "string" } } }, "ExternalRef": { "type": "object", "properties": { "system": { "type": "string" }, "reference": { "type": "string" }, "updatedOnUtc": { "type": "string", "format": "date-time" } } }, "Address": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "address1": { "type": [ "string", "null" ] }, "address2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "zipPostalCode": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ], "description": "Two-letter ISO code." }, "stateCode": { "type": [ "string", "null" ] }, "stateName": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] }, "faxNumber": { "type": [ "string", "null" ] } } }, "CustomerRef": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] } } }, "OrderTotals": { "type": "object", "properties": { "subtotalInclTax": { "type": "number" }, "subtotalExclTax": { "type": "number" }, "subtotalDiscountInclTax": { "type": "number" }, "subtotalDiscountExclTax": { "type": "number" }, "shippingInclTax": { "type": "number" }, "shippingExclTax": { "type": "number" }, "paymentFeeInclTax": { "type": "number" }, "paymentFeeExclTax": { "type": "number" }, "tax": { "type": "number" }, "discount": { "type": "number" }, "total": { "type": "number" }, "refunded": { "type": "number" } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "integer" }, "guid": { "type": "string", "format": "uuid" }, "productId": { "type": "integer" }, "combinationId": { "type": [ "integer", "null" ] }, "sku": { "type": [ "string", "null" ] }, "gtin": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPriceInclTax": { "type": "number" }, "unitPriceExclTax": { "type": "number" }, "priceInclTax": { "type": "number" }, "priceExclTax": { "type": "number" }, "discountInclTax": { "type": "number" }, "discountExclTax": { "type": "number" }, "attributes": { "type": [ "string", "null" ], "description": "The chosen attributes as plain text, one per line." }, "itemWeight": { "type": [ "number", "null" ] }, "vendorId": { "type": "integer" } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ], "description": "The order number customers see." }, "guid": { "type": "string", "format": "uuid" }, "storeId": { "type": "integer" }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/CustomerRef" }, { "type": "null" } ] }, "status": { "type": [ "string", "null" ], "description": "Pending, Processing, Complete or Cancelled." }, "paymentStatus": { "type": [ "string", "null" ], "description": "Pending, Authorized, Paid, PartiallyRefunded, Refunded or Voided." }, "shippingStatus": { "type": [ "string", "null" ], "description": "ShippingNotRequired, NotYetShipped, PartiallyShipped, Shipped or Delivered." }, "currency": { "type": [ "string", "null" ], "description": "The currency of every amount (the store's primary currency)." }, "customerCurrency": { "type": [ "string", "null" ] }, "customerCurrencyRate": { "type": "number" }, "pricesIncludeTax": { "type": "boolean" }, "totals": { "$ref": "#/components/schemas/OrderTotals" }, "paymentMethod": { "type": [ "string", "null" ] }, "shippingMethod": { "type": [ "string", "null" ] }, "shippingProvider": { "type": [ "string", "null" ] }, "pickupInStore": { "type": "boolean" }, "billingAddress": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "shippingAddress": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "checkoutAttributes": { "type": [ "string", "null" ] }, "vatNumber": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "createdOnUtc": { "type": "string", "format": "date-time" }, "paidOnUtc": { "type": [ "string", "null" ], "format": "date-time" }, "adminUrl": { "type": [ "string", "null" ] }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } }, "ShipmentItem": { "type": "object", "properties": { "id": { "type": "integer" }, "orderItemId": { "type": "integer" }, "productId": { "type": "integer" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "warehouseId": { "type": "integer" } } }, "Shipment": { "type": "object", "properties": { "id": { "type": "integer" }, "orderId": { "type": "integer" }, "orderNumber": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "totalWeight": { "type": [ "number", "null" ] }, "createdOnUtc": { "type": "string", "format": "date-time" }, "shippedOnUtc": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredOnUtc": { "type": [ "string", "null" ], "format": "date-time" }, "readyForPickupOnUtc": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentItem" } }, "adminUrl": { "type": [ "string", "null" ] } } }, "Combination": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": [ "string", "null" ] }, "gtin": { "type": [ "string", "null" ] }, "manufacturerPartNumber": { "type": [ "string", "null" ] }, "stockQuantity": { "type": "integer" }, "price": { "type": [ "number", "null" ], "description": "Set when the combination has its own price." }, "attributes": { "type": [ "string", "null" ] } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "gtin": { "type": [ "string", "null" ] }, "manufacturerPartNumber": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "SimpleProduct or GroupedProduct." }, "parentGroupedProductId": { "type": "integer" }, "published": { "type": "boolean" }, "deleted": { "type": "boolean" }, "price": { "type": "number" }, "oldPrice": { "type": "number" }, "productCost": { "type": "number" }, "stockQuantity": { "type": "integer" }, "manageInventory": { "type": [ "string", "null" ], "description": "DontManageStock, ManageStock or ManageStockByAttributes." }, "weight": { "type": "number" }, "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "vendorId": { "type": "integer" }, "createdOnUtc": { "type": "string", "format": "date-time" }, "updatedOnUtc": { "type": "string", "format": "date-time", "description": "Also the product's version." }, "combinations": { "type": "array", "items": { "$ref": "#/components/schemas/Combination" } }, "adminUrl": { "type": [ "string", "null" ] }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } }, "Customer": { "type": "object", "properties": { "id": { "type": "integer" }, "guid": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "vatNumber": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "storeId": { "type": "integer" }, "createdOnUtc": { "type": "string", "format": "date-time" }, "billingAddress": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "shippingAddress": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "adminUrl": { "type": [ "string", "null" ] }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } }, "OrderPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "nextAfterId": { "type": [ "integer", "null" ], "description": "Pass as afterId for the next page. Null on the last page." } } }, "ProductPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "nextAfterId": { "type": [ "integer", "null" ] } } }, "CustomerPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "nextAfterId": { "type": [ "integer", "null" ] } } }, "ChangeItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order", "product", "stock", "customer" ] }, "id": { "type": "integer" }, "deleted": { "type": "boolean" }, "storeId": { "type": "integer" }, "changedOnUtc": { "type": "string", "format": "date-time" } } }, "ChangesPage": { "type": "object", "description": "Oldest first. Each order, product, stock level or customer appears once, at its latest change.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeItem" } }, "cursor": { "type": "string", "description": "Save it and pass it as since next time." }, "hasMore": { "type": "boolean", "description": "Call again at once with the new cursor." } } }, "OrderStatusRequest": { "type": "object", "properties": { "orderStatus": { "type": "string", "enum": [ "Pending", "Processing", "Complete", "Cancelled" ] }, "paymentStatus": { "type": "string", "enum": [ "Paid", "Refunded", "Voided" ] }, "notifyCustomer": { "type": "boolean", "default": false } } }, "ShipmentLine": { "type": "object", "properties": { "orderItemId": { "type": "integer" }, "sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "warehouseId": { "type": "integer", "description": "Only for products stocked in several warehouses." } }, "required": [ "quantity" ] }, "ShipmentRequest": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentLine" }, "description": "Leave out to ship everything not yet in a shipment." }, "trackingNumber": { "type": "string" }, "adminComment": { "type": "string" }, "ship": { "type": "boolean", "default": false }, "deliver": { "type": "boolean", "default": false }, "notifyCustomer": { "type": "boolean", "default": true } } }, "ShipmentUpdateRequest": { "type": "object", "properties": { "trackingNumber": { "type": "string" }, "ship": { "type": "boolean" }, "deliver": { "type": "boolean" }, "notifyCustomer": { "type": "boolean", "default": true } } }, "OrderNoteRequest": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 4000 }, "displayToCustomer": { "type": "boolean", "default": false } }, "required": [ "note" ] }, "OrderNote": { "type": "object", "properties": { "id": { "type": "integer" }, "orderId": { "type": "integer" }, "note": { "type": "string" }, "displayToCustomer": { "type": "boolean" }, "createdOnUtc": { "type": "string", "format": "date-time" } } }, "ExternalReferenceRequest": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 200 } }, "required": [ "reference" ] }, "StockLine": { "type": "object", "properties": { "sku": { "type": "string" }, "productId": { "type": "integer" }, "combinationId": { "type": "integer" }, "warehouseId": { "type": "integer" }, "quantity": { "type": "integer", "description": "The new stock. Give this or adjustment." }, "adjustment": { "type": "integer", "description": "Added to (or, when negative, taken from) the stock." } } }, "StockRequest": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StockLine" }, "maxItems": 1000 }, "dryRun": { "type": "boolean", "default": false }, "reason": { "type": "string", "description": "Kept in nopCommerce's stock history. Default \"Integration Hub API\"." } }, "required": [ "lines" ] }, "PriceLine": { "type": "object", "properties": { "sku": { "type": "string" }, "productId": { "type": "integer" }, "combinationId": { "type": "integer" }, "price": { "type": "number", "minimum": 0 }, "oldPrice": { "type": "number", "minimum": 0, "description": "Products only." }, "productCost": { "type": "number", "minimum": 0, "description": "Products only." } } }, "PriceRequest": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PriceLine" }, "maxItems": 1000 }, "dryRun": { "type": "boolean", "default": false } }, "required": [ "lines" ] }, "PriceChange": { "type": "object", "properties": { "from": { "type": [ "number", "null" ] }, "to": { "type": [ "number", "null" ] } } }, "LineResult": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "updated", "unchanged", "failed" ] }, "sku": { "type": [ "string", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "combinationId": { "type": [ "integer", "null" ] }, "warehouseId": { "type": [ "integer", "null" ] }, "oldQuantity": { "type": "integer" }, "newQuantity": { "type": "integer" }, "changes": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PriceChange" } }, "error": { "type": "string", "description": "not_found, ambiguous, stock_not_tracked, use_combination_sku, warehouse_needed, warehouse_unknown, invalid, server_error" }, "message": { "type": "string" } } }, "BulkResult": { "type": "object", "description": "One result per line, in the request's order. In a dry run, \"updated\" means it would be.", "properties": { "dryRun": { "type": "boolean" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "failed": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/LineResult" } } } }, "EventInfo": { "type": "object", "properties": { "type": { "type": "string" }, "group": { "type": "string" }, "data": { "type": "string" } } }, "TargetRequest": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "https:// only." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event names, or [\"*\"] for all." }, "format": { "type": "string", "enum": [ "full", "thin" ], "default": "full" } }, "required": [ "url", "events" ] }, "Target": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "format": { "type": "string", "enum": [ "full", "thin" ] }, "enabled": { "type": "boolean" }, "storeId": { "type": "integer" }, "createdOnUtc": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "The signing secret. Only in the answer that created the webhook." } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer cih_…" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } }