{ "openapi": "3.1.0", "info": { "title": "ecommerce.sa Storefront API", "version": "1.0.0", "description": "Storefront (tenant-scoped, public) and merchant admin (Bearer token) endpoints. Money is in integer minor units (halalas). Errors are `{error: string}`. \n\n**Versioning.** Every response carries `X-API-Version: 1`. Clients may pin a version with `X-API-Version: 1` or `Accept: application/vnd.ecommerce.v1+json`; an unknown version is refused with 406 `{error: unsupported_version}`. The `/api/v1` prefix is reserved for a future breaking release and is not an alias of these paths. `Deprecation` / `Sunset` headers announce a retirement date when one is set.\n\n**Rate limits & quotas.** Bearer calls are limited per token by the tenant plan (`api-token` limiter); storefront calls per tenant + IP (`api-public`). Responses carry `X-RateLimit-Limit` / `X-RateLimit-Remaining`; 429 `{error: rate_limited, retry_after}` when exceeded. Token calls also carry `X-Quota-Limit` / `X-Quota-Used` / `X-Quota-Remaining` / `X-Quota-Reset` for the monthly plan quota; `{error: quota_exceeded}` when spent. Usage is metered per call (see GET /admin/usage).", "x-api-version": "1", "x-supported-versions": [ "1" ], "x-rate-limits": { "plans": { "default": 60, "public": 120, "start": 60, "grow": 120, "market": 600, "enterprise": 1200 }, "quotas": { "default": 10000, "start": 10000, "grow": 100000, "market": 1000000, "enterprise": null }, "unit": "requests per minute; quotas are calls per calendar month" } }, "servers": [ { "url": "http://localhost/api" } ], "paths": { "/admin/analytics": { "get": { "operationId": "api.admin.analytics.index", "summary": "Which metrics, granularities, dimensions and comparisons exist", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "analytics.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsCatalogue" } } } } } } }, "/admin/analytics/kpis": { "get": { "operationId": "get_admin_analytics_kpis", "summary": "GET /admin/analytics/kpis — AnalyticsController::kpis", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "analytics.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/analytics/{metric}": { "get": { "operationId": "api.admin.analytics.show", "summary": "A warehouse metric over a date range, optionally bucketed and compared", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "analytics.read" ] } ], "parameters": [ { "name": "metric", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start date (YYYY-MM-DD). Default: 29 days before `to`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end date (YYYY-MM-DD). Default: today.", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Bucket size", "schema": { "type": "string", "enum": [ "day", "week", "month", "total" ], "default": "day" } }, { "name": "dimension", "in": "query", "required": false, "description": "Adds a `breakdown[]`", "schema": { "type": "string", "enum": [ "none", "category", "city", "product", "channel" ], "default": "none" } }, { "name": "compare", "in": "query", "required": false, "description": "Adds a `comparison{}`", "schema": { "type": "string", "enum": [ "none", "previous_period", "previous_year" ], "default": "none" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsReport" } } } }, "404": { "description": "unknown_metric — the body lists every metric there is", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_granularity, unknown_dimension, range_too_wide_for_granularity, from_after_to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Metrics: revenue, orders, units, returns, margin. Read from `fact_order_line` joined to `dim_date`. **Maximum granularity is `day`** — the warehouse stores one row per calendar day, so hour-of-day cannot be answered and is refused rather than rounded. `returns` is derived from order lines whose order reached returned/refunded; there is no separate returns fact. `margin` is `null` for any bucket containing a line with no known cost." } }, "/admin/bulk/customers": { "post": { "operationId": "api.admin.bulk.customers.apply", "summary": "Apply up to 100 customers operations in one request", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "customers.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the first response for this envelope instead of applying it again.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every operation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "207": { "description": "Partial success — read `results[]` for the per-operation outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "409": { "description": "idempotency_key_reused — the same key arrived with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Each operation is validated by the SAME rules as the single-item path and applied in its own transaction, so a failure does not roll back the operations that succeeded. Answers **207 Multi-Status** when any operation failed and 200 when none did. Supported actions: create, update, delete.\n\nSend `Idempotency-Key` to make a retry of the whole envelope replay the first response; give an individual operation a `key` to make that one operation replayable on its own.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } } } } } }, "/admin/bulk/customers/jobs": { "post": { "operationId": "api.admin.bulk.customers.jobs.create", "summary": "Queue up to 10000 customers operations as a background job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "customers.write" ] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The work runs on the queue in chunks so progress is readable while it runs. Returns 202 and a job id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobRequest" } } } } } }, "/admin/bulk/customers/jobs/{id}": { "get": { "operationId": "api.admin.bulk.customers.jobs.show", "summary": "Progress and counts for a customers bulk job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/bulk/customers/jobs/{id}/errors": { "get": { "operationId": "api.admin.bulk.customers.jobs.errors", "summary": "Downloadable error report for a customers bulk job, keyed by row", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkErrorReport" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`row` is the caller's own operation index, so a failure can be matched back to the line that caused it." } }, "/admin/bulk/inventory": { "post": { "operationId": "api.admin.bulk.inventory.apply", "summary": "Apply up to 100 inventory operations in one request", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the first response for this envelope instead of applying it again.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every operation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "207": { "description": "Partial success — read `results[]` for the per-operation outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "409": { "description": "idempotency_key_reused — the same key arrived with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Each operation is validated by the SAME rules as the single-item path and applied in its own transaction, so a failure does not roll back the operations that succeeded. Answers **207 Multi-Status** when any operation failed and 200 when none did. Supported actions: create, update, delete.\n\nSend `Idempotency-Key` to make a retry of the whole envelope replay the first response; give an individual operation a `key` to make that one operation replayable on its own.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } } } } } }, "/admin/bulk/inventory/jobs": { "post": { "operationId": "api.admin.bulk.inventory.jobs.create", "summary": "Queue up to 10000 inventory operations as a background job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The work runs on the queue in chunks so progress is readable while it runs. Returns 202 and a job id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobRequest" } } } } } }, "/admin/bulk/inventory/jobs/{id}": { "get": { "operationId": "api.admin.bulk.inventory.jobs.show", "summary": "Progress and counts for a inventory bulk job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/bulk/inventory/jobs/{id}/errors": { "get": { "operationId": "api.admin.bulk.inventory.jobs.errors", "summary": "Downloadable error report for a inventory bulk job, keyed by row", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkErrorReport" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`row` is the caller's own operation index, so a failure can be matched back to the line that caused it." } }, "/admin/bulk/orders": { "post": { "operationId": "api.admin.bulk.orders.apply", "summary": "Apply up to 100 orders operations in one request", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "orders.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the first response for this envelope instead of applying it again.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every operation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "207": { "description": "Partial success — read `results[]` for the per-operation outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "409": { "description": "idempotency_key_reused — the same key arrived with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Each operation is validated by the SAME rules as the single-item path and applied in its own transaction, so a failure does not roll back the operations that succeeded. Answers **207 Multi-Status** when any operation failed and 200 when none did. Supported actions: update. Refused for this resource: create (orders_create_unsupported), delete (orders_delete_unsupported).\n\nSend `Idempotency-Key` to make a retry of the whole envelope replay the first response; give an individual operation a `key` to make that one operation replayable on its own.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } } } } } }, "/admin/bulk/orders/jobs": { "post": { "operationId": "api.admin.bulk.orders.jobs.create", "summary": "Queue up to 10000 orders operations as a background job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "orders.write" ] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The work runs on the queue in chunks so progress is readable while it runs. Returns 202 and a job id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobRequest" } } } } } }, "/admin/bulk/orders/jobs/{id}": { "get": { "operationId": "api.admin.bulk.orders.jobs.show", "summary": "Progress and counts for a orders bulk job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "orders.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/bulk/orders/jobs/{id}/errors": { "get": { "operationId": "api.admin.bulk.orders.jobs.errors", "summary": "Downloadable error report for a orders bulk job, keyed by row", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "orders.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkErrorReport" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`row` is the caller's own operation index, so a failure can be matched back to the line that caused it." } }, "/admin/bulk/prices": { "post": { "operationId": "api.admin.bulk.prices.apply", "summary": "Apply up to 100 prices operations in one request", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the first response for this envelope instead of applying it again.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every operation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "207": { "description": "Partial success — read `results[]` for the per-operation outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "409": { "description": "idempotency_key_reused — the same key arrived with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Each operation is validated by the SAME rules as the single-item path and applied in its own transaction, so a failure does not roll back the operations that succeeded. Answers **207 Multi-Status** when any operation failed and 200 when none did. Supported actions: create, update, delete.\n\nSend `Idempotency-Key` to make a retry of the whole envelope replay the first response; give an individual operation a `key` to make that one operation replayable on its own.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } } } } } }, "/admin/bulk/prices/jobs": { "post": { "operationId": "api.admin.bulk.prices.jobs.create", "summary": "Queue up to 10000 prices operations as a background job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The work runs on the queue in chunks so progress is readable while it runs. Returns 202 and a job id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobRequest" } } } } } }, "/admin/bulk/prices/jobs/{id}": { "get": { "operationId": "api.admin.bulk.prices.jobs.show", "summary": "Progress and counts for a prices bulk job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/bulk/prices/jobs/{id}/errors": { "get": { "operationId": "api.admin.bulk.prices.jobs.errors", "summary": "Downloadable error report for a prices bulk job, keyed by row", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkErrorReport" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`row` is the caller's own operation index, so a failure can be matched back to the line that caused it." } }, "/admin/bulk/products": { "post": { "operationId": "api.admin.bulk.products.apply", "summary": "Apply up to 100 products operations in one request", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the first response for this envelope instead of applying it again.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every operation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "207": { "description": "Partial success — read `results[]` for the per-operation outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "409": { "description": "idempotency_key_reused — the same key arrived with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Each operation is validated by the SAME rules as the single-item path and applied in its own transaction, so a failure does not roll back the operations that succeeded. Answers **207 Multi-Status** when any operation failed and 200 when none did. Supported actions: create, update, delete.\n\nSend `Idempotency-Key` to make a retry of the whole envelope replay the first response; give an individual operation a `key` to make that one operation replayable on its own.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } } } } } }, "/admin/bulk/products/jobs": { "post": { "operationId": "api.admin.bulk.products.jobs.create", "summary": "Queue up to 10000 products operations as a background job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The work runs on the queue in chunks so progress is readable while it runs. Returns 202 and a job id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobRequest" } } } } } }, "/admin/bulk/products/jobs/{id}": { "get": { "operationId": "api.admin.bulk.products.jobs.show", "summary": "Progress and counts for a products bulk job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/bulk/products/jobs/{id}/errors": { "get": { "operationId": "api.admin.bulk.products.jobs.errors", "summary": "Downloadable error report for a products bulk job, keyed by row", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkErrorReport" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`row` is the caller's own operation index, so a failure can be matched back to the line that caused it." } }, "/admin/bulk/variants": { "post": { "operationId": "api.admin.bulk.variants.apply", "summary": "Apply up to 100 variants operations in one request", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the first response for this envelope instead of applying it again.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every operation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "207": { "description": "Partial success — read `results[]` for the per-operation outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "409": { "description": "idempotency_key_reused — the same key arrived with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Each operation is validated by the SAME rules as the single-item path and applied in its own transaction, so a failure does not roll back the operations that succeeded. Answers **207 Multi-Status** when any operation failed and 200 when none did. Supported actions: create, update, delete.\n\nSend `Idempotency-Key` to make a retry of the whole envelope replay the first response; give an individual operation a `key` to make that one operation replayable on its own.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequest" } } } } } }, "/admin/bulk/variants/jobs": { "post": { "operationId": "api.admin.bulk.variants.jobs.create", "summary": "Queue up to 10000 variants operations as a background job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "422": { "description": "operations_required, too_many_operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The work runs on the queue in chunks so progress is readable while it runs. Returns 202 and a job id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobRequest" } } } } } }, "/admin/bulk/variants/jobs/{id}": { "get": { "operationId": "api.admin.bulk.variants.jobs.show", "summary": "Progress and counts for a variants bulk job", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/bulk/variants/jobs/{id}/errors": { "get": { "operationId": "api.admin.bulk.variants.jobs.errors", "summary": "Downloadable error report for a variants bulk job, keyed by row", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkErrorReport" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`row` is the caller's own operation index, so a failure can be matched back to the line that caused it." } }, "/admin/customers": { "get": { "operationId": "get_admin_customers", "summary": "GET /admin/customers", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/events": { "get": { "operationId": "api.admin.events.index", "summary": "Read this store's events, cursor-paginated (the pull-based Event API)", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "events.read" ] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Cursor: return events written after this id", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Only this event type", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } } } } }, "description": "Reads the transactional outbox (`outbox_messages`) — the same rows the relay publishes, so the API cannot disagree with what the system did. Paging is by cursor, not offset: pass `meta.next_cursor` back as `since` and no event is skipped or repeated when new events arrive mid-page." } }, "/admin/events/stream": { "get": { "operationId": "api.admin.events.stream", "summary": "Server-Sent Events stream of this store's events", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "events.read" ] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Resume cursor (an event id)", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Only this event type", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "Presentation", "schema": { "type": "string", "enum": [ "api", "dashboard" ], "default": "api" } }, { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Resume cursor replayed automatically by EventSource.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`text/event-stream` — frames: hello, , heartbeat, eof" } }, "x-rate-limit": { "requests": 12, "per_minutes": 1 }, "description": "**This is SSE, not WebSockets, and that is a deployment fact rather than a preference.** A WebSocket API needs a server that holds connections (Reverb, Soketi, Pusher) and a broker; this platform runs on PHP-FPM with `BROADCAST_CONNECTION=null` and has neither. SSE is a plain HTTP response this stack really serves.\n\n**Reconnect contract.** Every frame carries `id:` (the cursor). The server closes the connection deliberately after `max_duration_seconds` with a final `event: eof` carrying `cursor` — a long-lived request holds a PHP worker, so the cap is what stops the stream being a resource leak. Reconnect with `?since=`, or let `EventSource` reconnect and replay `Last-Event-ID`; both are honoured. `retry:` tells the browser how long to wait. A quiet stream emits `event: heartbeat` so a client can tell a calm stream from a dead one.\n\n`?channel=dashboard` is the merchant dashboard's realtime channel — the same controller and the same cursor, not a second mechanism." } }, "/admin/events/types": { "get": { "operationId": "api.admin.events.types", "summary": "Event types this store has actually produced", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "events.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/admin/exports": { "post": { "operationId": "api.admin.exports.store", "summary": "Export an entity and get a signed, expiring download link", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResult" } } } }, "422": { "description": "unsupported_entity, unsupported_format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Formats: csv, json, ndjson. The link expires after 15 minutes and its signature covers both the job id and the tenant, so it can neither be edited into another store's export nor survive its expiry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } } } }, "/admin/exports/{job}": { "get": { "operationId": "api.admin.exports.show", "summary": "An export job, with a freshly signed link while it is complete", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "job", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResult" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/exports/{job}/download": { "get": { "operationId": "api.admin.exports.download", "summary": "Download an export (signed link, no token)", "tags": [ "Merchant admin" ], "security": [], "parameters": [ { "name": "job", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "required": false, "description": "Part of the signature — must be the job's own tenant", "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "description": "Signature expiry (added by the signer)", "schema": { "type": "integer" } }, { "name": "signature", "in": "query", "required": false, "description": "HMAC of the URL (added by the signer)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The export file" }, "403": { "description": "Invalid or expired signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "export_not_ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 30, "per_minutes": 1 }, "description": "Carries no Bearer token: the signature is the authority. An expired or edited link is refused by the `signed` middleware; a valid signature over another store's job is refused by the handler." } }, "/admin/graphql": { "post": { "operationId": "post_admin_graphql", "summary": "POST /admin/graphql — GraphQLController::query", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/imports": { "post": { "operationId": "api.admin.imports.store", "summary": "Import rows, or dry-run them and see what would change", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [], "responses": { "200": { "description": "Dry run — nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDryRun" } } } }, "201": { "description": "Imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "422": { "description": "unsupported_format, source_url_blocked, invalid_json, invalid_xml, no_source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Formats: csv, json, xml, ndjson, xlsx. `.xlsx` is parsed by the repository's own pure-PHP OOXML reader and needs PHP's `zip` extension; legacy `.xls` is not supported. Rows arrive inline (`data` or `rows`) or from `url` — a URL is fetched only after the SSRF guard clears it. `dry_run: true` writes nothing and returns the per-row create/update/error diff.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRequest" } } } } } }, "/admin/imports/capabilities": { "get": { "operationId": "api.admin.imports.capabilities", "summary": "Which import formats and connectors work here, and why the others do not", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCapabilities" } } } } }, "description": "The live availability map. Unavailable entries carry a machine-readable reason (`needs_aws_sdk_and_iam_credentials`, `php_zip_extension_missing_export_csv_instead`, …) rather than being absent." } }, "/admin/imports/{job}": { "get": { "operationId": "api.admin.imports.show", "summary": "An import job with its error report", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [ { "name": "job", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "404": { "description": "No such job in this store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/integrations/{key}/run": { "post": { "operationId": "api.admin.integrations.run", "summary": "POST /admin/integrations/{key}/run — IntegrationApiController::run", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "integrations.run" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 60, "per_minutes": 1 } } }, "/admin/me": { "get": { "operationId": "get_admin_me", "summary": "GET /admin/me", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/notifications/channels": { "get": { "operationId": "api.admin.notifications.channels", "summary": "Outbound alert channels and whether each one can actually deliver", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "notifications.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelList" } } } } }, "description": "Channels: slack, discord, teams, webhook, email, pagerduty, opsgenie, telegram, voice. Every entry carries `available` and, when false, a reason — `not_configured`, `no_credential`, `no_target`, `disabled`, `mailer_not_configured`, or `needs_paid_telephony_and_tts_provider` for voice, which no credential can fix. Stored credentials are never returned; `credential_masked` is." } }, "/admin/notifications/channels/{key}": { "put": { "operationId": "api.admin.notifications.channels.update", "summary": "Configure one channel (paste the webhook URL, integration key or bot token)", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "notifications.write" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelState" } } } }, "404": { "description": "unknown_channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "channel_unavailable — no credential can make this channel real here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConfig" } } } } } }, "/admin/notifications/channels/{key}/test": { "post": { "operationId": "api.admin.notifications.channels.test", "summary": "Send a test message down one channel", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "notifications.write" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Attempted — read `delivery.status`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDelivery" } } } }, "422": { "description": "Channel unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDelivery" } } } }, "404": { "description": "unknown_channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Goes through the same path as a real alert, including the SSRF guard and the per-channel throttle, and writes the same delivery row. Answers 422 when the channel is unavailable, so a merchant pressing the button on an unconfigured channel is told, rather than watching nothing happen." } }, "/admin/notifications/deliveries": { "get": { "operationId": "api.admin.notifications.deliveries", "summary": "The delivery log, including the attempts that never left the building", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "notifications.read" ] } ], "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Filter by channel key", "schema": { "type": "string", "enum": [ "slack", "discord", "teams", "webhook", "email", "pagerduty", "opsgenie", "telegram", "voice" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by outcome", "schema": { "type": "string", "enum": [ "delivered", "failed", "pending", "blocked", "unavailable", "throttled" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Rows", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDeliveryList" } } } } } } }, "/admin/orders": { "get": { "operationId": "get_admin_orders", "summary": "GET /admin/orders — OrderController::index", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "orders.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}": { "get": { "operationId": "get_admin_orders_id_", "summary": "GET /admin/orders/{id} — OrderController::show", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "orders.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/payments/tuwaiq/logs": { "get": { "operationId": "get_admin_payments_tuwaiq_logs", "summary": "GET /admin/payments/tuwaiq/logs — TuwaiqController::logs", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "payments.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/payments/tuwaiq/refund": { "post": { "operationId": "post_admin_payments_tuwaiq_refund", "summary": "POST /admin/payments/tuwaiq/refund — TuwaiqController::refund", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "payments.refund" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/plugins": { "get": { "operationId": "api.admin.plugins", "summary": "GET /admin/plugins — PluginCatalogApiController::index", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "plugins.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/products": { "get": { "operationId": "get_admin_products", "summary": "GET /admin/products — ProductController::index", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.read" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_admin_products", "summary": "POST /admin/products — ProductController::store", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "catalog.write" ] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/search": { "get": { "operationId": "api.admin.search", "summary": "Search the store, keyword or semantic, and be told which path answered", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [ "search.read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "The query. Shorter than 2 characters returns an empty result with `reason: query_too_short`.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "Retrieval path", "schema": { "type": "string", "enum": [ "keyword", "semantic", "auto" ], "default": "auto" } }, { "name": "resource", "in": "query", "required": false, "description": "Restrict to one resource", "schema": { "type": "string", "enum": [ "all", "products", "orders", "customers", "invoices", "messages" ], "default": "all" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "422": { "description": "unknown_mode, unknown_resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Every response carries `answered_by`: `keyword:database`, `keyword:meilisearch`, `semantic:index`, `semantic:scan` or `unavailable`. `mode=auto` prefers the semantic path and falls back to keyword when the store has no product embeddings; `mode=semantic` reports `unavailable` with a reason rather than silently degrading. Semantic retrieval covers products only — they are the only entity that is embedded." } }, "/admin/usage": { "get": { "operationId": "api.admin.usage", "summary": "GET /admin/usage — DeveloperUsageController::api", "tags": [ "Merchant admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assistant": { "post": { "operationId": "post_assistant", "summary": "POST /assistant — AssistantController::ask", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 60, "per_minutes": 1 } } }, "/cart": { "post": { "operationId": "api.headless.cart.create", "summary": "Create a cart; the returned token is its only identity", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartCreated" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 } } } } } } } }, "/cart/{token}": { "get": { "operationId": "api.headless.cart.show", "summary": "Read a cart (lines re-priced from the catalog)", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartEnvelope" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/cart/{token}/checkout": { "post": { "operationId": "api.headless.cart.checkout", "summary": "Place the order from the cart and start payment; marks the cart converted", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 }, "description": "Runs the same pipeline as POST /checkout (server re-pricing, checkout policy, Checkout Trust, idempotent placement). Send an Idempotency-Key header to make retries safe; without one the cart id is used.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartCheckout" } } } } } }, "/cart/{token}/coupon": { "post": { "operationId": "api.headless.cart.coupon.apply", "summary": "Apply a coupon (validated by the same CouponService as the web checkout)", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartEnvelope" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartCoupon" } } } } }, "delete": { "operationId": "api.headless.cart.coupon.remove", "summary": "Remove the coupon", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartEnvelope" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/cart/{token}/items": { "post": { "operationId": "api.headless.cart.items.add", "summary": "Add a variant (merges into an existing line)", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartEnvelope" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartAddItem" } } } } } }, "/cart/{token}/items/{variant_id}": { "patch": { "operationId": "api.headless.cart.items.update", "summary": "Set a line quantity (0 removes it)", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartEnvelope" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartSetQuantity" } } } } }, "delete": { "operationId": "api.headless.cart.items.remove", "summary": "Remove a line", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartEnvelope" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/cart/{token}/quote": { "get": { "operationId": "api.headless.cart.quote", "summary": "Totals the order would carry now: subtotal, discount, shipping, tax, total", "tags": [ "Cart" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Echoed back; shipping is a flat merchant rate today", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO-2, echoed back", "schema": { "type": "string" } }, { "name": "method", "in": "query", "required": false, "description": "Payment method, echoed back", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "404": { "description": "Unknown token (including tokens issued by another store)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already converted to an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Cart expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refused (unknown_variant, insufficient_stock, coupon_invalid, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/categories": { "get": { "operationId": "api.headless.categories", "summary": "Categories (flat list + tree) with active product counts", "tags": [ "Catalog" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/checkout": { "post": { "operationId": "post_checkout", "summary": "Place an order from explicit lines (legacy, cart-less)", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "201": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "422": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } } } } }, "/data/session-signals": { "post": { "operationId": "data.session.signals", "summary": "POST /data/session-signals — SessionSignalsController::ingest", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/data/tracking-consent": { "post": { "operationId": "data.tracking.consent", "summary": "POST /data/tracking-consent — SessionSignalsController::consent", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/data/tracking-notice": { "get": { "operationId": "data.tracking.notice", "summary": "GET /data/tracking-notice — SessionSignalsController::notice", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/delivery/track/{token}": { "get": { "operationId": "api.delivery.feed", "summary": "GET /delivery/track/{token} — DeliveryTrackingController::liveFeed", "tags": [ "Delivery" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/delivery/{token}/complete": { "post": { "operationId": "api.delivery.complete", "summary": "POST /delivery/{token}/complete — DeliveryTrackingController::complete", "tags": [ "Delivery" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/delivery/{token}/ping": { "post": { "operationId": "api.delivery.ping", "summary": "POST /delivery/{token}/ping — DeliveryTrackingController::ping", "tags": [ "Delivery" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/devices/register": { "post": { "operationId": "post_devices_register", "summary": "POST /devices/register — DeviceController::register", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/docs": { "get": { "operationId": "api.headless.docs", "summary": "HTML rendering of this document", "tags": [ "Docs" ], "security": [], "parameters": [], "responses": { "200": { "description": "HTML" } }, "x-public": true } }, "/flows/{flow}/trigger": { "post": { "operationId": "api.flows.trigger", "summary": "POST /flows/{flow}/trigger — FlowTriggerController::trigger", "tags": [ "Storefront" ], "security": [], "parameters": [ { "name": "flow", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 60, "per_minutes": 1 } } }, "/me": { "get": { "operationId": "get_me", "summary": "GET /me", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/metadata": { "get": { "operationId": "api.oauth.metadata", "summary": "Endpoints, supported grants, and the grants this server refuses", "tags": [ "Storefront" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthMetadata" } } } } }, "x-public": true, "x-rate-limit": { "requests": 60, "per_minutes": 1 } } }, "/oauth/revoke": { "post": { "operationId": "api.oauth.revoke", "summary": "Revoke an access or refresh token (RFC 7009)", "tags": [ "Storefront" ], "security": [], "parameters": [], "responses": { "200": { "description": "`{revoked: true}` — unconditionally" } }, "x-public": true, "x-rate-limit": { "requests": 60, "per_minutes": 1 }, "description": "Always answers 200, whether or not the token existed: telling a caller that a token is unknown is an oracle. Revoking an access token deletes the credential row, so the very next call is 401 — not \"revoked but still working until it expires\".", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ] } } } } } } } }, "/oauth/token": { "post": { "operationId": "api.oauth.token", "summary": "Exchange an authorization code, or refresh an access token", "tags": [ "Storefront" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "invalid_grant, invalid_request, unsupported_grant_type, redirect_uri_mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "401": { "description": "invalid_client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } }, "x-public": true, "x-rate-limit": { "requests": 20, "per_minutes": 1 }, "description": "Grants supported: authorization_code, refresh_token.\n\n**Grants deliberately refused**, with the reason rather than silence: `implicit` (implicit_grant_removed_token_would_leak_in_url); `password` (password_grant_removed_third_parties_must_not_see_merchant_credentials); `client_credentials` (use_a_merchant_api_token_issued_from_the_dashboard).\n\nPKCE `S256` is required of every client, public or confidential — a confidential client with a leaked secret is a public client that does not know it yet. The `plain` challenge method is refused because it proves nothing an eavesdropper on the redirect could not replay. Codes are single-use and short-lived; replaying one revokes every token it produced. Refreshing rotates: the presented refresh token and its access token both die.\n\nThe issued access token is an ordinary merchant API token whose abilities are the granted scopes, so it is authorised by the same `ability:` checks as every other token.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } } } } } }, "/openapi.json": { "get": { "operationId": "api.headless.openapi", "summary": "This document", "tags": [ "Docs" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OpenAPI 3.1 JSON" } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/orders": { "get": { "operationId": "get_orders", "summary": "GET /orders — TrackController::orders", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 20, "per_minutes": 1 } } }, "/orders/access/request": { "post": { "operationId": "post_orders_access_request", "summary": "POST /orders/access/request — TrackController::requestOrdersAccess", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 6, "per_minutes": 1 } } }, "/orders/access/verify": { "post": { "operationId": "post_orders_access_verify", "summary": "POST /orders/access/verify — TrackController::verifyOrdersAccess", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 20, "per_minutes": 1 } } }, "/payments/moyasar/confirm": { "post": { "operationId": "post_payments_moyasar_confirm", "summary": "POST /payments/moyasar/confirm — MoyasarController::confirm", "tags": [ "Payments" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 } } }, "/payments/moyasar/invoice": { "post": { "operationId": "post_payments_moyasar_invoice", "summary": "POST /payments/moyasar/invoice — MoyasarController::invoice", "tags": [ "Payments" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 } } }, "/payments/stripe/confirm": { "post": { "operationId": "post_payments_stripe_confirm", "summary": "POST /payments/stripe/confirm — StripeController::confirm", "tags": [ "Payments" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 } } }, "/payments/stripe/intent": { "post": { "operationId": "post_payments_stripe_intent", "summary": "POST /payments/stripe/intent — StripeController::intent", "tags": [ "Payments" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 } } }, "/payments/tuwaiq/confirm": { "post": { "operationId": "post_payments_tuwaiq_confirm", "summary": "POST /payments/tuwaiq/confirm — TuwaiqController::confirm", "tags": [ "Payments" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 } } }, "/payments/tuwaiq/invoice": { "post": { "operationId": "post_payments_tuwaiq_invoice", "summary": "POST /payments/tuwaiq/invoice — TuwaiqController::invoice", "tags": [ "Payments" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 30, "per_minutes": 1 } } }, "/payments/webhook/{gateway}": { "post": { "operationId": "post_payments_webhook_gateway_", "summary": "POST /payments/webhook/{gateway} — WebhookController", "tags": [ "Payments" ], "security": [], "parameters": [ { "name": "gateway", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } }, "/products": { "get": { "operationId": "api.headless.products", "summary": "List products (paginated, filterable, with facets)", "tags": [ "Catalog" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search in name/description", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Category slug or id (includes direct children)", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Brand slug or id", "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum variant price, minor units", "schema": { "type": "integer" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum variant price, minor units", "schema": { "type": "integer" } }, { "name": "in_stock", "in": "query", "required": false, "description": "1 = only products with sellable stock (untracked variants count as in stock)", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": [ "newest", "price_asc", "price_desc", "name" ], "default": "newest" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/products/{slug}": { "get": { "operationId": "api.headless.product", "summary": "Product detail with variants, availability, images and related products", "tags": [ "Catalog" ], "security": [ { "tenant": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailEnvelope" } } } }, "404": { "description": "Unknown slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 120, "per_minutes": 1 } } }, "/track": { "get": { "operationId": "get_track", "summary": "GET /track — TrackController::track", "tags": [ "Storefront" ], "security": [ { "tenant": [] } ], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": { "requests": 20, "per_minutes": 1 } } }, "/webhooks/in/{tenant}/{provider}": { "post": { "operationId": "post_webhooks_in_tenant_provider_", "summary": "POST /webhooks/in/{tenant}/{provider} — InboundWebhookController::receive", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } }, "/webhooks/moyasar": { "post": { "operationId": "platform.moyasar.webhook", "summary": "POST /webhooks/moyasar — PlatformMoyasarWebhookController::webhook", "tags": [ "Webhooks" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } }, "/webhooks/moyasar/invoice/{payment}": { "post": { "operationId": "platform.moyasar.invoice_callback", "summary": "POST /webhooks/moyasar/invoice/{payment} — PlatformMoyasarWebhookController::invoice", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } }, "/webhooks/twilio/inbound": { "post": { "operationId": "post_webhooks_twilio_inbound", "summary": "POST /webhooks/twilio/inbound — TwilioWebhookController::inbound", "tags": [ "Webhooks" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } }, "/webhooks/twilio/status": { "post": { "operationId": "post_webhooks_twilio_status", "summary": "POST /webhooks/twilio/status — TwilioWebhookController::status", "tags": [ "Webhooks" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } }, "/whatsapp/webhook": { "get": { "operationId": "get_whatsapp_webhook", "summary": "GET /whatsapp/webhook — WhatsAppWebhookController::verify", "tags": [ "Webhooks" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } }, "post": { "operationId": "post_whatsapp_webhook", "summary": "POST /whatsapp/webhook — WhatsAppWebhookController::receive", "tags": [ "Webhooks" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK" }, "422": { "description": "Validation or business refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-public": true, "x-rate-limit": { "requests": 240, "per_minutes": 1 } } } }, "components": { "securitySchemes": { "tenant": { "type": "apiKey", "in": "header", "name": "X-Tenant", "description": "Store slug. Resolved from the request host in production (custom domain or {slug}.platform); the header / ?tenant= form is for development and headless clients where enabled." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Merchant API token. Scopes listed per operation are the token abilities the route requires." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "available": { "type": "integer", "description": "Present on insufficient_stock" }, "reason": { "type": "string", "description": "Present on coupon refusals" }, "order_id": { "type": [ "string", "null" ], "description": "Present on cart_converted" } } }, "Meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } }, "Facets": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "count": { "type": "integer" } } } }, "brands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "count": { "type": "integer" } } } }, "price": { "type": "object", "properties": { "min": { "type": [ "integer", "null" ] }, "max": { "type": [ "integer", "null" ] } } }, "in_stock_count": { "type": "integer" } } }, "ProductCard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "price": { "type": "integer", "description": "Minor units (halalas)" }, "compare_at": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "variant_id": { "type": [ "string", "null" ], "format": "uuid" }, "variants_count": { "type": "integer" }, "image": { "type": [ "string", "null" ] }, "in_stock": { "type": "boolean" }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "brand": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCard" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "facets": { "$ref": "#/components/schemas/Facets" } } }, "Variant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": [ "string", "null" ] }, "barcode": { "type": [ "string", "null" ] }, "price": { "type": "integer", "description": "Minor units (halalas)" }, "compare_at": { "type": [ "integer", "null" ] }, "options": { "type": "object", "additionalProperties": true }, "weight": { "type": [ "number", "null" ] }, "available": { "type": [ "integer", "null" ], "description": "Sellable units; null = untracked (no stock cap)" }, "in_stock": { "type": "boolean" } } }, "ProductDetail": { "allOf": [ { "$ref": "#/components/schemas/ProductCard" }, { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "attributes": { "type": "object", "additionalProperties": true }, "images": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }, "related": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "bought_together", "similar", "none" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "price": { "type": "integer", "description": "Minor units (halalas)" }, "variant_id": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "reason": { "type": "string" } } } } } } } } ] }, "ProductDetailEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" } } }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "product_count": { "type": "integer" }, "children": { "type": "array", "items": { "type": "object" }, "description": "Only in `tree`" } } }, "CategoryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "tree": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }, "CartItem": { "type": "object", "properties": { "variant_id": { "type": "string", "format": "uuid" }, "product_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "options": { "type": "object", "additionalProperties": true }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer", "description": "Minor units (halalas)" }, "line_total": { "type": "integer", "description": "Minor units (halalas)" }, "available": { "type": [ "integer", "null" ] }, "sellable": { "type": "boolean", "description": "false when the variant vanished or its product went inactive" } } }, "Cart": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "status": { "type": "string", "enum": [ "open", "converted", "expired" ] }, "currency": { "type": "string" }, "coupon_code": { "type": [ "string", "null" ] }, "order_id": { "type": [ "string", "null" ], "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "item_count": { "type": "integer" }, "subtotal": { "type": "integer", "description": "Minor units (halalas)" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CartEnvelope": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/Cart" } } }, "CartCreated": { "type": "object", "properties": { "token": { "type": "string" }, "cart": { "$ref": "#/components/schemas/Cart" } } }, "CartAddItem": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 } } }, "CartSetQuantity": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 0, "description": "0 removes the line" } } }, "CartCoupon": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "Quote": { "type": "object", "properties": { "subtotal": { "type": "integer", "description": "Minor units (halalas)" }, "discount": { "type": "integer", "description": "Minor units (halalas)" }, "shipping": { "type": "integer", "description": "Minor units (halalas)" }, "tax": { "type": "integer", "description": "Minor units (halalas)" }, "tax_rate": { "type": "number" }, "prices_include_tax": { "type": "boolean" }, "total": { "type": "integer", "description": "Minor units (halalas)" }, "currency": { "type": "string" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer", "description": "Minor units (halalas)" }, "line_total": { "type": "integer", "description": "Minor units (halalas)" }, "tax": { "type": "integer", "description": "Minor units (halalas)" } } } }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "integer" } } }, "shipping_quote": { "type": "object", "description": "Merchant flat-rate quote: cost, flat, threshold, free, remaining, offer + echoed method/destination" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "CartCheckout": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "description": "mada | visa | applepay | cod | wallet | … (as enabled for the store)" }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string", "description": "Identifies the customer; omit for a guest order" }, "email": { "type": "string", "format": "email" } } }, "shipping_address": { "type": "object", "additionalProperties": true }, "return_url": { "type": "string", "format": "uri" }, "otp": { "type": "string", "description": "Required when Checkout Trust demands it (error otp_required)" }, "otp_challenge": { "type": "string" } } }, "CheckoutRequest": { "type": "object", "required": [ "items", "method" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 }, "unit_price": { "type": "integer", "description": "Minor units (halalas)" } } } }, "method": { "type": "string" }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string", "description": "Identifies the customer; omit for a guest order" }, "email": { "type": "string", "format": "email" } } }, "shipping_address": { "type": "object", "additionalProperties": true }, "return_url": { "type": "string", "format": "uri" } } }, "CheckoutResponse": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "grand_total": { "type": "integer", "description": "Minor units (halalas)" }, "tax_total": { "type": "integer", "description": "Minor units (halalas)" }, "currency": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" } } }, "payment": { "type": "object", "properties": { "gateway": { "type": "string" }, "status": { "type": "string" }, "action_url": { "type": [ "string", "null" ], "description": "Redirect the shopper here (3DS / hosted page) when present" } } }, "repriced": { "type": "array", "description": "Lines whose client-sent price differed from the catalog", "items": { "type": "object" } }, "cart": { "$ref": "#/components/schemas/Cart" } } }, "BulkOperation": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "create", "update", "delete" ] }, "key": { "type": "string", "description": "Optional per-operation idempotency key. A replay returns the first result and writes nothing." }, "data": { "type": "object", "additionalProperties": true, "description": "The same body the single-item endpoint takes." } } }, "BulkOperationResult": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position in the submitted array — the \"row\"" }, "key": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "result": { "type": "object", "additionalProperties": true }, "error": { "type": "string", "description": "validation_failed, not_found, unknown_action, idempotency_key_reused, …" }, "errors": { "type": "object", "additionalProperties": true, "description": "Laravel validation errors, exactly as the single path returns them" }, "replayed": { "type": "boolean", "description": "true when this is a stored result, not a fresh write" } } }, "BulkRequest": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/BulkOperation" } }, "dry_run": { "type": "boolean", "description": "Validate everything and write nothing" } } }, "BulkJobRequest": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/BulkOperation" } }, "chunk_size": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } }, "BulkResult": { "type": "object", "properties": { "resource": { "type": "string" }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "succeeded", "partial", "failed" ] }, "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkOperationResult" } }, "replayed": { "type": "boolean" } } }, "BulkJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "resource": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "processed": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } }, "chunk_size": { "type": "integer" }, "error_report_url": { "type": "string", "format": "uri" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BulkErrorReport": { "type": "object", "properties": { "job_id": { "type": "string" }, "resource": { "type": "string" }, "status": { "type": "string" }, "failed": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": [ "integer", "null" ] }, "key": { "type": [ "string", "null" ] }, "error": { "type": "string" }, "errors": { "type": "object", "additionalProperties": true } } } } } }, "ImportCapabilities": { "type": "object", "properties": { "import": { "type": "object", "additionalProperties": true }, "export": { "type": "object", "additionalProperties": true }, "connectors": { "type": "object", "additionalProperties": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } } } } } }, "ImportRequest": { "type": "object", "required": [ "entity", "format" ], "properties": { "entity": { "type": "string", "enum": [ "products", "customers" ] }, "format": { "type": "string", "enum": [ "csv", "json", "xml", "ndjson", "xlsx" ] }, "dry_run": { "type": "boolean", "description": "Report the diff and write nothing" }, "mapping": { "type": "object", "additionalProperties": { "type": "string" }, "description": "target column => source column in the file" }, "data": { "type": "string", "description": "The file content inline (base64 for xlsx)" }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "url": { "type": "string", "format": "uri", "description": "Fetched only after the SSRF guard clears it" } } }, "ImportDryRun": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "entity": { "type": "string" }, "mapping": { "type": "object", "additionalProperties": true }, "total": { "type": "integer" }, "would_create": { "type": "integer" }, "would_update": { "type": "integer" }, "would_fail": { "type": "integer" }, "diff": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "action": { "type": "string", "enum": [ "create", "update" ] }, "match": { "type": [ "object", "null" ], "additionalProperties": true }, "values": { "type": "object", "additionalProperties": true } } } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "wrote_nothing": { "type": "boolean" } } }, "DataTransferJob": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "entity": { "type": "string" }, "format": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "failed": { "type": "integer" } } }, "ImportResult": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/DataTransferJob" }, "report": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "failed": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "message": { "type": "string" } } } } } } } }, "ExportRequest": { "type": "object", "required": [ "entity", "format" ], "properties": { "entity": { "type": "string", "enum": [ "products", "orders", "customers" ] }, "format": { "type": "string", "enum": [ "csv", "json", "ndjson" ] } } }, "ExportResult": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/DataTransferJob" }, "download_url": { "type": [ "string", "null" ], "format": "uri", "description": "Signed; expires" }, "expires_in": { "type": "integer", "description": "Seconds" } } }, "AnalyticsCatalogue": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "type": "string" } }, "granularities": { "type": "array", "items": { "type": "string" } }, "max_granularity": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "string" } }, "comparisons": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "object", "additionalProperties": { "type": "string" } } } }, "AnalyticsReport": { "type": "object", "properties": { "metric": { "type": "string" }, "granularity": { "type": "string" }, "max_granularity": { "type": "string" }, "dimension": { "type": "string" }, "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "currency": { "type": "string" }, "unit": { "type": "string", "enum": [ "minor_units", "count" ] }, "source": { "type": "string" }, "total": { "type": "object", "properties": { "value": { "type": [ "integer", "null" ], "description": "null for margin when any line has no known cost" }, "lines_without_cost": { "type": "integer" }, "note": { "type": "string" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "value": { "type": [ "integer", "null" ] } } } }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "integer" } } } }, "comparison": { "type": "object", "properties": { "period": { "type": "string" }, "range": { "type": "object", "additionalProperties": true }, "total": { "type": "object", "additionalProperties": true }, "change": { "type": [ "object", "null" ], "properties": { "absolute": { "type": "integer" }, "percent": { "type": [ "number", "null" ] } } } } } } }, "SearchResult": { "type": "object", "properties": { "query": { "type": "string" }, "mode": { "type": "string", "enum": [ "keyword", "semantic", "auto" ] }, "resource": { "type": "string", "enum": [ "all", "products", "orders", "customers", "invoices", "messages" ] }, "answered_by": { "type": "string", "description": "keyword:database | keyword:meilisearch | semantic:index | semantic:scan | unavailable | none" }, "data": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "href": { "type": [ "string", "null" ] } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "count": { "type": "integer" }, "total": { "type": "integer" }, "reason": { "type": "string", "description": "Why a path could not answer: query_too_short, no_embeddings_indexed, resource_not_embedded" } } } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "Also the cursor" }, "type": { "type": "string" }, "version": { "type": "integer" }, "aggregate": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "sequence": { "type": "integer" } } }, "payload": { "type": "object", "additionalProperties": true }, "correlation_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "EventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" }, "source": { "type": "string" } } } } }, "OAuthTokenRequest": { "type": "object", "required": [ "grant_type", "client_id" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Confidential clients only" }, "code": { "type": "string", "description": "authorization_code grant" }, "redirect_uri": { "type": "string", "description": "Must equal the one the code was issued for" }, "code_verifier": { "type": "string", "description": "PKCE verifier; required, S256 only" }, "refresh_token": { "type": "string", "description": "refresh_token grant" } } }, "OAuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string", "description": "Rotated on every use" }, "scope": { "type": "string", "description": "Space-separated; each scope is an `ability:` the token carries" } } }, "OAuthError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "supported_grant_types": { "type": "array", "items": { "type": "string" } } } }, "OAuthMetadata": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_refused": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ChannelState": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "configured": { "type": "boolean" }, "transport": { "type": "string", "enum": [ "webhook_url", "api_key", "mailer", "none" ] }, "credential": { "type": [ "string", "null" ], "description": "What the merchant must paste — never the stored value" }, "credential_masked": { "type": [ "string", "null" ] }, "target": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "throttle_per_minute": { "type": "integer" } } }, "ChannelList": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChannelState" } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "slack", "discord", "teams", "webhook", "email", "pagerduty", "opsgenie", "telegram", "voice" ] } } } }, "ChannelConfig": { "type": "object", "properties": { "credential": { "type": "string", "description": "Incoming-webhook URL, integration key or bot token" }, "target": { "type": "string", "description": "Email address or Telegram chat id, where the channel needs one" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "throttle_per_minute": { "type": "integer", "minimum": 0, "maximum": 600 } } }, "ChannelDelivery": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "event": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "delivered", "failed", "pending", "blocked", "unavailable", "throttled" ] }, "reason": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "response_code": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "ChannelDeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }