{ "openapi": "3.1.0", "info": { "title": "LARM Stores API", "version": "2026-10-15", "description": "LARM stores API for apps. Breaking changes are announced at least 12 months in advance." }, "servers": [ { "url": "https://larm.sa", "description": "LARM" } ], "x-larm-scopes": [ "analytics.categories:read", "analytics.overview:read", "analytics.products:read", "analytics.sales:read", "analytics:read", "carts:read", "categories:read", "categories:write", "coupons.status:write", "coupons:read", "customers:read", "inventory:read", "inventory:write", "orders.digital:read", "orders:read", "pages.delete:write", "pages.publish:write", "pages:read", "pages:write", "payments:read", "products.media:read", "products.media:write", "products.prices:read", "products.prices:write", "products.seo:read", "products.seo:write", "products:read", "products:write", "reviews.moderation:write", "reviews:read" ], "x-larm-limits": { "bodyBytes": 65536, "pageDefault": 25, "pageMax": 100, "accessSeconds": 900, "quotaProofMs": 5000, "policyLeaseMs": 45000 }, "paths": { "/stores/{storeId}/v1/me": { "get": { "operationId": "me", "summary": "me", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Me" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stores/{storeId}/v1/products": { "get": { "operationId": "products.list", "summary": "products.list", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "inactive" ] }, "description": "Product status." }, { "in": "query", "name": "category", "schema": { "type": "string" }, "description": "Category name." }, { "in": "query", "name": "search", "schema": { "type": "string", "maxLength": 100 }, "description": "Search by name." }, { "in": "query", "name": "updated_since", "schema": { "type": "string", "format": "date-time" }, "description": "Products updated after this time." } ], "x-required-scope": "products:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/KeysetMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "products:read" ] }, "post": { "operationId": "products.create", "summary": "products.create", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-required-scope": "products:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" } } } }, "x-accepted-scopes": [ "products:write" ] } }, "/stores/{storeId}/v1/products/{id}": { "get": { "operationId": "products.get", "summary": "products.get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "products:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "products:read" ] } }, "/stores/{storeId}/v1/categories": { "get": { "operationId": "categories.list", "summary": "categories.list", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 } }, { "in": "query", "name": "search", "schema": { "type": "string", "maxLength": 100 }, "description": "Search by name." } ], "x-required-scope": "products:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/KeysetMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "products:read", "categories:read" ], "x-accepted-scopes": [ "categories:read", "products:read" ] }, "post": { "operationId": "categories.create", "summary": "categories.create", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-required-scope": "categories:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Category" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" } } } }, "x-accepted-scopes": [ "categories:write" ] } }, "/stores/{storeId}/v1/categories/{id}": { "get": { "operationId": "categories.get", "summary": "categories.get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "products:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Category" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "products:read", "categories:read" ], "x-accepted-scopes": [ "categories:read", "products:read" ] }, "patch": { "operationId": "categories.update", "summary": "categories.update", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "categories:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Category" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryContent" } } } }, "x-accepted-scopes": [ "categories:write" ] } }, "/stores/{storeId}/v1/products/{id}/content": { "patch": { "operationId": "products.content", "summary": "products.content", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "products:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductContent" } } } }, "x-accepted-scopes": [ "products:write" ] } }, "/stores/{storeId}/v1/products/{id}/prices": { "patch": { "operationId": "products.prices", "summary": "products.prices", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "products.prices:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductPrices" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prices" } } } }, "x-accepted-scopes": [ "products.prices:write" ] }, "get": { "operationId": "products.price.get", "summary": "Read product prices", "description": "Read the price, previous price and pricing state only.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "products.prices:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductPrices" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "products:read", "products.prices:read" ], "x-accepted-scopes": [ "products.prices:read", "products:read" ] } }, "/stores/{storeId}/v1/products/{id}/inventory": { "get": { "operationId": "inventory.get", "summary": "inventory.get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "inventory:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Inventory" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "inventory:read" ] } }, "/stores/{storeId}/v1/products/{id}/inventory-adjustments": { "post": { "operationId": "inventory.adjust", "summary": "inventory.adjust", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-required-scope": "inventory:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InventoryAdjustment" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockDelta" } } } }, "x-accepted-scopes": [ "inventory:write" ] } }, "/stores/{storeId}/v1/inventory": { "get": { "operationId": "inventory.list", "summary": "inventory.list", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 } } ], "x-required-scope": "inventory:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inventory" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/KeysetMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "inventory:read" ] } }, "/stores/{storeId}/v1/analytics/overview": { "get": { "operationId": "analytics.overview", "summary": "analytics.overview", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date" } } ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AnalyticsOverview" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/AnalyticsMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "analytics:read", "analytics.overview:read" ], "x-accepted-scopes": [ "analytics:read", "analytics.overview:read" ] } }, "/stores/{storeId}/v1/analytics/sales": { "get": { "operationId": "analytics.sales", "summary": "analytics.sales", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date" } } ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPoint" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/AnalyticsMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "analytics:read", "analytics.sales:read" ], "x-accepted-scopes": [ "analytics:read", "analytics.sales:read" ] } }, "/stores/{storeId}/v1/analytics/sales-by-product": { "get": { "operationId": "analytics.products", "summary": "analytics.products", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date" } } ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSales" }, "maxItems": 100 }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/AnalyticsMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "analytics:read", "analytics.products:read" ], "x-accepted-scopes": [ "analytics:read", "analytics.products:read" ] } }, "/stores/{storeId}/v1/analytics/sales-by-category": { "get": { "operationId": "analytics.categories", "summary": "analytics.categories", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date" } } ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySales" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/AnalyticsMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-any-scope": [ "analytics:read", "analytics.categories:read" ], "x-accepted-scopes": [ "analytics:read", "analytics.categories:read" ] } }, "/stores/{storeId}/v1/webhook-subscriptions": { "get": { "operationId": "webhooks.list", "summary": "webhooks.list", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "webhooks.create", "summary": "webhooks.create", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" }, "secret": { "type": "string", "description": "Signing secret: 32 bytes, base64url-encoded. Returned once." } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreate" } } } } } }, "/stores/{storeId}/v1/webhook-subscriptions/{id}": { "patch": { "operationId": "webhooks.update", "summary": "webhooks.update", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdate" } } } } }, "delete": { "operationId": "webhooks.delete", "summary": "webhooks.delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stores/{storeId}/v1/webhook-subscriptions/{id}/rotate-secret": { "post": { "operationId": "webhooks.rotate", "summary": "webhooks.rotate", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" }, "secret": { "type": "string", "description": "The new secret. Returned once." } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stores/{storeId}/v1/webhook-subscriptions/{id}/test": { "post": { "operationId": "webhooks.test", "summary": "webhooks.test", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "queued": { "const": true }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "test": { "const": true } } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "description": "Omit the body to test the first subscribed topic, or select a subscribed event_type.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "event_type": { "type": "string" } } } } } } } }, "/stores/{storeId}/v1/webhook-subscriptions/{id}/replay": { "post": { "operationId": "webhooks.replay", "summary": "webhooks.replay", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "selected": { "type": "integer" } } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Replay" } } } } } }, "/oauth/token": { "post": { "operationId": "oauth.token", "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenInput" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenInput" } } } }, "responses": { "200": { "description": "New token pair", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthToken" } } } }, "default": { "description": "Rejected with a stable error code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/operations/status": { "post": { "operationId": "oauth.status", "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthOperation" } } } }, "responses": { "200": { "description": "App server only; tokens are never sent to the browser" }, "default": { "description": "Documented rejection" } } } }, "/oauth/operations/lookup": { "post": { "operationId": "oauth.lookup", "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenInput" } } } }, "responses": { "200": { "description": "App server only; tokens are never sent to the browser" }, "default": { "description": "Documented rejection" } } } }, "/oauth/operations/recover": { "post": { "operationId": "oauth.recover", "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthOperation" } } } }, "responses": { "200": { "description": "App server only; tokens are never sent to the browser" }, "default": { "description": "Documented rejection" } } } }, "/stores/{storeId}/v1/products/{id}/media": { "get": { "operationId": "products.media.get", "summary": "Read product media", "description": "Read product images and alt text, without price or content.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "products.media:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductMediaResource" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "products.media:read" ] }, "patch": { "operationId": "products.media.update", "summary": "Update product media", "description": "Update the main image, additional images and alt text, after file checks.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "products.media:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductMediaResource" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductMedia" } } } }, "x-accepted-scopes": [ "products.media:write" ] } }, "/stores/{storeId}/v1/products/{id}/seo": { "get": { "operationId": "products.seo.get", "summary": "Read product SEO", "description": "Read the SEO title, description, keywords and social sharing image.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "products.seo:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductSeoResource" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "products.seo:read" ] }, "patch": { "operationId": "products.seo.update", "summary": "Update product SEO", "description": "Update the SEO title, description, keywords and social sharing image.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "products.seo:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductSeoResource" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "headers": { "ETag": { "description": "Send it in If-Match with the next update.", "schema": { "type": "string", "pattern": "^\"p1\\.\\d+\\.[A-Za-z0-9_-]{43}\"$" } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSeo" } } } }, "x-accepted-scopes": [ "products.seo:write" ] } }, "/stores/{storeId}/v1/pages": { "get": { "operationId": "pages.list", "summary": "Read store pages", "description": "Read page content, drafts and SEO settings.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 } } ], "x-required-scope": "pages:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Page" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "pages:read" ] }, "post": { "operationId": "pages.create", "summary": "Create and update pages", "description": "Create drafts and update their content; updating a published page also requires the publish scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "x-required-scope": "pages:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Page" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCreate" } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "pages:write" ] } }, "/stores/{storeId}/v1/pages/{id}": { "get": { "operationId": "pages.get", "summary": "Read store pages", "description": "Read page content, drafts and SEO settings.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "pages:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Page" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "pages:read" ] }, "patch": { "operationId": "pages.update", "summary": "Create and update pages", "description": "Create drafts and update their content. Updating a published page also requires pages.publish:write.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "pages:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Page" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageUpdate" } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "pages:write" ] }, "delete": { "operationId": "pages.delete", "summary": "Delete pages", "description": "Permanently delete a specific page; the update scope does not grant this.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "pages.delete:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "pages.delete:write" ] } }, "/stores/{storeId}/v1/pages/{id}/publication": { "patch": { "operationId": "pages.publish", "summary": "Publish and hide pages", "description": "Change page visibility for visitors; separate from content updates.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "pages.publish:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Page" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublication" } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "pages.publish:write" ] } }, "/stores/{storeId}/v1/coupons": { "get": { "operationId": "coupons.list", "summary": "Read discount coupons", "description": "Read discount rules and usage, without the customer email linked to the coupon.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 } } ], "x-required-scope": "coupons:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "coupons:read" ] } }, "/stores/{storeId}/v1/coupons/{id}": { "get": { "operationId": "coupons.get", "summary": "Read discount coupons", "description": "Read discount rules and usage, without the customer email linked to the coupon.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "coupons:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Coupon" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "coupons:read" ] } }, "/stores/{storeId}/v1/coupons/{id}/status": { "patch": { "operationId": "coupons.status", "summary": "Activate and deactivate coupons", "description": "Change the status of an existing coupon only; its value and conditions cannot be changed.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "coupons.status:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Coupon" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponStatus" } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "coupons.status:write" ] } }, "/stores/{storeId}/v1/reviews": { "get": { "operationId": "reviews.list", "summary": "Read reviews", "description": "Read review text, rating and publication state, without the customer's name, email or order number.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 } } ], "x-required-scope": "reviews:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "reviews:read" ] } }, "/stores/{storeId}/v1/reviews/{id}": { "get": { "operationId": "reviews.get", "summary": "Read reviews", "description": "Read review text, rating and publication state, without the customer's name, email or order number.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "reviews:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Review" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "reviews:read" ] } }, "/stores/{storeId}/v1/reviews/{id}/moderation": { "patch": { "operationId": "reviews.moderation", "summary": "Publish and hide reviews", "description": "Approve or hide a review; the customer's text cannot be changed and no messages are sent.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" }, "description": "ETag from a GET of this same resource projection." } ], "x-required-scope": "reviews.moderation:write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Review" }, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewModeration" } } } }, "x-runtime-migration": "apps_104_app_extended_resources.sql", "x-accepted-scopes": [ "reviews.moderation:write" ] } }, "/stores/{storeId}/v1/orders": { "get": { "operationId": "orders.list", "summary": "List orders", "description": "Orders, newest first, with items, amounts, payment status and the customer order link.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Number of items per page." }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 }, "description": "The meta.next_cursor value from the previous page. Valid for 15 minutes and bound to the same filters." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "cancelled", "returned" ], "description": "Order status as the merchant sees it. Any refund makes it returned." }, "description": "Order status." }, { "in": "query", "name": "payment_status", "schema": { "type": "string", "enum": [ "unpaid", "paid", "refunded" ] }, "description": "Payment status." }, { "in": "query", "name": "created_after", "schema": { "type": "string", "format": "date-time" }, "description": "Orders created after this time." }, { "in": "query", "name": "created_before", "schema": { "type": "string", "format": "date-time" }, "description": "Orders created before this time." }, { "in": "query", "name": "updated_after", "schema": { "type": "string", "format": "date-time" }, "description": "Orders updated after this time; use it for periodic sync." } ], "x-required-scope": "orders:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "orders:read" ] } }, "/stores/{storeId}/v1/orders/{id}": { "get": { "operationId": "orders.get", "summary": "Get an order", "description": "The full order by its ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" } } ], "x-required-scope": "orders:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "orders:read" ] } }, "/stores/{storeId}/v1/payments": { "get": { "operationId": "payments.list", "summary": "List payments", "description": "Payment outcomes: succeeded or failed, with the order ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Number of items per page." }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 }, "description": "The meta.next_cursor value from the previous page. Valid for 15 minutes and bound to the same filters." } ], "x-required-scope": "payments:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "payments:read" ] } }, "/stores/{storeId}/v1/payments/{id}": { "get": { "operationId": "payments.get", "summary": "Get a payment", "description": "A single payment outcome by its ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "x-required-scope": "payments:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "payments:read" ] } }, "/stores/{storeId}/v1/orders/{id}/digital-items": { "get": { "operationId": "orders.digital.get", "summary": "Get delivered digital content", "description": "The codes, links and files delivered in a paid order.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" } } ], "x-required-scope": "orders.digital:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DigitalItems" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "orders.digital:read" ] } }, "/stores/{storeId}/v1/abandoned-carts": { "get": { "operationId": "carts.list", "summary": "List abandoned carts", "description": "Unpaid carts the store treats as abandoned, newest first.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Number of items per page." }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 4096 }, "description": "The meta.next_cursor value from the previous page. Valid for 15 minutes and bound to the same filters." }, { "in": "query", "name": "created_after", "schema": { "type": "string", "format": "date-time" }, "description": "Carts created after this time." } ], "x-required-scope": "carts:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AbandonedCart" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "carts:read" ] } }, "/stores/{storeId}/v1/abandoned-carts/{id}": { "get": { "operationId": "carts.get", "summary": "Get an abandoned cart", "description": "A single cart by its ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the store the app is installed on." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" } } ], "x-required-scope": "carts:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AbandonedCart" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "default": { "description": "Rejected with a stable error code and the request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-accepted-scopes": [ "carts:read" ] } }, "/oauth/authorize": { "get": { "operationId": "oauth.authorize", "summary": "Start authorization", "description": "Redirects the browser (303) to the merchant consent page.", "parameters": [ { "in": "query", "name": "response_type", "required": true, "schema": { "const": "code" } }, { "in": "query", "name": "client_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "store_id", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "From larm_store_id in the launch URL." }, { "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Exact match of a URL registered in the version." }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 512 } }, { "in": "query", "name": "code_challenge", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "in": "query", "name": "code_challenge_method", "required": true, "schema": { "const": "S256" } }, { "in": "query", "name": "scope", "required": true, "schema": { "type": "string", "maxLength": 2048 }, "description": "Space-separated, including all of their dependencies." }, { "in": "query", "name": "version_id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "303": { "description": "To the consent page in the merchant dashboard", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "default": { "description": "Rejected with a stable error code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/launch/verify": { "post": { "operationId": "oauth.launch.verify", "summary": "Verify a launch URL", "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchVerify" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LaunchVerify" } } } }, "responses": { "200": { "description": "The URL was issued by LARM just now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchContext" } } } }, "default": { "description": "Rejected with a stable error code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lar_at opaque" }, "clientSecretBasic": { "type": "http", "scheme": "basic" } }, "schemas": { "Product": { "type": "object", "x-projection-fields": [ "id", "name", "description", "short_desc", "image", "images", "image_alt", "category", "slug", "keywords", "supported_devices", "seo_title", "seo_description", "og_image", "product_kind", "status", "price", "old_price", "price_state", "resource_version" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" } }, "image_alt": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "description": "Category name." }, "slug": { "type": [ "string", "null" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "supported_devices": {}, "seo_title": { "type": [ "string", "null" ] }, "seo_description": { "type": [ "string", "null" ] }, "og_image": { "type": [ "string", "null" ] }, "product_kind": { "enum": [ "digital", "service", "physical" ] }, "status": { "enum": [ "active", "inactive" ] }, "price": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Price in SAR." }, "old_price": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "description": "Price before discount." }, "price_state": { "enum": [ "required", "ready" ], "description": "required until a price is set; a new product is created inactive with price 0.00." }, "resource_version": { "type": "integer" } } }, "ProductContent": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 240 }, "description": { "type": "string", "maxLength": 50000 }, "short_desc": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "image_alt": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "supported_devices": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "seo_title": { "type": "string" }, "seo_description": { "type": "string" }, "og_image": { "type": [ "string", "null" ] } } }, "ProductCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 240 }, "description": { "type": "string", "maxLength": 50000 }, "short_desc": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "image_alt": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "supported_devices": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "seo_title": { "type": "string" }, "seo_description": { "type": "string" }, "og_image": { "type": [ "string", "null" ] }, "product_kind": { "type": "string", "enum": [ "digital", "service", "physical" ] }, "price": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,9})(?:\\.[0-9]{1,2})?$", "x-exclusive-positive": true }, "old_price": { "type": [ "string", "null" ] } }, "required": [ "name", "product_kind" ] }, "Prices": { "type": "object", "additionalProperties": false, "properties": { "price": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,9})(?:\\.[0-9]{1,2})?$", "x-exclusive-positive": true }, "old_price": { "type": [ "string", "null" ] } }, "required": [ "price" ] }, "CategoryContent": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "image": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 100000 } } }, "CategoryCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "image": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "name" ] }, "StockDelta": { "type": "object", "additionalProperties": false, "properties": { "delta": { "type": "integer", "minimum": -100000, "maximum": 100000, "x-excludes": [ 0 ] }, "reason": { "type": "string", "minLength": 3, "maxLength": 240 } }, "required": [ "delta", "reason" ] }, "Envelope": { "type": "object", "required": [ "data", "meta" ], "description": "Every successful response has status 200. The ETag is returned in the ETag header, not in the body.", "properties": { "data": {}, "execution": { "$ref": "#/components/schemas/Execution" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Error": { "type": "object", "required": [ "error" ], "description": "An error is a stable code only, with no message; branch on the code.", "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9_]{1,80}$" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "SubscriptionCreate": { "type": "object", "additionalProperties": false, "properties": { "endpoint_url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" } }, "payload_version": { "const": 1 } }, "required": [ "endpoint_url", "event_types", "payload_version" ] }, "SubscriptionUpdate": { "type": "object", "additionalProperties": false, "properties": { "state": { "enum": [ "active", "paused" ] }, "event_types": { "type": "array", "items": { "type": "string" } } } }, "Replay": { "type": "object", "additionalProperties": false, "description": "Replay eligible deliveries created within the last seven days. from must not be in the future; to must be at or after from and no more than five seconds in the future.", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "reason": { "type": "string", "minLength": 3, "maxLength": 240 } }, "required": [ "from", "to", "reason" ] }, "OAuthTokenInput": { "type": "object", "additionalProperties": false, "properties": { "grant_type": { "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "grant_type" ] }, "OAuthOperation": { "type": "object", "additionalProperties": false, "properties": { "operation_id": { "type": "string", "format": "uuid" } }, "required": [ "operation_id" ] }, "PageCreate": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 160, "minLength": 1 }, "slug": { "type": "string", "maxLength": 160, "pattern": "^[\\u0600-\\u06ffa-z0-9]+(?:-[\\u0600-\\u06ffa-z0-9]+)*$" }, "content": { "type": "string", "maxLength": 50000 }, "seo_title": { "type": "string", "maxLength": 65 }, "seo_description": { "type": "string", "maxLength": 320 }, "seo_keywords": { "type": "string", "maxLength": 500 }, "indexable": { "type": "boolean" } }, "required": [ "title", "slug" ], "minProperties": 1 }, "PageUpdate": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 160, "minLength": 1 }, "slug": { "type": "string", "maxLength": 160, "pattern": "^[\\u0600-\\u06ffa-z0-9]+(?:-[\\u0600-\\u06ffa-z0-9]+)*$" }, "content": { "type": "string", "maxLength": 50000 }, "seo_title": { "type": "string", "maxLength": 65 }, "seo_description": { "type": "string", "maxLength": 320 }, "seo_keywords": { "type": "string", "maxLength": 500 }, "indexable": { "type": "boolean" } }, "minProperties": 1 }, "PagePublication": { "type": "object", "additionalProperties": false, "properties": { "is_active": { "type": "boolean" } }, "required": [ "is_active" ], "minProperties": 1 }, "CouponStatus": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "minProperties": 1 }, "ReviewModeration": { "type": "object", "additionalProperties": false, "properties": { "approved": { "type": "boolean" } }, "required": [ "approved" ], "minProperties": 1 }, "ProductMedia": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": [ "string", "null" ] }, "images": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "image_alt": { "type": "string", "maxLength": 240 } }, "minProperties": 1 }, "ProductSeo": { "type": "object", "additionalProperties": false, "properties": { "seo_title": { "type": "string", "maxLength": 65 }, "seo_description": { "type": "string", "maxLength": 320 }, "keywords": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 100, "minLength": 1 } }, "og_image": { "type": [ "string", "null" ] } }, "minProperties": 1 }, "Meta": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "The request ID; include it in any support request." } } }, "ListMeta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null on the last page." }, "request_id": { "type": "string", "format": "uuid" } } }, "Customer": { "type": "object", "description": "Included only with the customers:read scope.", "x-requires-scope": "customers:read", "properties": { "id": { "type": [ "string", "null" ], "description": "The customer's account ID in the store, or null for a guest order." }, "name": { "type": [ "string", "null" ], "description": "The customer's name as entered." }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format, such as +966512345678, or null if it is not a valid number." }, "email": { "type": [ "string", "null" ], "format": "email" } } }, "OrderItem": { "type": "object", "required": [ "product_id", "name", "quantity", "unit_price", "total" ], "properties": { "product_id": { "type": "string" }, "name": { "type": "string", "description": "Product name at the time of the order." }, "kind": { "type": "string", "enum": [ "digital", "physical", "service" ], "description": "Product kind." }, "quantity": { "type": "integer", "minimum": 1 }, "unit_price": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Unit price in SAR." }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Unit price × quantity." } } }, "Order": { "type": "object", "required": [ "id", "number", "status", "payment_status", "currency", "totals", "items", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Stable order ID." }, "number": { "type": "integer", "description": "Order number shown to the merchant and the customer." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "cancelled", "returned" ], "description": "Order status as the merchant sees it. Any refund makes it returned." }, "payment_status": { "type": "string", "enum": [ "unpaid", "paid", "refunded" ] }, "currency": { "type": "string", "const": "SAR" }, "totals": { "type": "object", "required": [ "total" ], "properties": { "subtotal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Items total before discount and shipping." }, "discount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Discount." }, "shipping": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Shipping fee." }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Amount paid by the customer." } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "order_url": { "type": [ "string", "null" ], "format": "uri", "description": "The customer's orders page in the store (/orders), the same link as the order email. It is not a link to one order and carries no sign-in token. null when the store has no https domain." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "refunded_at": { "type": [ "string", "null" ], "format": "date-time" }, "customer": { "$ref": "#/components/schemas/Customer" }, "shipping_address": { "type": [ "object", "null" ], "description": "Shipping address as entered by the customer, or null when the order has no address. Included only with customers:read.", "x-requires-scope": "customers:read", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "E.164 format, or null." }, "country": { "type": [ "string", "null" ], "description": "Always SA." }, "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "short_address_code": { "type": [ "string", "null" ] }, "building_number": { "type": [ "string", "null" ] }, "secondary_number": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } } }, "resource_version": { "type": "integer", "const": 0, "description": "Always 0 for orders. Order the events of one order by resource.version in the webhook envelope." } } }, "DigitalItems": { "type": "object", "required": [ "order_id", "items" ], "properties": { "order_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "type", "value" ], "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "code", "link", "file", "text" ] }, "value": { "type": "string", "description": "The code, link or text. File links are signed and tied to the order: send them to the customer, never publish them, and read them again when needed instead of storing them." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "null today for every type. If links gain an expiry, its time will appear here." } } } } } }, "AbandonedCart": { "type": "object", "required": [ "id", "currency", "total", "items", "checkout_url", "created_at" ], "properties": { "id": { "type": "string" }, "currency": { "type": "string", "const": "SAR" }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Cart total." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "checkout_url": { "type": "string", "format": "uri", "description": "The same checkout link the store sends in its abandoned-cart reminder." }, "created_at": { "type": "string", "format": "date-time" }, "customer": { "$ref": "#/components/schemas/Customer" } } }, "Payment": { "type": "object", "required": [ "id", "order_id", "status", "created_at" ], "properties": { "id": { "type": "string" }, "order_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "Payment outcome: succeeded or failed. In-progress attempts are not returned." }, "created_at": { "type": "string", "format": "date-time" } } }, "Execution": { "type": "object", "description": "Who executed the request: the app, version, installation and store. Field names here are camelCase.", "properties": { "appId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "installationId": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "generation": { "type": "integer" }, "routeEpoch": { "type": "integer" }, "appAuthEpoch": { "type": "integer" }, "grantRevision": { "type": "integer" } } }, "KeysetMeta": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "consistency": { "const": "live_keyset" }, "request_id": { "type": "string", "format": "uuid" } } }, "ProductPrices": { "type": "object", "properties": { "id": { "type": "integer" }, "resource_version": { "type": "integer" }, "price": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Price in SAR." }, "old_price": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "description": "Price before discount." }, "price_state": { "enum": [ "required", "ready" ], "description": "required until a price is set; a new product is created inactive with price 0.00." } } }, "ProductMediaResource": { "type": "object", "properties": { "id": { "type": "integer" }, "resource_version": { "type": "integer" }, "image": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" } }, "image_alt": { "type": [ "string", "null" ] } } }, "ProductSeoResource": { "type": "object", "properties": { "id": { "type": "integer" }, "resource_version": { "type": "integer" }, "seo_title": { "type": [ "string", "null" ] }, "seo_description": { "type": [ "string", "null" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "og_image": { "type": [ "string", "null" ] } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer" }, "visible": { "type": "boolean" }, "resource_version": { "type": "integer" } } }, "Inventory": { "oneOf": [ { "type": "object", "title": "Physical", "properties": { "product_id": { "type": "integer" }, "product_kind": { "const": "physical" }, "mode": { "enum": [ "variants", "manual" ] }, "quantity": { "type": "integer" }, "resource_version": { "type": "integer" } } }, { "type": "object", "title": "Digital or service", "properties": { "product_id": { "type": "integer" }, "product_kind": { "enum": [ "digital", "service" ] }, "mode": { "enum": [ "unlimited", "digital_aggregate" ] }, "available_units": { "type": [ "integer", "null" ], "description": "null when unlimited." }, "resource_version": { "type": "integer" } } } ] }, "InventoryAdjustment": { "type": "object", "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer" }, "before": { "type": "integer" }, "delta": { "type": "integer" }, "resource_version": { "type": "integer" } } }, "Page": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "slug": { "type": "string" }, "content": { "type": "string" }, "is_active": { "type": "boolean" }, "seo_title": { "type": [ "string", "null" ] }, "seo_description": { "type": [ "string", "null" ] }, "seo_keywords": { "type": [ "string", "null" ] }, "indexable": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Coupon": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "type": { "enum": [ "percent", "fixed" ] }, "value": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Discount percentage or amount." }, "usage": { "type": "integer", "description": "Number of uses." }, "expiry": { "type": [ "string", "null" ], "format": "date" }, "active": { "type": "boolean" } } }, "Review": { "type": "object", "properties": { "id": { "type": "integer" }, "product_name": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "text": { "type": "string" }, "approved": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "AnalyticsMeta": { "type": "object", "properties": { "metric_definition": { "const": "dashboard_sales_v1" }, "timezone": { "const": "Asia/Riyadh" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "currency": { "const": "SAR" }, "request_id": { "type": "string", "format": "uuid" } } }, "AnalyticsOverview": { "type": "object", "properties": { "orders": { "type": "integer" }, "paid_orders": { "type": "integer" }, "fulfilled_orders": { "type": "integer" }, "gross_sales": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Gross sales." }, "wallet_refunds": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Refunded to the customer wallet." }, "net_sales": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Net sales." }, "average_order": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Average order value." }, "currency": { "const": "SAR" } } }, "SalesPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "net_sales": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "Net sales for the day." }, "paid_orders": { "type": "integer" } } }, "ProductSales": { "type": "object", "properties": { "product_id": { "type": "integer" }, "units": { "type": "integer" }, "mapping": { "type": "string" } } }, "CategorySales": { "type": "object", "properties": { "category": { "type": "string" }, "units": { "type": "integer" }, "mapping": { "type": "string" } } }, "Me": { "type": "object", "properties": { "store_id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "installation_id": { "type": "string", "format": "uuid" }, "installation_generation": { "type": "integer" }, "grant_revision": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string" } }, "api_major": { "const": 1 }, "store": { "type": "object", "description": "Public store details.", "properties": { "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ], "description": "The store domain, without https." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The store https origin, or null when it has no domain." }, "currency": { "const": "SAR" }, "locale": { "const": "ar" } } } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "endpoint_url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" } }, "payload_version": { "const": 1 }, "state": { "enum": [ "active", "paused", "revoked" ] }, "secret_generation": { "type": "integer" }, "issued_scopes": { "type": "array", "items": { "type": "string" } } } }, "OAuthToken": { "type": "object", "required": [ "access_token", "refresh_token", "token_type", "expires_in", "scope", "store_id", "installation_id" ], "properties": { "access_token": { "type": "string", "pattern": "^lar_at_[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$", "description": "Valid for 900 seconds." }, "refresh_token": { "type": "string", "pattern": "^lar_rt_[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$", "description": "Valid for 30 days, and replaced on every refresh." }, "token_type": { "const": "Bearer" }, "expires_in": { "const": 900 }, "scope": { "type": "string", "description": "Granted scopes, space-separated." }, "store_id": { "type": "string", "format": "uuid" }, "installation_id": { "type": "string", "format": "uuid" }, "installation_generation": { "type": "integer" }, "grant_revision": { "type": "integer" }, "operation_id": { "type": "string", "format": "uuid" } } }, "LaunchVerify": { "type": "object", "additionalProperties": false, "required": [ "larm_store_id", "larm_intent", "larm_issued_at", "larm_nonce", "larm_signature" ], "properties": { "larm_store_id": { "type": "string", "format": "uuid" }, "larm_installation_id": { "type": "string", "format": "uuid" }, "larm_intent": { "enum": [ "install", "open" ] }, "larm_issued_at": { "type": "string", "pattern": "^\\d{1,12}$" }, "larm_nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" }, "larm_signature": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } }, "LaunchContext": { "type": "object", "properties": { "valid": { "const": true }, "store_id": { "type": "string", "format": "uuid" }, "installation_id": { "type": [ "string", "null" ], "format": "uuid" }, "intent": { "enum": [ "install", "open" ] }, "issued_at": { "type": "integer" } } } } }, "x-larm-scope-catalog": [ { "id": "analytics:read", "group": "Analytics", "label": "Read sales reports", "description": "Read all aggregated sales reports, without customer data.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "products:read", "group": "Products", "label": "Read products and categories", "description": "Read product content, prices, images and categories.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "inventory:read", "group": "Inventory", "label": "Read inventory availability", "description": "Read physical quantities and digital product availability, without the codes.", "dependencies": [ "products:read" ], "sensitive": false, "access": "read" }, { "id": "products:write", "group": "Products", "label": "Create products and update content", "description": "Create inactive products and update content; prices are a separate scope.", "dependencies": [ "products:read" ], "sensitive": false, "access": "write" }, { "id": "products.prices:write", "group": "Products", "label": "Update prices", "description": "Update the price and previous price of a live product, effective immediately.", "dependencies": [ "products:read" ], "sensitive": true, "access": "write" }, { "id": "categories:write", "group": "Categories", "label": "Manage categories", "description": "Create categories and update their names, images and sort order.", "dependencies": [ "products:read" ], "sensitive": false, "access": "write" }, { "id": "inventory:write", "group": "Inventory", "label": "Adjust physical inventory", "description": "Increase or decrease quantity with a reason; digital codes cannot be changed.", "dependencies": [ "inventory:read" ], "sensitive": true, "access": "write" }, { "id": "categories:read", "group": "Categories", "label": "Read categories", "description": "Read category names, images and sort order, without product content.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "products.prices:read", "group": "Products", "label": "Read product prices", "description": "Read the price, previous price and pricing state only.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "products.media:read", "group": "Products", "label": "Read product media", "description": "Read product images and alt text, without price or content.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "products.media:write", "group": "Products", "label": "Update product media", "description": "Update the main image, additional images and alt text, after file checks.", "dependencies": [ "products.media:read" ], "sensitive": false, "access": "write" }, { "id": "products.seo:read", "group": "Products", "label": "Read product SEO", "description": "Read the SEO title, description, keywords and social sharing image.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "products.seo:write", "group": "Products", "label": "Update product SEO", "description": "Update the SEO title, description, keywords and social sharing image.", "dependencies": [ "products.seo:read" ], "sensitive": false, "access": "write" }, { "id": "analytics.overview:read", "group": "Analytics", "label": "Read sales overview", "description": "Aggregated sales metrics. No customer data.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "analytics.sales:read", "group": "Analytics", "label": "Read daily sales", "description": "Sales totals by day. No customer data.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "analytics.products:read", "group": "Analytics", "label": "Read product sales", "description": "Aggregated sales per product. No customer data.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "analytics.categories:read", "group": "Analytics", "label": "Read category sales", "description": "Aggregated sales per category. No customer data.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "pages:read", "group": "Pages", "label": "Read store pages", "description": "Read page content, drafts and SEO settings.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "pages:write", "group": "Pages", "label": "Create and update pages", "description": "Create drafts and update their content; updating a published page also requires the publish scope.", "dependencies": [ "pages:read" ], "sensitive": false, "access": "write" }, { "id": "pages.publish:write", "group": "Pages", "label": "Publish and hide pages", "description": "Change page visibility for visitors; separate from content updates.", "dependencies": [ "pages:read" ], "sensitive": true, "access": "write" }, { "id": "pages.delete:write", "group": "Pages", "label": "Delete pages", "description": "Permanently delete a specific page; the update scope does not grant this.", "dependencies": [ "pages:read" ], "sensitive": true, "access": "write" }, { "id": "coupons:read", "group": "Coupons", "label": "Read discount coupons", "description": "Read discount rules and usage, without the customer email linked to the coupon.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "coupons.status:write", "group": "Coupons", "label": "Activate and deactivate coupons", "description": "Change the status of an existing coupon only; its value and conditions cannot be changed.", "dependencies": [ "coupons:read" ], "sensitive": true, "access": "write" }, { "id": "reviews:read", "group": "Reviews", "label": "Read reviews", "description": "Read review text, rating and publication state, without the customer's name, email or order number.", "dependencies": [], "sensitive": false, "access": "read" }, { "id": "reviews.moderation:write", "group": "Reviews", "label": "Publish and hide reviews", "description": "Approve or hide a review; the customer's text cannot be changed and no messages are sent.", "dependencies": [ "reviews:read" ], "sensitive": true, "access": "write" }, { "id": "orders:read", "group": "Orders", "label": "Read orders", "description": "Read the full order: number, status, payment status, items, quantities, amounts, currency and the customer order link; without the customer's name and phone.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "payments:read", "group": "Payments", "label": "Read payments", "description": "The outcome of each payment attempt (succeeded or failed) and its order ID only; no gateway, amount or card details.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "customers:read", "group": "Customers", "label": "Read customer contact details", "description": "Customer name, phone in international format, email and shipping address, inside orders, abandoned carts and their webhooks.", "dependencies": [], "sensitive": true, "access": "read" }, { "id": "orders.digital:read", "group": "Orders", "label": "Read delivered digital content", "description": "The codes, links and files delivered to the customer in a paid order, so your app can deliver them to the customer.", "dependencies": [ "orders:read" ], "sensitive": true, "access": "read" }, { "id": "carts:read", "group": "Abandoned carts", "label": "Read abandoned carts", "description": "Items, total and checkout link of unpaid carts.", "dependencies": [], "sensitive": true, "access": "read" } ], "webhooks": { "order.created": { "post": { "operationId": "event.order.created", "summary": "Order created", "x-required-scopes": [ "orders:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "order.created" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges receipt." } } } }, "order.paid": { "post": { "operationId": "event.order.paid", "summary": "Order paid", "x-required-scopes": [ "orders:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "order.paid" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges receipt." } } } }, "order.status.updated": { "post": { "operationId": "event.order.status.updated", "summary": "Order status changed", "x-required-scopes": [ "orders:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "order.status.updated" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "object", "properties": { "previous_status": { "type": "string", "enum": [ "pending", "processing", "completed", "cancelled", "returned" ], "description": "Order status as the merchant sees it. Any refund makes it returned." } } } ] } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges receipt." } } } }, "order.refunded": { "post": { "operationId": "event.order.refunded", "summary": "Order refunded", "x-required-scopes": [ "orders:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "order.refunded" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges receipt." } } } }, "order.digital.delivered": { "post": { "operationId": "event.order.digital.delivered", "summary": "Digital content delivered", "x-required-scopes": [ "orders:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "order.digital.delivered" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "object", "properties": { "digital_items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "type", "value" ], "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "code", "link", "file", "text" ] }, "value": { "type": "string", "description": "The code, link or text. File links are signed and tied to the order: send them to the customer, never publish them, and read them again when needed instead of storing them." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "null today for every type. If links gain an expiry, its time will appear here." } } }, "x-requires-scope": "orders.digital:read" } } } ] } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges receipt." } } } }, "abandoned_cart.created": { "post": { "operationId": "event.abandoned_cart.created", "summary": "New abandoned cart", "x-required-scopes": [ "carts:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "abandoned_cart.created" }, "data": { "$ref": "#/components/schemas/AbandonedCart" } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges receipt." } } } } }, "x-larm-api-version": "2026-10-15", "x-larm-breaking-change-notice-months": 12 }