{ "openapi": "3.1.0", "info": { "title": "Nouq Storefront API", "version": "0.2.0", "description": "The public API behind every Nouq storefront. Use it to build a **headless storefront** (your own\nfrontend, app or integration) for any Nouq store.\n\n- **Choose the store** with the `X-Nouq-Host` header: `.nouq.net` or the store's own domain.\n- **No API key, no cookies:** everything here is public, and carts and orders are addressed by their\n unguessable `token`. CORS is open, so you can call it from the browser.\n- **Money** is an integer in minor units (halalas for SAR). Format it with Latin digits.\n- **Errors** are RFC 9457 problem details: `code` is for your code, `detail` is a shopper-friendly\n Arabic message, and `fields` has per-field messages.\n- **SDKs:** TypeScript (`@nouq/storefront-sdk`) and Go (`github.com/nouq/nouq/backend/pkg/nouq`).\n Start with the guide at [nouq.net/developers](https://nouq.net/en/developers).\n" }, "servers": [ { "url": "http://localhost:8090" } ], "tags": [ { "name": "storefront" } ], "paths": { "/storefront/v1/canonical": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontCanonical", "responses": { "200": { "description": "The store's primary host; on a funnel's own domain, also the funnel's sales page", "content": { "application/json": { "schema": { "type": "object", "required": [ "host" ], "properties": { "host": { "type": "string" }, "funnel_slug": { "type": "string", "description": "This host is a funnel's domain: serve this sales page at / and send other paths to host" } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/returns": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "returnEligibility", "responses": { "200": { "description": "Whether and what can be returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnEligibility" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "post": { "tags": [ "storefront" ], "operationId": "requestReturn", "description": "JSON, or multipart with a JSON \"data\" field and up to 3 \"photos\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRequestInput" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "data": { "type": "string" }, "photos": { "type": "array", "items": { "type": "string", "format": "binary" } } } } } } }, "responses": { "201": { "description": "Return", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Return" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/reviews": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "reviewForm", "responses": { "200": { "description": "What the shopper can review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewForm" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "post": { "tags": [ "storefront" ], "operationId": "submitReviews", "description": "Verified buyers only (delivered order), one review per product. JSON, or multipart with a JSON \"data\" field and up to 4 photos per product in \"photos_\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewSubmit" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "additionalProperties": { "type": "array", "items": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Saved reviews", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicReview" } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/reviews": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storeReviews", "parameters": [ { "in": "query", "name": "min_rating", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 4 }, "description": "Only reviews with at least this many stars" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 12, "default": 6 } } ], "responses": { "200": { "description": "The store's overall rating and its latest written reviews", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreReviews" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/products/{slug}/reviews": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "productReviews", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Rating summary and published reviews", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductReviews" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/privacy/unsubscribe": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "unsubscribe", "description": "Withdraw marketing consent using the signed link from a message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/theme": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontTheme", "parameters": [ { "in": "query", "name": "preview", "schema": { "type": "string" }, "description": "Preview token: returns the draft instead of the published theme" } ], "responses": { "200": { "description": "Theme to render", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontTheme" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/landings/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontLanding", "parameters": [ { "in": "query", "name": "preview", "schema": { "type": "string" }, "description": "A draft's preview token" }, { "in": "query", "name": "bucket", "schema": { "type": "integer", "minimum": 0, "maximum": 99 }, "description": "The visitor's A/B bucket: under a test, the page's other version may come back, under its own slug" } ], "responses": { "200": { "description": "Landing page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPublic" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/landings/{slug}/view": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "storefrontLandingView", "description": "Counts one visit (send once per session). Drafts and unknown pages are ignored.", "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } }, "/storefront/v1/landings/{slug}/form-start": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "storefrontLandingFormStart", "description": "Counts a visitor starting the order form (send once per browser per day). Drafts and unknown pages are ignored.", "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } }, "/storefront/v1/landings/{slug}/cart": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "put": { "tags": [ "storefront" ], "operationId": "storefrontLandingCart", "description": "Replaces the landing cart's lines with the shopper's pick (this product only) and prices the page's quantity offer.", "parameters": [ { "in": "query", "name": "preview", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingCartInput" } } } }, "responses": { "200": { "description": "Priced cart (keep its token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/funnel-thank-you/{id}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontFunnelThankYou", "description": "The thank-you message of the funnel a landing page (an order's landing_page_id) belongs to.", "responses": { "200": { "description": "Empty headline: use the store's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelThankYou" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/landing-templates/{id}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "product", "schema": { "type": "string" }, "description": "An active product's slug (default: the store's first active product)" }, { "in": "query", "name": "lang", "schema": { "type": "string", "enum": [ "ar", "en" ] } }, { "in": "query", "name": "package_token", "schema": { "type": "string" }, "description": "A designer package's preview token: its latest unapproved version" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontLandingTemplate", "description": "A funnel template rendered for one of the store's active products, as a preview page (nothing saved, preview true).", "responses": { "200": { "description": "Preview page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPublic" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/pages": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPages", "responses": { "200": { "description": "Published pages (without bodies)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorePage" } } } } } } } }, "/storefront/v1/pages/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPage", "responses": { "200": { "description": "Page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePage" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/posts": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPosts", "parameters": [ { "in": "query", "name": "category", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Published posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostPage" } } } } } } }, "/storefront/v1/posts/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPost", "responses": { "200": { "description": "Post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPost" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/newsletter": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "subscribeNewsletter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeInput" } } } }, "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/popups": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPopups", "description": "The popups running now with their rules; the browser picks at most one per page view.", "responses": { "200": { "description": "Live popups", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LivePopup" } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/popups/{id}/submit": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "storefront" ], "operationId": "submitPopup", "description": "Signs a shopper up with marketing consent and returns their single-use code (also sent on WhatsApp).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PopupSubmitInput" } } } }, "responses": { "200": { "description": "Signed up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PopupSubmitResult" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/popups/{id}/events": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "storefront" ], "operationId": "popupEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "view", "close" ] } } } } } }, "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/store": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "getCurrentStore", "responses": { "200": { "description": "Store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/categories": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontCategories", "responses": { "200": { "description": "Categories", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } } }, "/storefront/v1/products": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontProducts", "parameters": [ { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "featured", "schema": { "type": "string", "enum": [ "true" ] } }, { "$ref": "#/components/parameters/Q" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPage" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/products/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontProduct", "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/shipping-methods": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontShippingMethods", "responses": { "200": { "description": "Active methods", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingMethod" } } } } } } } }, "/storefront/v1/governorates": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontGovernorates", "description": "Egypt's governorates, for an Egyptian store's address form (the governorate goes in the address's city).", "responses": { "200": { "description": "Egypt's governorates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Governorate" } } } } } } } }, "/storefront/v1/carts": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "createCart", "responses": { "201": { "description": "New cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } } } } }, "/storefront/v1/carts/{token}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "getCart", "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/items": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "post": { "tags": [ "storefront" ], "operationId": "addCartItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCartItem" } } } }, "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/items/{variantID}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" }, { "in": "path", "name": "variantID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "storefront" ], "operationId": "setCartItemQuantity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetQuantity" } } } }, "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/discount": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "put": { "tags": [ "storefront" ], "operationId": "applyCoupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponInput" } } } }, "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "delete": { "tags": [ "storefront" ], "operationId": "removeCoupon", "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/contact": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "put": { "tags": [ "storefront" ], "operationId": "setCartContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartContact" } } } }, "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/checkout": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "checkout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutInput" } } } }, "responses": { "201": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontOrder", "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/products/{slug}/quantity-offer": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontQuantityOffer", "description": "The product's active quantity tiers, for its page.", "responses": { "200": { "description": "The offer, or null", "content": { "application/json": { "schema": { "type": "object", "required": [ "offer" ], "properties": { "offer": { "oneOf": [ { "$ref": "#/components/schemas/QuantityOffer" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/products/{slug}/bundles": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontProductBundles", "description": "The active bundles naming this product that can be bought now.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductBundle" } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/products/{slug}/recommendations": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontProductRecommendations", "description": "Real co-purchases for the product's page.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRecommendations" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/recommendations": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontCartRecommendations", "description": "Real co-purchases of what's in the cart.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRecommendations" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/order-form/cart": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "put": { "tags": [ "storefront" ], "operationId": "storefrontOrderFormCart", "description": "Sets the cart behind the order form on a product page: separate from the shopper's normal cart, priced like a store cart.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingCartInput" } } } }, "responses": { "200": { "description": "Priced cart (keep its token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/upsell": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontOrderUpsell", "description": "The post-purchase offer (recorded as shown): for a COD order awaiting confirmation (accepting adds to it), or a paid card order not shipped yet (accepting makes a small order of its own to pay, shipped with it).", "responses": { "200": { "description": "The offer, or null", "content": { "application/json": { "schema": { "type": "object", "required": [ "offer" ], "properties": { "offer": { "oneOf": [ { "$ref": "#/components/schemas/PostPurchaseOffer" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "post": { "tags": [ "storefront" ], "operationId": "answerOrderUpsell", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPurchaseAnswer" } } } }, "responses": { "200": { "description": "The order, and the downsell after a declined upsell", "content": { "application/json": { "schema": { "type": "object", "required": [ "order", "next" ], "properties": { "order": { "$ref": "#/components/schemas/Order" }, "next": { "oneOf": [ { "$ref": "#/components/schemas/PostPurchaseOffer" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/invoices": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontOrderInvoices", "responses": { "200": { "description": "The shopper's tax invoices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/cod-confirmation": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "post": { "tags": [ "storefront" ], "operationId": "answerCOD", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CODAnswer" } } } }, "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/payments": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "post": { "tags": [ "storefront" ], "operationId": "startPayment", "responses": { "201": { "description": "Payment started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/payments/{id}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "storefront" ], "operationId": "getPayment", "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/payments/{id}/confirm": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "storefront" ], "operationId": "confirmPayment", "description": "The shopper is back from the merchant's gateway. Reads the payment's real status from the gateway and settles it.", "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/pixels": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPixels", "responses": { "200": { "description": "Ad pixels to load", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixelConfig" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/pixels/fired": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "pixelsFired", "description": "Counts an event the browser sent to pixels, for the merchant's pixel health.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixelsFired" } } } }, "responses": { "204": { "description": "Counted" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/events": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "trackEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackEvent" } } } }, "responses": { "204": { "description": "Recorded" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/feeds/{token}/{file}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "products.xml", "products.csv" ] } } ], "get": { "tags": [ "storefront" ], "operationId": "catalogFeed", "description": "Product feed for Meta, TikTok, Snapchat and Google Merchant Center (Google product format; CSV for Meta).", "responses": { "200": { "description": "Feed", "content": { "application/xml": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/payment-methods": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "total", "in": "query", "schema": { "type": "integer" }, "description": "Order total in halalas", "for BNPL limits": null } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontPaymentMethods", "responses": { "200": { "description": "Methods on offer besides COD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethods" } } } } } } }, "/storefront/v1/orders/{token}/transfer": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "orderTransfer", "responses": { "200": { "description": "Bank details and receipts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferInfo" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/transfer-receipts": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "uploadTransferReceipt", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "receipt" ], "properties": { "receipt": { "type": "string", "format": "binary" }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferReceipt" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/sales-proof": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontSalesProof", "description": "Sales notices from the store's real recent orders (empty when off or fewer than two).", "responses": { "200": { "description": "Where to show notices and what", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveSalesProof" } } } } } } }, "/storefront/v1/checkout/fields": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontCheckoutFields", "responses": { "200": { "description": "The store's checkout questions", "in order": null, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutField" } } } } } } } }, "/storefront/v1/checkout/shipping-rates": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "cart_token", "in": "query", "schema": { "type": "string" } }, { "name": "city", "in": "query", "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "checkoutShippingRates", "responses": { "200": { "description": "Active methods priced for this cart and city", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingRate" } } } } } } } }, "/storefront/v1/orders/{token}/tracking": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "orderTracking", "responses": { "200": { "description": "The order's parcels and their scans", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/checkout/cod-check": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "codCheck", "description": "Whether cash on delivery needs a deposit or isn't available for this buyer and total (the decision is made again at checkout).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "total" ], "properties": { "phone": { "type": "string" }, "total": { "$ref": "#/components/schemas/Money" }, "shipping_total": { "$ref": "#/components/schemas/Money" }, "address": { "$ref": "#/components/schemas/Address" }, "cart_token": { "type": "string", "description": "The cart, so products that always need a deposit and a phone already proven with a code count" } } } } } }, "responses": { "200": { "description": "Outcome", "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "deposit", "trusted" ], "properties": { "action": { "type": "string", "enum": [ "auto_confirm", "whatsapp", "otp", "deposit", "block" ] }, "deposit": { "$ref": "#/components/schemas/Money" }, "trusted": { "type": "boolean" } } } } } } } } }, "/storefront/v1/checkout/phone-code": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "requestCheckoutPhoneCode", "description": "Sends the code checkout asked for (422 with fields.phone_code) by SMS. 409 phone_code_not_needed when the store's policy never asks for one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cart_token", "phone" ], "properties": { "cart_token": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "expires_in" ], "properties": { "phone": { "type": "string" }, "expires_in": { "type": "integer" }, "dev_code": { "type": "string", "description": "Local development only" } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/checkout/phone-code/verify": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "verifyCheckoutPhoneCode", "description": "Checks the code and marks the phone proven on the cart; checkout then confirms the order.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cart_token", "phone", "code" ], "properties": { "cart_token": { "type": "string" }, "phone": { "type": "string" }, "code": { "type": "string" } } } } } }, "responses": { "204": { "description": "Verified" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/trust/badge": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontTrustBadge", "responses": { "200": { "description": "Whether the store earned the trusted-store badge", "content": { "application/json": { "schema": { "type": "object", "required": [ "earned", "met" ], "properties": { "earned": { "type": "boolean" }, "met": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/storefront/v1/seo/resolve": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "resolveRedirect", "description": "Where a path with no page should permanently redirect, from the store's redirects or from the URL shapes of Shopify, Zid and Salla.", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Target", "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/sitemap/products": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "sitemapProducts", "description": "Active products for one sitemap file (5,000 per page, oldest first).", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sitemap entries", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "per_page" ], "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "required": [ "slug", "title_ar", "title_en", "updated_at", "images" ], "properties": { "slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "images": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } }, "/storefront/v1/return-policy": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontReturnPolicy", "responses": { "200": { "description": "The store's return policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnSettings" } } } } } } }, "/storefront/v1/seo/verification": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "storefrontSEOVerification", "responses": { "200": { "description": "Verification meta tag contents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SEOSettings" } } } } } } }, "/storefront/v1/passport/exchange": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "passportExchange", "description": "The store's server swaps the one-time code from my.nouq.net for a link token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Link token and the shopper's profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "link_token", "profile" ], "properties": { "link_token": { "type": "string" }, "profile": { "$ref": "#/components/schemas/PassportStoreProfile" } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/register": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "accountRegister", "description": "Opens a shopper account on this store and signs it in; a code to confirm the email goes out too.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "201": { "description": "Signed in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperSession" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/login": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "accountLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperSession" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/logout": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "accountLogout", "responses": { "204": { "description": "Signed out" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/me": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "accountMe", "responses": { "200": { "description": "The signed-in account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperAccount" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "put": { "tags": [ "storefront" ], "operationId": "accountUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperAccount" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/password": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "accountChangePassword", "description": "Needs the current password; signs every other device out.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } } } } } }, "responses": { "204": { "description": "Changed" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/verify/request": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "accountRequestVerification", "responses": { "200": { "description": "Code sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperCodeSent" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/verify": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "accountVerify", "description": "Confirms the email; earlier guest orders with it then show in the account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperAccount" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/reset/request": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "accountRequestReset", "description": "Emails a reset code. Answers the same whether or not the email has an account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "Code sent (if the account exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperCodeSent" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/reset": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "accountReset", "description": "Sets a new password with the emailed code, signs out every device and signs in here.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code", "password" ], "properties": { "email": { "type": "string" }, "code": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperSession" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/orders": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "accountOrders", "responses": { "200": { "description": "The account's orders", "newest first": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShopperOrder" } } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/account/delete": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Account-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "accountDelete", "description": "Closes the account for good (the password confirms it). Orders stay with the store.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string" } } } } } }, "responses": { "204": { "description": "Deleted" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/passport/me": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "X-Passport-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "passportForStore", "responses": { "200": { "description": "The connected shopper", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportStoreProfile" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/passport-payment": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Passport-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "storefront" ], "operationId": "passportPayment", "description": "One tap with a card saved on the shopper's Passport (needs the cards scope).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "card_id" ], "properties": { "card_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/loyalty/code": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "requestLoyaltyCode", "description": "Sends a WhatsApp code that proves the phone before its points are spent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OTPRequestResult" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/loyalty": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" }, { "name": "X-Passport-Token", "in": "header", "required": false, "description": "Skips the code when its phone matches", "schema": { "type": "string" } }, { "name": "X-Account-Token", "in": "header", "required": false, "description": "The signed-in store account: skips the code when its email is verified and one of its orders was delivered to the phone", "schema": { "type": "string" } } ], "put": { "tags": [ "storefront" ], "operationId": "useLoyalty", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UseLoyaltyInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "delete": { "tags": [ "storefront" ], "operationId": "removeLoyalty", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/referral": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "put": { "tags": [ "storefront" ], "operationId": "useReferral", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "delete": { "tags": [ "storefront" ], "operationId": "removeReferral", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/referrals/{code}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "referralLink", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralLink" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/orders/{token}/rewards": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "orderRewards", "description": "Points earned and the shopper's referral link, on their order page.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRewards" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/rewards": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "get": { "tags": [ "storefront" ], "operationId": "rewardPrograms", "description": "The store's points and referral programmes, as shoppers see them.", "responses": { "200": { "description": "Programmes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardPrograms" } } } } } } }, "/storefront/v1/business": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/BusinessToken" } ], "get": { "tags": [ "storefront" ], "operationId": "businessMe", "description": "The store's wholesale programme and the signed-in business buyer, if any.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessMe" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/business/code": { "parameters": [ { "$ref": "#/components/parameters/Host" } ], "post": { "tags": [ "storefront" ], "operationId": "requestBusinessCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OTPRequestResult" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/business/session": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/BusinessToken" } ], "post": { "tags": [ "storefront" ], "operationId": "businessSignIn", "description": "Check the WhatsApp code; the token goes in X-Business-Token afterwards.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "code" ], "properties": { "phone": { "type": "string" }, "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "me" ], "properties": { "token": { "type": "string" }, "me": { "$ref": "#/components/schemas/BusinessMe" } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "delete": { "tags": [ "storefront" ], "operationId": "businessSignOut", "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/business/apply": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/BusinessToken" } ], "post": { "tags": [ "storefront" ], "operationId": "applyBusinessAccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessAccountInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessMe" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/business/products/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/BusinessToken" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "storefront" ], "operationId": "businessProductTiers", "description": "The product's wholesale tiers, for an approved business buyer.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VariantTiers" } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/business": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" }, { "$ref": "#/components/parameters/BusinessToken" } ], "put": { "tags": [ "storefront" ], "operationId": "linkBusinessCart", "description": "Price the cart for the signed-in buyer's approved account.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } }, "delete": { "tags": [ "storefront" ], "operationId": "unlinkBusinessCart", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/carts/{token}/quote": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" }, { "$ref": "#/components/parameters/BusinessToken" } ], "post": { "tags": [ "storefront" ], "operationId": "requestQuote", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/quotes/{token}": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" } ], "get": { "tags": [ "storefront" ], "operationId": "quoteByToken", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/quotes/{token}/accept": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" }, { "$ref": "#/components/parameters/BusinessToken" } ], "post": { "tags": [ "storefront" ], "operationId": "acceptQuote", "description": "Fill the cart (or a new one) with the quote's lines at its prices.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cart_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "cart_token" ], "properties": { "cart_token": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/storefront/v1/quotes/{token}/decline": { "parameters": [ { "$ref": "#/components/parameters/Host" }, { "$ref": "#/components/parameters/TokenPath" }, { "$ref": "#/components/parameters/BusinessToken" } ], "post": { "tags": [ "storefront" ], "operationId": "declineQuoteAsBuyer", "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "parameters": { "Host": { "in": "header", "name": "X-Nouq-Host", "required": false, "schema": { "type": "string", "example": "test.localhost" } }, "Page": { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } }, "PerPage": { "in": "query", "name": "per_page", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, "Q": { "in": "query", "name": "q", "schema": { "type": "string" } }, "IdPath": { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "TokenPath": { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } }, "BusinessToken": { "in": "header", "name": "X-Business-Token", "required": false, "description": "A business buyer's storefront session (wholesale)", "schema": { "type": "string" } } }, "responses": { "Problem": { "description": "Error (RFC 7807)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NoContent": { "description": "Done" } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Locale": { "type": "string", "enum": [ "ar", "en" ] }, "Money": { "type": "integer", "format": "int64", "description": "Minor units (halalas)" }, "OTPRequestResult": { "type": "object", "required": [ "phone", "expires_in" ], "properties": { "phone": { "type": "string" }, "expires_in": { "type": "integer" }, "dev_code": { "type": "string", "description": "Only in local development", "and for the public demo account": null }, "demo": { "type": "boolean", "description": "The public demo account (0500000000); dev_code is shown on screen" } } }, "Domain": { "type": "object", "required": [ "host", "is_primary", "verified" ], "properties": { "host": { "type": "string" }, "is_primary": { "type": "boolean" }, "verified": { "type": "boolean" } } }, "Store": { "type": "object", "required": [ "id", "slug", "name", "description", "logo_url", "whatsapp_phone", "currency", "locale", "status", "cod_enabled", "cod_fee", "vat_enabled", "vat_rate_bp", "min_order_total", "recovery_enabled", "recovery_delay_minutes", "recovery_discount_code", "domains", "created_at", "phone_messages" ], "properties": { "phone_messages": { "type": "boolean", "description": "Nouq can deliver WhatsApp and SMS (PHONE_CODES). False: shoppers hear by email only; don't offer or promise phone messages" }, "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "logo_url": { "type": "string" }, "whatsapp_phone": { "type": "string" }, "currency": { "type": "string" }, "locale": { "$ref": "#/components/schemas/Locale" }, "status": { "type": "string", "enum": [ "active", "suspended", "closed" ] }, "cod_enabled": { "type": "boolean" }, "cod_fee": { "$ref": "#/components/schemas/Money" }, "vat_enabled": { "type": "boolean" }, "vat_rate_bp": { "type": "integer" }, "min_order_total": { "$ref": "#/components/schemas/Money", "description": "The least the store takes an order for: products after offers and discounts, before rewards and shipping (0: no minimum)" }, "recovery_enabled": { "type": "boolean" }, "recovery_delay_minutes": { "type": "integer" }, "recovery_discount_code": { "type": "string" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "created_at": { "type": "string", "format": "date-time" } } }, "SearchSnippet": { "type": "object", "description": "What a product or category shows in Google. Empty fields fall back to the title and description.", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "maxLength": 70 }, "description": { "type": "string", "maxLength": 170 } } }, "Category": { "type": "object", "required": [ "id", "slug", "name_ar", "name_en", "position", "product_count", "description_ar", "description_en", "seo", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "position": { "type": "integer" }, "product_count": { "type": "integer" }, "description_ar": { "type": "string", "description": "Intro text shown above the category's products" }, "description_en": { "type": "string" }, "seo": { "$ref": "#/components/schemas/SearchSnippet" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Option": { "type": "object", "required": [ "name", "values" ], "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "Variant": { "type": "object", "required": [ "id", "sku", "options", "title", "price", "compare_at_price", "stock", "track_inventory", "in_stock" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "type": "string" } }, "title": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "compare_at_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "stock": { "type": "integer" }, "track_inventory": { "type": "boolean" }, "in_stock": { "type": "boolean" }, "weight_grams": { "type": "integer", "description": "Shipped weight; 0 = the store's default parcel weight" }, "cost": { "type": [ "integer", "null" ], "description": "What the merchant pays per unit (minor units; null = not entered). Only in the merchant's own product responses: never to apps or the storefront." } } }, "Product": { "type": "object", "required": [ "id", "slug", "title_ar", "title_en", "description_ar", "description_en", "status", "featured", "options", "variants", "images", "category_ids", "seo", "free_shipping", "page", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "description_ar": { "type": "string" }, "description_en": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "featured": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }, "images": { "type": "array", "items": { "type": "string" } }, "category_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "seo": { "$ref": "#/components/schemas/SearchSnippet" }, "free_shipping": { "type": "boolean", "description": "This product ships free. An order ships free when every line in it does" }, "page": { "$ref": "#/components/schemas/ProductPageSettings" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProductPageSettings": { "type": "object", "description": "How this product's page sells, for products sold from an ad. All off: the store's normal product page.", "required": [ "buy_now", "button_label", "order_form", "hide_chrome", "hide_related", "sticky_bar", "hide_reviews" ], "properties": { "buy_now": { "type": "boolean", "description": "The button skips the cart and goes straight to checkout" }, "button_label": { "type": "string", "maxLength": 30, "description": "The button's words (empty: the store's)" }, "order_form": { "type": "string", "enum": [ "", "before_description", "after_description" ], "description": "The whole order form on the page, in place of the buy box" }, "hide_chrome": { "type": "boolean", "description": "A focused header and footer instead of the store's" }, "hide_related": { "type": "boolean", "description": "No other products: similar ones, bought together, bundles" }, "sticky_bar": { "type": "string", "enum": [ "", "on", "off" ], "description": "The mobile buy bar (empty: as the store's theme has it)" }, "hide_reviews": { "type": "boolean", "description": "No stars and no reviews section" } } }, "ProductRecommendations": { "type": "object", "required": [ "frequently_bought", "also_like" ], "properties": { "frequently_bought": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" }, "description": "Bought in the same order at least twice in the last year, most often first; in stock" }, "also_like": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" }, "description": "Co-purchases, then the same category, then featured products" } } }, "ProductSummary": { "type": "object", "required": [ "id", "slug", "title_ar", "title_en", "status", "featured", "price", "compare_at_price", "in_stock", "total_stock", "variant_count", "image_url", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "featured": { "type": "boolean" }, "price": { "$ref": "#/components/schemas/Money" }, "compare_at_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "in_stock": { "type": "boolean" }, "total_stock": { "type": "integer" }, "variant_count": { "type": "integer" }, "image_url": { "type": "string" }, "hover_image_url": { "type": "string", "description": "The second photo (empty when there is one); storefront cards fade to it on hover" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProductPage": { "type": "object", "required": [ "items", "total", "page", "per_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "ShippingMethod": { "type": "object", "required": [ "id", "name_ar", "name_en", "eta_ar", "eta_en", "price", "free_over", "active", "position", "region_prices", "other_regions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "eta_ar": { "type": "string" }, "eta_en": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "free_over": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "position": { "type": "integer" }, "carrier": { "type": "string", "description": "'' = flat price; otherwise priced live by this carrier" }, "markup": { "$ref": "#/components/schemas/Money" }, "region_prices": { "type": "array", "items": { "$ref": "#/components/schemas/RegionPrice" } }, "other_regions": { "$ref": "#/components/schemas/OtherRegions" } } }, "RegionPrice": { "type": "object", "required": [ "region", "price" ], "properties": { "region": { "type": "string", "description": "An Egyptian governorate code (CAI…) or a Saudi city" }, "price": { "$ref": "#/components/schemas/Money" } } }, "OtherRegions": { "type": "string", "enum": [ "base", "none" ], "description": "What regions without their own price get: base = the method's price, none = no delivery" }, "ShippingRate": { "type": "object", "required": [ "id", "name_ar", "name_en", "eta_ar", "eta_en", "carrier", "price", "eta_min", "eta_max", "available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "eta_ar": { "type": "string" }, "eta_en": { "type": "string" }, "carrier": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "eta_min": { "type": "integer", "description": "Business days from the carrier (0 = use eta_ar/eta_en)" }, "eta_max": { "type": "integer" }, "available": { "type": "boolean" }, "reason": { "type": "string" } } }, "CarrierAddress": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "city": { "type": "string" }, "district": { "type": "string" }, "street": { "type": "string" }, "building_number": { "type": "string" }, "postal_code": { "type": "string" }, "short_address": { "type": "string" } } }, "CarrierMode": { "type": "string", "enum": [ "own", "nouq" ], "description": "own: the merchant's carrier contract; nouq: Nouq Shipping (Nouq's contract, paid from the shipping balance, ADR 0020)" }, "Governorate": { "type": "object", "required": [ "code", "name_ar", "name_en", "region" ], "properties": { "code": { "type": "string" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "region": { "type": "string", "enum": [ "greater_cairo", "alex_delta", "upper_canal", "remote" ] } } }, "ParcelEvent": { "type": "object", "required": [ "at", "status", "description", "location" ], "properties": { "at": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/ParcelStatus" }, "description": { "type": "string" }, "location": { "type": "string" } } }, "ParcelStatus": { "type": "string", "enum": [ "label_created", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed_attempt", "returned", "cancelled" ] }, "ParcelLabel": { "type": "object", "required": [ "format", "barcode", "service", "route", "from", "to", "pieces", "reference", "contents" ], "properties": { "format": { "type": "string" }, "barcode": { "type": "string" }, "service": { "type": "string" }, "route": { "type": "string" }, "from": { "$ref": "#/components/schemas/CarrierAddress" }, "to": { "$ref": "#/components/schemas/CarrierAddress" }, "pieces": { "type": "integer" }, "reference": { "type": "string" }, "contents": { "type": "string" } } }, "Parcel": { "type": "object", "required": [ "id", "order_id", "carrier", "carrier_name", "sandbox", "tracking_number", "track_url", "status", "weight_grams", "cost", "cod_amount", "mode", "currency", "retail", "cod_fee", "pickup_ref", "pickup_at", "events", "delivered_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid" }, "carrier": { "type": "string" }, "carrier_name": { "type": "string" }, "sandbox": { "type": "boolean" }, "tracking_number": { "type": "string" }, "track_url": { "type": "string" }, "status": { "$ref": "#/components/schemas/ParcelStatus" }, "weight_grams": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Money" }, "cod_amount": { "$ref": "#/components/schemas/Money" }, "mode": { "$ref": "#/components/schemas/CarrierMode" }, "currency": { "type": "string" }, "retail": { "$ref": "#/components/schemas/Money", "description": "Walk-in rate the Nouq price compares with (nouq mode)" }, "cod_fee": { "$ref": "#/components/schemas/Money", "description": "Charged for collecting the cash (nouq mode)" }, "label": { "$ref": "#/components/schemas/ParcelLabel" }, "pickup_ref": { "type": "string" }, "pickup_at": { "type": "string", "format": "date-time", "nullable": true }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ParcelEvent" } }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "DiscountType": { "type": "string", "enum": [ "percent", "fixed", "free_shipping", "buy_x_get_y" ], "description": "buy_x_get_y: for every buy_quantity + get_quantity covered pieces, the cheapest get_quantity come value% off (100: free); it repeats" }, "AppliedDiscount": { "type": "object", "required": [ "code", "title", "type", "amount", "free_shipping" ], "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "type": { "$ref": "#/components/schemas/DiscountType" }, "amount": { "$ref": "#/components/schemas/Money" }, "free_shipping": { "type": "boolean" } } }, "DiscountNudge": { "type": "object", "required": [ "title", "type", "missing_quantity", "missing_amount" ], "properties": { "title": { "type": "string" }, "type": { "$ref": "#/components/schemas/DiscountType" }, "missing_quantity": { "type": "integer", "description": "Pieces of the covered products still to add (0: none)" }, "missing_amount": { "$ref": "#/components/schemas/Money", "description": "Spend on the covered products still to add (0: none)" } } }, "CartItem": { "type": "object", "required": [ "variant_id", "product_id", "product_slug", "title_ar", "title_en", "variant_title", "image_url", "unit_price", "compare_at_price", "quantity", "line_total", "available", "max_quantity", "retail_price", "min_quantity", "next_tier", "quoted" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "product_slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "variant_title": { "type": "string" }, "image_url": { "type": "string" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "compare_at_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "quantity": { "type": "integer" }, "line_total": { "$ref": "#/components/schemas/Money" }, "available": { "type": "boolean" }, "max_quantity": { "type": "integer" }, "retail_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Business carts: the retail price when the wholesale one differs" }, "min_quantity": { "type": "integer", "description": "Business carts: the variant's wholesale minimum (0: no wholesale price)" }, "next_tier": { "oneOf": [ { "$ref": "#/components/schemas/PriceTier" }, { "type": "null" } ], "description": "Business carts: the next quantity break" }, "quoted": { "type": "boolean", "description": "Business carts: priced from an accepted quote" } } }, "Cart": { "type": "object", "required": [ "token", "items", "item_count", "subtotal", "discounts", "discount", "discount_code", "discount_stale", "next_discount", "rewards", "offer", "landing_id", "upsells", "suggestions", "business", "total", "checkoutable", "free_shipping", "min_order", "below_minimum", "min_order_gap" ], "properties": { "token": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "item_count": { "type": "integer" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedDiscount" }, "description": "Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones" }, "discount": { "oneOf": [ { "$ref": "#/components/schemas/AppliedDiscount" }, { "type": "null" } ], "description": "The main one of discounts (the coupon, else the largest); show discounts instead" }, "discount_code": { "type": "string" }, "discount_stale": { "type": "boolean" }, "next_discount": { "oneOf": [ { "$ref": "#/components/schemas/DiscountNudge" }, { "type": "null" } ], "description": "The automatic discount the shopper is closest to" }, "rewards": { "$ref": "#/components/schemas/CartRewards" }, "offer": { "oneOf": [ { "$ref": "#/components/schemas/CartOffer" }, { "type": "null" } ], "description": "A landing page's quantity offer, when the cart came from one" }, "landing_id": { "type": [ "string", "null" ], "format": "uuid" }, "upsells": { "type": "array", "items": { "$ref": "#/components/schemas/CartUpsell" }, "description": "Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/UpsellSuggestion" }, "description": "Cross-sell offers for products not yet in the cart (at most 3)" }, "business": { "oneOf": [ { "$ref": "#/components/schemas/CartBusiness" }, { "type": "null" } ], "description": "The business account the cart is priced for (wholesale; no coupons, offers or rewards)" }, "total": { "$ref": "#/components/schemas/Money", "description": "Subtotal after offer, upsells, discount and rewards, before shipping" }, "checkoutable": { "type": "boolean" }, "free_shipping": { "type": "boolean", "description": "Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached" }, "min_order": { "$ref": "#/components/schemas/Money", "description": "The store's minimum order (0: none)" }, "below_minimum": { "type": "boolean", "description": "The products after offers and discounts don't reach min_order, so the cart can't be checked out" }, "min_order_gap": { "$ref": "#/components/schemas/Money", "description": "What's still missing to reach min_order" } } }, "CartOffer": { "type": "object", "required": [ "landing_id", "label", "quantity", "amount", "free_shipping" ], "properties": { "landing_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "quantity": { "type": "integer", "description": "The tier reached, e.g. 2 for \"2 pieces for 349\" (0: only add-ons)" }, "amount": { "$ref": "#/components/schemas/Money", "description": "What the tier and add-ons take off" }, "free_shipping": { "type": "boolean", "description": "The tier reached ships free" } } }, "CartUpsell": { "type": "object", "required": [ "offer_id", "product_id", "label", "amount" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money", "description": "What the offer takes off one piece" } } }, "UpsellVariant": { "type": "object", "required": [ "id", "title", "price", "offer_price", "available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "offer_price": { "$ref": "#/components/schemas/Money", "description": "One piece with the offer's discount" }, "available": { "type": "boolean" } } }, "UpsellSuggestion": { "type": "object", "required": [ "offer_id", "headline", "product_slug", "title_ar", "title_en", "image_url", "discount_percent", "variants" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "headline": { "type": "string" }, "product_slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "image_url": { "type": "string" }, "discount_percent": { "type": "integer" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/UpsellVariant" } } } }, "ProductBundle": { "type": "object", "required": [ "offer_id", "kind", "headline", "price", "quantity", "regular", "products" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "fixed", "box" ] }, "headline": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "quantity": { "type": "integer", "description": "box: pieces to pick" }, "regular": { "$ref": "#/components/schemas/Money", "description": "What the pieces cost without the bundle (box: filled with the dearest, the most it can save)" }, "products": { "type": "array", "items": { "type": "object", "required": [ "product_id", "slug", "title_ar", "title_en", "image_url", "quantity", "variants" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "image_url": { "type": "string" }, "quantity": { "type": "integer", "description": "fixed: how many of it the bundle has" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/UpsellVariant" } } } } } } }, "UpsellTier": { "type": "object", "required": [ "quantity", "price" ], "properties": { "quantity": { "type": "integer", "minimum": 2, "maximum": 99 }, "price": { "$ref": "#/components/schemas/Money", "description": "The total for this many pieces" }, "label": { "type": "string", "maxLength": 40 }, "badge": { "type": "string", "maxLength": 24 }, "free_shipping": { "type": "boolean", "description": "\\\"An order reaching this tier ships free\\\"" } } }, "QuantityOffer": { "type": "object", "required": [ "offer_id", "headline", "tiers" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "headline": { "type": "string" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/UpsellTier" } } } }, "UpsellStage": { "type": "string", "enum": [ "upsell", "downsell" ] }, "PopupText": { "type": "object", "required": [ "title", "body", "button", "consent", "success" ], "properties": { "title": { "type": "string", "maxLength": 80 }, "body": { "type": "string", "maxLength": 300 }, "button": { "type": "string", "maxLength": 40 }, "consent": { "type": "string", "maxLength": 300, "description": "The line a shopper ticks to sign up (kept with the sign-up, PDPL)" }, "success": { "type": "string", "maxLength": 200, "description": "Shown after signing up", "above the code": null } } }, "PopupContent": { "type": "object", "required": [ "ar", "en", "image_url", "link_url", "channel" ], "properties": { "ar": { "$ref": "#/components/schemas/PopupText" }, "en": { "$ref": "#/components/schemas/PopupText" }, "image_url": { "type": "string" }, "link_url": { "type": "string", "description": "Where an announcement's button goes" }, "channel": { "type": "string", "enum": [ "whatsapp", "email", "both", "" ], "description": "What a sign-up asks for (empty for announcements)" } } }, "PopupDesign": { "type": "object", "required": [ "layout" ], "properties": { "layout": { "type": "string", "enum": [ "auto", "center", "sheet" ], "description": "auto: a bottom sheet on phones, a centre dialog on larger screens" } } }, "PopupTrigger": { "type": "object", "required": [ "type", "seconds", "percent" ], "properties": { "type": { "type": "string", "enum": [ "delay", "scroll", "exit" ], "description": "exit: about to leave (computers: the pointer leaves through the top of the window; phones: the back gesture, once)" }, "seconds": { "type": "integer", "description": "delay: seconds after the page loads; exit: also show on phones after this many seconds without activity (0: off, else 10-300)" }, "percent": { "type": "integer", "description": "scroll: how far down the page" } } }, "PopupTargeting": { "type": "object", "required": [ "pages", "visitors", "landings" ], "properties": { "pages": { "type": "array", "items": { "type": "string", "enum": [ "home", "product", "category", "landing", "other" ] }, "description": "Never checkout, payment, order or tracking pages" }, "visitors": { "type": "string", "enum": [ "all", "new", "returning" ] }, "landings": { "type": "array", "maxItems": 20, "items": { "type": "string", "format": "uuid" }, "description": "Only on these landing pages (funnels' sales pages); empty: every page of the kinds in pages. When set, pages is [landing]" } } }, "PopupFrequency": { "type": "object", "required": [ "mode", "days" ], "properties": { "mode": { "type": "string", "enum": [ "session", "days", "until_submit", "once" ], "description": "once: once per visitor (the default for exit offers)" }, "days": { "type": "integer" } } }, "LivePopup": { "type": "object", "required": [ "id", "kind", "content", "design", "trigger", "targeting", "frequency", "has_reward", "priority", "ends_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "signup", "announcement" ] }, "content": { "$ref": "#/components/schemas/PopupContent" }, "design": { "$ref": "#/components/schemas/PopupDesign" }, "trigger": { "$ref": "#/components/schemas/PopupTrigger" }, "targeting": { "$ref": "#/components/schemas/PopupTargeting" }, "frequency": { "$ref": "#/components/schemas/PopupFrequency" }, "has_reward": { "type": "boolean" }, "priority": { "type": "integer" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PopupSubmitInput": { "type": "object", "required": [ "contact", "consent" ], "properties": { "contact": { "type": "string", "description": "A Saudi mobile number or an email" }, "consent": { "type": "boolean" }, "locale": { "type": "string", "enum": [ "ar", "en" ] }, "website": { "type": "string", "description": "Honeypot: leave empty" } } }, "PopupSubmitResult": { "type": "object", "required": [ "code", "already" ], "properties": { "code": { "type": "string", "description": "The single-use code (empty when the popup gives none)" }, "already": { "type": "boolean", "description": "This contact signed up before; code is the one they got then" } } }, "PostPurchaseOffer": { "type": "object", "required": [ "offer_id", "stage", "headline", "product_slug", "title_ar", "title_en", "image_url", "discount_percent", "variants", "expires_at" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "stage": { "$ref": "#/components/schemas/UpsellStage" }, "headline": { "type": "string" }, "product_slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "image_url": { "type": "string" }, "discount_percent": { "type": "integer" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/UpsellVariant" } }, "expires_at": { "type": "string", "format": "date-time", "description": "When the order can no longer be changed" } } }, "PostPurchaseAnswer": { "type": "object", "required": [ "offer_id", "stage", "accept" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "stage": { "$ref": "#/components/schemas/UpsellStage" }, "accept": { "type": "boolean" }, "variant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when accepting" } } }, "LandingBenefit": { "type": "object", "required": [ "icon", "title", "body" ], "properties": { "icon": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" } } }, "LandingFeature": { "type": "object", "required": [ "image", "title", "body" ], "properties": { "image": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" } } }, "LandingFAQ": { "type": "object", "required": [ "q", "a" ], "properties": { "q": { "type": "string" }, "a": { "type": "string" } } }, "LandingGuarantee": { "type": "object", "required": [ "icon", "text" ], "properties": { "icon": { "type": "string" }, "text": { "type": "string" } } }, "LandingContent": { "type": "object", "required": [ "badge", "headline", "subheadline", "images", "video_url", "benefits", "features", "show_reviews", "review_images", "faq", "guarantees", "cta", "ends_at", "show_stock", "whatsapp_order", "blocks", "layout", "form" ], "properties": { "badge": { "type": "string" }, "headline": { "type": "string" }, "subheadline": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" }, "description": "Replace the product's photos; empty uses them" }, "video_url": { "type": "string" }, "benefits": { "type": "array", "items": { "$ref": "#/components/schemas/LandingBenefit" } }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/LandingFeature" } }, "show_reviews": { "type": "boolean", "description": "Show the product's real published reviews" }, "review_images": { "type": "array", "items": { "type": "string" }, "description": "Screenshots of customer messages" }, "faq": { "type": "array", "items": { "$ref": "#/components/schemas/LandingFAQ" } }, "guarantees": { "type": "array", "items": { "$ref": "#/components/schemas/LandingGuarantee" } }, "cta": { "type": "string" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "A real offer deadline; the page counts down to it" }, "show_stock": { "type": "boolean", "description": "Say \"only N left\" when real stock is low" }, "whatsapp_order": { "type": "boolean" }, "blocks": { "type": "array", "maxItems": 24, "items": { "$ref": "#/components/schemas/LandingBlock" }, "description": "The sections below the hero, in order. Pages saved before blocks get the default order" }, "layout": { "$ref": "#/components/schemas/LandingLayout" }, "form": { "$ref": "#/components/schemas/LandingFormSettings" } } }, "LandingFormSettings": { "type": "object", "description": "The page's own order-form choices on top of Settings → Checkout", "required": [ "hide_questions", "whatsapp_check" ], "properties": { "hide_questions": { "type": "array", "items": { "type": "string" }, "description": "Keys of the store's checkout questions this page doesn't ask (checkout doesn't require them for its orders)" }, "whatsapp_check": { "type": "boolean", "description": "Ask whether the phone number is on WhatsApp" } } }, "LandingBlockType": { "type": "string", "enum": [ "benefits", "video", "features", "reviews", "faq", "cta", "form", "text", "image", "before_after", "comparison", "steps", "in_box", "specs", "size_chart", "promise", "trust", "payments", "delivery", "ugc", "hotspots", "countdown", "stock", "sold" ], "description": "benefits, video, features, reviews, faq show the page's own lists; cta is the last call; form places the order form (layout.form end/both); countdown, stock and sold show real data only (the offer's end, real stock, real orders)" }, "LandingBlock": { "type": "object", "required": [ "id", "type", "icon", "title", "body", "image", "image2", "columns", "items" ], "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/LandingBlockType" }, "icon": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "image": { "type": "string", "description": "The block's picture (before_after: before; hotspots: the scene)" }, "image2": { "type": "string", "description": "before_after: the after picture" }, "columns": { "type": "array", "maxItems": 6, "items": { "type": "string" }, "description": "Table headings (comparison: ours, theirs; size_chart)" }, "items": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/LandingBlockItem" } } } }, "LandingBlockItem": { "type": "object", "required": [ "icon", "title", "body", "image", "video", "values", "x", "y", "product_id", "product_slug" ], "properties": { "icon": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "image": { "type": "string" }, "video": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" }, "description": "A table row's cells (comparison: yes/no per column)" }, "x": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Hotspot position in percent" }, "y": { "type": "integer", "minimum": 0, "maximum": 100 }, "product_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The product a hotspot shows" }, "product_slug": { "type": "string", "description": "Filled for the storefront" } } }, "LandingLayout": { "type": "object", "required": [ "form", "hero_video", "sticky_bar", "whatsapp_chat" ], "properties": { "form": { "type": "string", "enum": [ "hero", "end", "both", "popup" ], "description": "Where the order form is: beside the photos, at the end (the form block), both, or a pop-up every order button opens" }, "hero_video": { "type": "boolean", "description": "Play the page's video at the top instead of the photos" }, "sticky_bar": { "type": "boolean", "description": "A buy bar at the bottom of phones until the form is on screen" }, "whatsapp_chat": { "type": "boolean", "description": "A floating chat button to the store's WhatsApp number" } } }, "LandingOffer": { "type": "object", "required": [ "quantity", "price", "label", "badge", "free_shipping" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 10 }, "price": { "$ref": "#/components/schemas/Money", "description": "Total for that many pieces" }, "label": { "type": "string" }, "badge": { "type": "string" }, "free_shipping": { "type": "boolean" } } }, "LandingPublicAddon": { "type": "object", "required": [ "product_slug", "price", "label" ], "properties": { "product_slug": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "label": { "type": "string" } } }, "LandingPublic": { "type": "object", "required": [ "id", "slug", "style", "content", "offers", "addons", "product_slug", "preview", "live", "proof", "funnel_host" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "style": { "type": "string", "enum": [ "bold", "clean", "story" ] }, "content": { "$ref": "#/components/schemas/LandingContent" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/LandingOffer" } }, "addons": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPublicAddon" } }, "product_slug": { "type": "string" }, "preview": { "type": "boolean", "description": "A draft opened with its preview token" }, "live": { "type": "boolean", "description": "False while the funnel is paused or outside its schedule: send the visitor to the product page (nothing else is filled in)" }, "proof": { "type": "object", "description": "The product's real sales, for the sold and stock blocks (zero when the page shows neither)", "required": [ "sold_week", "sold_month" ], "properties": { "sold_week": { "type": "integer" }, "sold_month": { "type": "integer" } } }, "funnel_host": { "type": "string", "description": "The funnel's own live domain, which serves this page at / (its canonical address); empty when it has none" } } }, "FunnelThankYou": { "type": "object", "required": [ "headline", "body" ], "properties": { "headline": { "type": "string", "maxLength": 120, "description": "Empty: the store's thank-you" }, "body": { "type": "string", "maxLength": 600 } } }, "LandingCartInput": { "type": "object", "required": [ "lines" ], "properties": { "cart_token": { "type": "string", "description": "The landing cart to replace; empty starts one" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 } } } } } }, "CouponInput": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "CartContact": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "name": { "type": "string" }, "marketing_consent": { "type": "boolean", "description": "Reminders are only sent with consent" } } }, "AddCartItem": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 } } }, "SetQuantity": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 0 } } }, "Address": { "type": "object", "required": [ "city" ], "properties": { "city": { "type": "string" }, "district": { "type": "string" }, "street": { "type": "string" }, "building_number": { "type": "string" }, "additional_number": { "type": "string" }, "postal_code": { "type": "string" }, "short_address": { "type": "string", "description": "Saudi National Address short code, e.g. RRRD2929 (Saudi stores only)" }, "floor": { "type": "string", "description": "Egyptian stores: floor (الدور)" }, "apartment": { "type": "string", "description": "Egyptian stores: apartment (شقة)" }, "landmark": { "type": "string", "maxLength": 120, "description": "Egyptian stores: a well-known place near the door (علامة مميزة)" }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "notes": { "type": "string" } } }, "Customer": { "type": "object", "required": [ "name", "phone" ], "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } } }, "RecentPurchase": { "type": "object", "required": [ "product_slug", "title_ar", "title_en", "image_url", "city", "at" ], "properties": { "product_slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "image_url": { "type": "string" }, "city": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } }, "LiveSalesProof": { "type": "object", "required": [ "pages", "items" ], "properties": { "pages": { "type": "array", "items": { "type": "string" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecentPurchase" } } } }, "CheckoutField": { "type": "object", "required": [ "key", "label_ar", "type", "required" ], "properties": { "key": { "type": "string", "description": "Kept across edits; empty for a new question" }, "label_ar": { "type": "string", "maxLength": 60 }, "label_en": { "type": "string", "maxLength": 60 }, "type": { "type": "string", "enum": [ "text", "textarea", "select" ] }, "options": { "type": "array", "items": { "type": "string" }, "description": "select only: 2–20 choices" }, "required": { "type": "boolean" } } }, "FieldAnswer": { "type": "object", "required": [ "key", "label_ar", "label_en", "value" ], "properties": { "key": { "type": "string" }, "label_ar": { "type": "string" }, "label_en": { "type": "string" }, "value": { "type": "string" } } }, "CheckoutInput": { "type": "object", "required": [ "cart_token", "customer", "address", "shipping_method_id", "payment_method" ], "properties": { "card_prefix": { "type": "string", "pattern": "^[0-9]{6}$", "description": "First 6 digits of the card, for a bank's card offer. Never more of the card than this" }, "cart_token": { "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" }, "address": { "$ref": "#/components/schemas/Address" }, "shipping_method_id": { "type": "string", "format": "uuid" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "note": { "type": "string" }, "marketing_consent": { "type": "boolean", "description": "Explicit opt-in to offers and reminders (PDPL); never pre-ticked" }, "tracking": { "$ref": "#/components/schemas/CheckoutTracking" }, "passport_token": { "type": "string", "description": "The store's Passport link token, when the shopper used Passport" }, "account_token": { "type": "string", "description": "The shopper's session on the store's own account (ADR 0023), when signed in" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Answers to the store's checkout questions, by question key" }, "bot": { "type": "object", "description": "What the store's own order form saw, for the silent bot check. Other clients leave it out. A filled trap refuses the order.", "properties": { "trap": { "type": "string", "description": "A field people can't see; must stay empty" }, "form_ms": { "type": "integer", "description": "How long the form was open before it was sent, in milliseconds" } } }, "challenge_token": { "type": "string", "description": "The Cloudflare Turnstile token, after checkout answered 422 with fields.challenge (the widget's site key)" }, "phone_whatsapp": { "type": "boolean", "description": "The shopper's answer to \"is this number on WhatsApp?\" (a funnel's form can ask); leave out when not asked" } } }, "PaymentMethod": { "type": "string", "enum": [ "cod", "card", "stc_pay", "tabby", "tamara", "bank_transfer", "net_terms", "exchange" ], "description": "exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)" }, "OrderStatus": { "type": "string", "enum": [ "pending_confirmation", "pending_payment", "confirmed", "processing", "shipped", "delivered", "cancelled" ] }, "OrderItem": { "type": "object", "required": [ "id", "product_id", "variant_id", "title", "variant_title", "sku", "image_url", "unit_price", "quantity", "total" ], "properties": { "id": { "type": "string", "format": "uuid" }, "product_id": { "type": [ "string", "null" ], "format": "uuid" }, "variant_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": "string" }, "variant_title": { "type": "string" }, "sku": { "type": "string" }, "image_url": { "type": "string" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "quantity": { "type": "integer" }, "total": { "$ref": "#/components/schemas/Money" } } }, "OrderEvent": { "type": "object", "required": [ "type", "message", "actor", "created_at" ], "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "actor": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Shipment": { "type": "object", "required": [ "id", "carrier", "tracking_number", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "carrier": { "type": "string" }, "tracking_number": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Order": { "type": "object", "required": [ "id", "number", "token", "status", "payment_method", "payment_status", "currency", "subtotal", "shipping_total", "cod_fee", "discount_total", "discount_code", "recovered_from_cart", "vat_total", "total", "refunded_total", "deposit_amount", "via_passport", "loyalty_points", "loyalty_amount", "referral_amount", "offer_total", "upsell_total", "landing_page_id", "phone_whatsapp", "parent_order_id", "customer", "address", "shipping_method", "note", "custom_fields", "payment_discount", "bank_offer", "card_prefix", "paid_card_prefix", "bank_offer_mismatch", "cod_confirmed_at", "cod_reminders", "cod_expires_at", "address_confirmed_at", "delivery_window", "items", "shipments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "token": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "payment_status": { "type": "string", "enum": [ "unpaid", "deposit_paid", "paid", "refunded" ] }, "currency": { "type": "string" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "shipping_total": { "$ref": "#/components/schemas/Money" }, "cod_fee": { "$ref": "#/components/schemas/Money" }, "discount_total": { "$ref": "#/components/schemas/Money" }, "discount_code": { "type": "string" }, "recovered_from_cart": { "type": "boolean" }, "vat_total": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "refunded_total": { "$ref": "#/components/schemas/Money" }, "deposit_amount": { "$ref": "#/components/schemas/Money", "description": "Partial COD: paid online before shipping; the rest on delivery" }, "via_passport": { "type": "boolean", "description": "Placed with a Nouq Passport (verified phone)" }, "loyalty_points": { "type": "integer", "description": "Points spent on the order" }, "loyalty_amount": { "$ref": "#/components/schemas/Money", "description": "What the points took off (also in discount_total)" }, "referral_amount": { "$ref": "#/components/schemas/Money", "description": "Friend-referral discount (also in discount_total)" }, "offer_total": { "$ref": "#/components/schemas/Money", "description": "A landing page's quantity offer (also in discount_total)" }, "upsell_total": { "$ref": "#/components/schemas/Money", "description": "What cross-sell and post-purchase offers took off (also in discount_total)" }, "landing_page_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The landing page the order came from" }, "phone_whatsapp": { "type": [ "boolean", "null" ], "description": "Whether the shopper said their number is on WhatsApp (null: not asked)" }, "parent_order_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The order this one ships with: an after-order offer accepted on a paid card order becomes its own small order, paid on its own" }, "customer": { "$ref": "#/components/schemas/Customer" }, "address": { "$ref": "#/components/schemas/Address" }, "shipping_method": { "type": "string" }, "note": { "type": "string" }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldAnswer" }, "description": "Answers to the store's checkout questions" }, "payment_discount": { "$ref": "#/components/schemas/Money", "description": "What paying this way took off (also in discount_total)" }, "bank_offer": { "type": "string", "description": "The bank whose card offer the order took (its amount is in payment_discount)" }, "card_prefix": { "type": "string", "description": "First 6 digits the shopper gave for that offer" }, "paid_card_prefix": { "type": "string", "description": "First 6 digits of the card the gateway reports paid (empty: not reported yet)" }, "bank_offer_mismatch": { "type": "boolean", "description": "The card that paid isn't in the offer" }, "cod_confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cod_reminders": { "type": "integer", "description": "Confirmation reminders sent (COD)" }, "cod_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When an unconfirmed COD order cancels itself" }, "address_confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivery_window": { "type": "string", "enum": [ "", "morning", "afternoon", "evening" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OrderEvent" }, "description": "Merchant view only" }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatus" }, "description": "Merchant view only" } } }, "CODAnswer": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean" }, "address": { "$ref": "#/components/schemas/AddressConfirmation" } } }, "AddressConfirmation": { "type": "object", "description": "What the shopper confirms about delivery when confirming a COD order; empty fields keep checkout's.", "properties": { "short_address": { "type": "string", "description": "National Address short code, e.g. RRRD2929 (Saudi stores only)" }, "landmark": { "type": "string", "maxLength": 120, "description": "Egyptian stores: a well-known place near the door (علامة مميزة)" }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "notes": { "type": "string", "maxLength": 200 }, "delivery_window": { "type": "string", "enum": [ "", "morning", "afternoon", "evening" ] } } }, "Payment": { "type": "object", "required": [ "id", "provider", "status", "amount", "currency", "order_token", "order_number" ], "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "method": { "$ref": "#/components/schemas/PaymentMethod" }, "status": { "type": "string", "enum": [ "initiated", "paid", "failed" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "order_token": { "type": "string" }, "order_number": { "type": "integer" }, "redirect_url": { "type": "string" }, "reference": { "type": "string", "description": "Still pending: a code the shopper pays offline (a Fawry reference at a kiosk)" } } }, "InvoiceKind": { "type": "string", "enum": [ "invoice", "credit_note" ] }, "InvoiceZatcaStatus": { "type": "string", "enum": [ "unsigned", "pending", "reported", "cleared", "warning", "rejected", "local" ], "description": "cleared: a standard (B2B) document cleared by ZATCA; local: an Egyptian store's invoice, which never goes to ZATCA" }, "InvoiceBuyer": { "type": "object", "required": [ "legal_name", "vat_number", "cr_number", "street", "building_number", "district", "city", "postal_code" ], "properties": { "legal_name": { "type": "string" }, "vat_number": { "type": "string" }, "cr_number": { "type": "string" }, "street": { "type": "string" }, "building_number": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" } } }, "InvoiceSeller": { "type": "object", "required": [ "legal_name", "vat_number", "cr_number", "street", "building_number", "district", "city", "postal_code" ], "properties": { "legal_name": { "type": "string" }, "vat_number": { "type": "string" }, "cr_number": { "type": "string" }, "street": { "type": "string" }, "building_number": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" } } }, "InvoiceTotals": { "type": "object", "description": "Tax-exclusive figures exactly as in the document's XML (minor units).", "required": [ "lines", "line_extension", "allowance", "tax_exclusive", "tax", "tax_inclusive", "rounding", "payable" ], "properties": { "lines": { "type": "array", "items": { "type": "object", "required": [ "name", "quantity", "unit_net", "net", "tax", "total_incl" ], "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_net": { "type": "integer", "format": "int64" }, "net": { "type": "integer", "format": "int64" }, "tax": { "type": "integer", "format": "int64" }, "total_incl": { "type": "integer", "format": "int64" } } } }, "line_extension": { "type": "integer", "format": "int64" }, "allowance": { "type": "integer", "format": "int64" }, "tax_exclusive": { "type": "integer", "format": "int64" }, "tax": { "type": "integer", "format": "int64" }, "tax_inclusive": { "type": "integer", "format": "int64" }, "rounding": { "type": "integer", "format": "int64" }, "payable": { "type": "integer", "format": "int64" }, "tax_sar": { "type": "integer", "format": "int64", "description": "The VAT total in halalas, on a Saudi tax invoice in another currency (US dollars at the 3.75 peg)" } } }, "Invoice": { "type": "object", "required": [ "id", "order_id", "kind", "number", "uuid", "icv", "signed", "currency", "taxable_total", "vat_total", "total", "vat_rate_bp", "issued_at", "reason", "billing_ref", "seller", "buyer_name", "standard", "buyer", "totals", "qr", "zatca_status", "zatca_messages", "reported_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid", "nullable": true }, "kind": { "$ref": "#/components/schemas/InvoiceKind" }, "number": { "type": "string", "example": "INV-1001" }, "uuid": { "type": "string", "format": "uuid" }, "icv": { "type": "integer", "format": "int64" }, "signed": { "type": "boolean", "description": "false for Phase-1 documents (store not onboarded with ZATCA)" }, "currency": { "type": "string" }, "taxable_total": { "type": "integer", "format": "int64" }, "vat_total": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" }, "vat_rate_bp": { "type": "integer" }, "issued_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "billing_ref": { "type": "string", "description": "Credit notes: the original invoice number" }, "seller": { "$ref": "#/components/schemas/InvoiceSeller" }, "buyer_name": { "type": "string" }, "standard": { "type": "boolean", "description": "A standard (B2B) tax invoice, cleared by ZATCA" }, "buyer": { "oneOf": [ { "$ref": "#/components/schemas/InvoiceBuyer" }, { "type": "null" } ], "description": "The business the document was issued to" }, "totals": { "$ref": "#/components/schemas/InvoiceTotals" }, "qr": { "type": "string", "description": "Base64 TLV payload the QR code encodes" }, "zatca_status": { "$ref": "#/components/schemas/InvoiceZatcaStatus" }, "zatca_messages": { "type": "array", "items": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "reported_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ThemeDocument": { "type": "object", "additionalProperties": true, "description": "Shape owned by frontend/packages/templates (ThemeDoc). The API validates the envelope only." }, "Occasions": { "type": "object", "required": [ "auto", "disabled", "forced" ], "properties": { "auto": { "type": "boolean" }, "disabled": { "type": "array", "items": { "type": "string" } }, "forced": { "type": [ "string", "null" ] } } }, "StorefrontTheme": { "type": "object", "required": [ "document", "occasions", "preview" ], "properties": { "document": { "oneOf": [ { "$ref": "#/components/schemas/ThemeDocument" }, { "type": "null" } ] }, "occasions": { "$ref": "#/components/schemas/Occasions" }, "preview": { "type": "boolean" }, "package_css": { "type": "string", "description": "Scoped CSS of a marketplace template the store is entitled to" } } }, "SEOSettings": { "type": "object", "required": [ "google_verification", "bing_verification" ], "properties": { "google_verification": { "type": "string", "description": "The content of Google's site-verification meta tag (the whole tag is accepted on save)" }, "bing_verification": { "type": "string" } } }, "SEO": { "type": "object", "required": [ "title", "description", "image" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" } } }, "PageKind": { "type": "string", "enum": [ "custom", "about", "contact", "privacy", "returns", "shipping", "terms" ] }, "StorePage": { "type": "object", "required": [ "id", "slug", "title", "body", "kind", "published", "seo", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string", "description": "Markdown subset" }, "kind": { "$ref": "#/components/schemas/PageKind" }, "published": { "type": "boolean" }, "seo": { "$ref": "#/components/schemas/SEO" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BlogPost": { "type": "object", "required": [ "id", "slug", "title", "excerpt", "body", "cover_url", "category", "author", "status", "published_at", "seo", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "string" }, "cover_url": { "type": "string" }, "category": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "seo": { "$ref": "#/components/schemas/SEO" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BlogPostPage": { "type": "object", "required": [ "items", "total", "page", "per_page", "categories" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPost" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "required": [ "name", "posts" ], "properties": { "name": { "type": "string" }, "posts": { "type": "integer" } } } } } }, "SubscribeInput": { "type": "object", "required": [ "contact", "consent" ], "properties": { "contact": { "type": "string", "description": "Email or Saudi mobile number" }, "consent": { "type": "boolean" } } }, "ReturnStatus": { "type": "string", "enum": [ "requested", "approved", "rejected", "received", "refunded", "exchanged" ] }, "ReturnReason": { "type": "string", "enum": [ "wrong_size", "damaged", "not_as_described", "wrong_item", "changed_mind", "other" ] }, "ReturnResolution": { "type": "string", "enum": [ "refund", "exchange" ] }, "PublicReview": { "type": "object", "required": [ "id", "author_name", "rating", "body", "photos", "verified", "reply", "replied_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "author_name": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "body": { "type": "string" }, "photos": { "type": "array", "items": { "type": "string" } }, "verified": { "type": "boolean", "description": "Written from a delivered order" }, "reply": { "type": "string", "description": "The store's public answer" }, "replied_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "RatingSummary": { "type": "object", "required": [ "count", "average", "distribution" ], "properties": { "count": { "type": "integer" }, "average": { "type": "number" }, "distribution": { "type": "array", "items": { "type": "integer" }, "minItems": 5, "maxItems": 5, "description": "Published reviews per star, 5 stars first" } } }, "StoreReviews": { "type": "object", "required": [ "count", "average", "items" ], "properties": { "count": { "type": "integer", "description": "Every published review in the store" }, "average": { "type": "number" }, "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/PublicReview" }, { "type": "object", "required": [ "product" ], "properties": { "product": { "oneOf": [ { "type": "object", "required": [ "slug", "title_ar", "title_en", "image_url" ], "properties": { "slug": { "type": "string" }, "title_ar": { "type": "string" }, "title_en": { "type": "string" }, "image_url": { "type": "string" } } }, { "type": "null" } ], "description": "Null when the product is no longer on sale" } } } ] } } } }, "ProductReviews": { "type": "object", "required": [ "summary", "items", "page", "per_page" ], "properties": { "summary": { "$ref": "#/components/schemas/RatingSummary" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicReview" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "ReviewForm": { "type": "object", "required": [ "allowed", "why", "name", "items" ], "properties": { "allowed": { "type": "boolean" }, "why": { "type": "string", "description": "Shopper-facing reason when not allowed" }, "name": { "type": "string", "description": "Suggested display name (first name and initial)" }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "title", "image_url", "review" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "image_url": { "type": "string" }, "review": { "oneOf": [ { "$ref": "#/components/schemas/PublicReview" }, { "type": "null" } ] } } } } } }, "ReviewSubmit": { "type": "object", "required": [ "reviews" ], "properties": { "name": { "type": "string", "description": "Display name; empty uses the suggested one" }, "reviews": { "type": "array", "items": { "type": "object", "required": [ "product_id", "rating" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "body": { "type": "string", "maxLength": 2000 } } } } } }, "ReturnSettings": { "type": "object", "required": [ "enabled", "window_days", "exchanges", "policy" ], "properties": { "enabled": { "type": "boolean" }, "window_days": { "type": "integer", "minimum": 1, "maximum": 90 }, "exchanges": { "type": "boolean" }, "policy": { "type": "string" } } }, "ReturnItem": { "type": "object", "required": [ "order_item_id", "title", "variant_title", "image_url", "unit_price", "quantity", "exchange_variant_id", "exchange_title" ], "properties": { "order_item_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "variant_title": { "type": "string" }, "image_url": { "type": "string" }, "unit_price": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer" }, "exchange_variant_id": { "type": "string", "format": "uuid", "nullable": true }, "exchange_title": { "type": "string" }, "exchange_price": { "type": "integer", "format": "int64" } } }, "Return": { "type": "object", "required": [ "id", "number", "order_id", "order_number", "status", "resolution", "reason", "note", "photos", "merchant_note", "restocked", "refund_amount", "refund_method", "suggested_refund", "max_refund", "exchange_order_id", "payment_method", "customer_name", "customer_phone", "currency", "items", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "order_id": { "type": "string", "format": "uuid" }, "order_number": { "type": "integer" }, "status": { "$ref": "#/components/schemas/ReturnStatus" }, "resolution": { "$ref": "#/components/schemas/ReturnResolution" }, "reason": { "$ref": "#/components/schemas/ReturnReason" }, "note": { "type": "string" }, "photos": { "type": "array", "items": { "type": "string" } }, "merchant_note": { "type": "string" }, "restocked": { "type": "boolean" }, "refund_amount": { "type": "integer", "format": "int64" }, "refund_method": { "type": "string", "description": "card | manual" }, "suggested_refund": { "type": "integer", "format": "int64", "description": "Items' value after the order's discount" }, "max_refund": { "type": "integer", "format": "int64", "description": "What's left to refund on the order" }, "exchange_order_id": { "type": "string", "format": "uuid", "nullable": true }, "price_difference": { "type": "integer", "format": "int64", "description": "Exchange only: positive = the shopper pays it, negative = refunded to them" }, "payment_method": { "type": "string" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "currency": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnItem" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ReturnEligibility": { "type": "object", "required": [ "allowed", "why_not", "deadline", "policy", "exchanges", "items", "returns" ], "properties": { "allowed": { "type": "boolean" }, "why_not": { "type": "string" }, "deadline": { "type": "string", "format": "date-time", "nullable": true }, "policy": { "type": "string" }, "exchanges": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "required": [ "order_item_id", "title", "variant_title", "image_url", "unit_price", "ordered", "returnable", "exchange_options" ], "properties": { "order_item_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "variant_title": { "type": "string" }, "image_url": { "type": "string" }, "unit_price": { "type": "integer", "format": "int64" }, "ordered": { "type": "integer" }, "returnable": { "type": "integer" }, "exchange_options": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "in_stock", "price", "difference" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "in_stock": { "type": "boolean" }, "price": { "type": "integer", "format": "int64" }, "difference": { "type": "integer", "format": "int64", "description": "Its price minus what was paid per item" } } } } } } }, "returns": { "type": "array", "items": { "$ref": "#/components/schemas/Return" } } } }, "ReturnRequestInput": { "type": "object", "required": [ "items", "resolution", "reason" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "order_item_id", "quantity" ], "properties": { "order_item_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer" }, "exchange_variant_id": { "type": "string", "format": "uuid", "nullable": true } } } }, "resolution": { "$ref": "#/components/schemas/ReturnResolution" }, "reason": { "$ref": "#/components/schemas/ReturnReason" }, "note": { "type": "string" } } }, "PixelsFired": { "type": "object", "description": "One event the browser sent to pixels (after consent; no visitor ids).", "required": [ "event" ], "properties": { "event": { "type": "string", "enum": [ "page_view", "view_item", "add_to_cart", "begin_checkout", "purchase" ] }, "event_id": { "type": "string" }, "pixels": { "type": "array", "items": { "type": "string" }, "description": "The pixels it reached, as \"platform:id\"." }, "foreign": { "type": "array", "items": { "type": "string" }, "description": "Platforms whose code something else had already loaded on the page." } } }, "PublicPixel": { "type": "object", "required": [ "platform", "id", "events", "everywhere", "product_ids", "landing_ids" ], "properties": { "platform": { "type": "string", "enum": [ "meta", "tiktok", "snap", "x", "pinterest" ] }, "id": { "type": "string" }, "events": { "type": "object", "additionalProperties": { "type": "string" }, "description": "X: the event id for each event." }, "everywhere": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "landing_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "PixelConfig": { "type": "object", "required": [ "pixels", "ga4_measurement_id", "gads_id", "gads_label", "gads_enhanced", "consent_banner", "ga4_server_purchase" ], "properties": { "pixels": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPixel" }, "description": "Meta", "TikTok": null, "Snapchat": null, "X and Pinterest pixels with where each runs.": null }, "ga4_measurement_id": { "type": "string" }, "gads_id": { "type": "string" }, "gads_label": { "type": "string" }, "gads_enhanced": { "type": "boolean", "description": "Google Ads enhanced conversions: give gtag the shopper's email and phone on purchase." }, "consent_banner": { "type": "boolean", "description": "Ask shoppers before loading ad pixels." }, "ga4_server_purchase": { "type": "boolean", "description": "Purchases reach GA4 from the server; the page must not send its own." } } }, "TrackEvent": { "type": "object", "description": "One storefront event. Sent by the storefront's server, which adds the shopper's client details.", "required": [ "visitor_id", "session_id", "type" ], "properties": { "visitor_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "page_view", "view_item", "add_to_cart", "begin_checkout" ] }, "event_id": { "type": "string", "description": "Shared with the browser pixels so platforms count the event once." }, "url": { "type": "string" }, "referrer": { "type": "string" }, "product_id": { "type": "string", "format": "uuid", "nullable": true }, "variant_id": { "type": "string", "format": "uuid", "nullable": true }, "landing_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The landing page the event happened on." }, "quantity": { "type": "integer" }, "cart_token": { "type": "string" }, "consent": { "type": "string", "enum": [ "granted", "denied", "" ] }, "client": { "$ref": "#/components/schemas/TrackClient" } } }, "TrackClient": { "type": "object", "properties": { "ip": { "type": "string" }, "user_agent": { "type": "string" }, "fbp": { "type": "string" }, "fbc": { "type": "string" }, "ttp": { "type": "string" }, "scid": { "type": "string" }, "ga": { "type": "string" }, "epik": { "type": "string", "description": "Pinterest's click id cookie (_epik)." } } }, "CheckoutTracking": { "type": "object", "description": "Attribution and ad consent for a checkout; written with the order.", "properties": { "visitor_id": { "type": "string", "format": "uuid", "nullable": true }, "session_id": { "type": "string", "format": "uuid", "nullable": true }, "touch": { "type": "object", "nullable": true, "description": "The last non-direct landing within 30 days.", "properties": { "url": { "type": "string" }, "referrer": { "type": "string" } } }, "consent": { "type": "string" }, "host": { "type": "string" }, "client": { "$ref": "#/components/schemas/TrackClient" } } }, "BankAccount": { "type": "object", "required": [ "bank", "holder", "iban" ], "properties": { "bank": { "type": "string" }, "holder": { "type": "string" }, "iban": { "type": "string" } } }, "CardBankOffer": { "type": "object", "required": [ "bank", "percent", "max_discount", "min_subtotal", "bins" ], "properties": { "bank": { "type": "string" }, "percent": { "type": "integer" }, "max_discount": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "min_subtotal": { "$ref": "#/components/schemas/Money" }, "bins": { "type": "array", "items": { "type": "string" }, "description": "Six-digit card prefixes" } } }, "PaymentOption": { "type": "object", "required": [ "method", "available" ], "properties": { "method": { "$ref": "#/components/schemas/PaymentMethod" }, "available": { "type": "boolean" }, "reason": { "type": "string" }, "installments": { "type": "integer" }, "installment": { "$ref": "#/components/schemas/Money" }, "min": { "$ref": "#/components/schemas/Money" }, "max": { "$ref": "#/components/schemas/Money" }, "gateway": { "type": "string", "description": "Online methods: the gateway that takes it (moyasar, tap, paymob, or dev for the local simulator)" }, "discount_percent": { "type": "integer", "description": "Whole percent off the products for paying this way" }, "bank_offers": { "type": "array", "items": { "$ref": "#/components/schemas/CardBankOffer" }, "description": "card only: discounts for cards of certain banks" } } }, "PaymentMethods": { "type": "object", "required": [ "options", "bank_accounts", "bank_transfer_hours" ], "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOption" } }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } }, "bank_transfer_hours": { "type": "integer" } } }, "TransferReceipt": { "type": "object", "required": [ "id", "order_id", "content_type", "note", "status", "reject_reason", "created_at", "decided_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid" }, "content_type": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "reject_reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TransferInfo": { "type": "object", "required": [ "amount", "currency", "accounts", "deadline", "state", "receipts" ], "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } }, "deadline": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "awaiting", "review", "paid", "cancelled" ] }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/TransferReceipt" } } } }, "PassportAddress": { "type": "object", "required": [ "id", "label", "address", "is_default" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "is_default": { "type": "boolean" } } }, "PassportCard": { "type": "object", "required": [ "id", "brand", "last4", "expires" ], "properties": { "id": { "type": "string", "format": "uuid" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "expires": { "type": "string" } } }, "ShopperAccount": { "type": "object", "description": "A shopper's account on one store (ADR 0023).", "required": [ "id", "email", "name", "phone", "email_verified", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email_verified": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "ShopperSession": { "type": "object", "required": [ "token", "expires_at", "account" ], "properties": { "token": { "type": "string", "description": "Kept by the store's server in an httpOnly cookie on its own domain" }, "expires_at": { "type": "string", "format": "date-time" }, "account": { "$ref": "#/components/schemas/ShopperAccount" } } }, "ShopperCodeSent": { "type": "object", "required": [ "email", "expires_in" ], "properties": { "email": { "type": "string" }, "expires_in": { "type": "integer" }, "dev_code": { "type": "string", "description": "Local development only" } } }, "ShopperOrder": { "type": "object", "required": [ "number", "token", "status", "payment_status", "total", "currency", "created_at", "item_count", "image_url" ], "properties": { "number": { "type": "integer" }, "token": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "total": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "item_count": { "type": "integer" }, "image_url": { "type": "string" } } }, "PassportStoreProfile": { "type": "object", "description": "What a connected store sees (only the granted scopes; cards without tokens)", "required": [ "passport_id", "name", "phone", "email", "addresses", "sizes", "cards", "scopes" ], "properties": { "passport_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/PassportAddress" } }, "sizes": { "type": "object", "additionalProperties": { "type": "string" } }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/PassportCard" } }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "RewardPrograms": { "type": "object", "required": [ "loyalty", "referral", "phone_codes" ], "properties": { "phone_codes": { "type": "boolean", "description": "Codes can be sent to phones (PHONE_CODES): offer spending points by phone code, and Nouq Passport" }, "loyalty": { "type": "object", "required": [ "enabled", "earn_rate", "point_value", "min_redeem", "max_redeem_pct" ], "properties": { "enabled": { "type": "boolean" }, "earn_rate": { "type": "integer" }, "point_value": { "type": "integer" }, "min_redeem": { "type": "integer" }, "max_redeem_pct": { "type": "integer" } } }, "referral": { "type": "object", "required": [ "enabled", "friend_amount", "min_subtotal", "referrer_amount" ], "properties": { "enabled": { "type": "boolean" }, "friend_amount": { "$ref": "#/components/schemas/Money" }, "min_subtotal": { "$ref": "#/components/schemas/Money" }, "referrer_amount": { "$ref": "#/components/schemas/Money" } } } } }, "CartRewards": { "type": "object", "required": [ "loyalty", "referral" ], "properties": { "loyalty": { "oneOf": [ { "type": "object", "required": [ "phone", "points", "amount", "balance", "max_points" ], "properties": { "phone": { "type": "string" }, "points": { "type": "integer" }, "amount": { "$ref": "#/components/schemas/Money" }, "balance": { "type": "integer" }, "max_points": { "type": "integer", "description": "The most this cart can take" }, "note": { "type": "string", "description": "Why fewer points apply than chosen" } } }, { "type": "null" } ] }, "referral": { "oneOf": [ { "type": "object", "required": [ "code", "amount", "referrer_name", "min_subtotal" ], "properties": { "code": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "referrer_name": { "type": "string" }, "min_subtotal": { "$ref": "#/components/schemas/Money" }, "stale": { "type": "string", "enum": [ "coupon", "min_subtotal" ], "description": "Why it doesn't apply right now" } } }, { "type": "null" } ] } } }, "LoyaltyTier": { "type": "object", "required": [ "key", "name_ar", "name_en", "min_spent", "multiplier_pct" ], "properties": { "key": { "type": "string" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "min_spent": { "$ref": "#/components/schemas/Money" }, "multiplier_pct": { "type": "integer", "description": "100 = ×1" } } }, "LoyaltyAccount": { "type": "object", "required": [ "customer_id", "balance", "value", "earned_total", "redeemed_total", "spent_total", "tier", "next_tier", "to_next_tier", "last_activity_at", "expires_at" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "balance": { "type": "integer" }, "value": { "$ref": "#/components/schemas/Money" }, "earned_total": { "type": "integer" }, "redeemed_total": { "type": "integer" }, "spent_total": { "$ref": "#/components/schemas/Money" }, "tier": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyTier" }, { "type": "null" } ] }, "next_tier": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyTier" }, { "type": "null" } ] }, "to_next_tier": { "$ref": "#/components/schemas/Money" }, "last_activity_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ReferralLink": { "type": "object", "required": [ "valid", "referrer_name", "friend_amount", "min_subtotal" ], "properties": { "valid": { "type": "boolean" }, "referrer_name": { "type": "string" }, "friend_amount": { "$ref": "#/components/schemas/Money" }, "min_subtotal": { "$ref": "#/components/schemas/Money" } } }, "OrderRewards": { "type": "object", "required": [ "loyalty", "referral" ], "properties": { "loyalty": { "oneOf": [ { "type": "object", "required": [ "earned", "pending", "spent", "account", "point_value" ], "properties": { "earned": { "type": "integer" }, "pending": { "type": "integer", "description": "What the order earns once delivered" }, "spent": { "type": "integer" }, "account": { "$ref": "#/components/schemas/LoyaltyAccount" }, "point_value": { "type": "integer" } } }, { "type": "null" } ] }, "referral": { "oneOf": [ { "type": "object", "required": [ "code", "path", "friend_amount", "min_subtotal", "referrer_amount", "referrer_reward", "invited", "rewarded" ], "properties": { "code": { "type": "string" }, "path": { "type": "string" }, "friend_amount": { "$ref": "#/components/schemas/Money" }, "min_subtotal": { "$ref": "#/components/schemas/Money" }, "referrer_amount": { "$ref": "#/components/schemas/Money" }, "referrer_reward": { "type": "string", "enum": [ "coupon", "points" ] }, "invited": { "type": "integer" }, "rewarded": { "type": "integer" } } }, { "type": "null" } ] } } }, "UseLoyaltyInput": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "code": { "type": "string", "description": "WhatsApp code; not needed when the phone is already proven on the cart or by Passport" }, "points": { "type": "integer", "description": "0 spends as many as the cart allows" } } }, "PriceTier": { "type": "object", "required": [ "min_qty", "price" ], "properties": { "min_qty": { "type": "integer" }, "price": { "$ref": "#/components/schemas/Money" } } }, "CartBusiness": { "type": "object", "required": [ "account_id", "company_name", "terms_days", "credit_available", "min_order", "below_minimum", "quotes_enabled", "quote_id", "quote_number", "savings" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "company_name": { "type": "string" }, "terms_days": { "type": "integer", "description": "Days to pay on credit terms (0: pays at checkout)" }, "credit_available": { "$ref": "#/components/schemas/Money" }, "min_order": { "$ref": "#/components/schemas/Money" }, "below_minimum": { "type": "boolean" }, "quotes_enabled": { "type": "boolean" }, "quote_id": { "type": [ "string", "null" ], "format": "uuid" }, "quote_number": { "type": "integer" }, "savings": { "$ref": "#/components/schemas/Money", "description": "What the same pieces cost more at retail" } } }, "BusinessAddress": { "type": "object", "required": [ "street", "building_number", "district", "city", "postal_code" ], "properties": { "street": { "type": "string" }, "building_number": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" } } }, "BusinessAccountStatus": { "type": "string", "enum": [ "pending", "approved", "rejected", "suspended" ] }, "BusinessAccount": { "type": "object", "required": [ "id", "phone", "company_name", "vat_number", "cr_number", "contact_name", "email", "address", "buyer_store_id", "buyer_store", "status", "terms_days", "credit_limit", "note", "created_at", "decided_at", "orders", "sales", "open_balance", "overdue" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phone": { "type": "string" }, "company_name": { "type": "string" }, "vat_number": { "type": "string" }, "cr_number": { "type": "string" }, "contact_name": { "type": "string" }, "email": { "type": "string" }, "address": { "$ref": "#/components/schemas/BusinessAddress" }, "buyer_store_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The Nouq store behind the account (merchant to merchant)" }, "buyer_store": { "type": "string" }, "status": { "$ref": "#/components/schemas/BusinessAccountStatus" }, "terms_days": { "type": "integer" }, "credit_limit": { "$ref": "#/components/schemas/Money" }, "note": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "orders": { "type": "integer" }, "sales": { "$ref": "#/components/schemas/Money" }, "open_balance": { "$ref": "#/components/schemas/Money" }, "overdue": { "$ref": "#/components/schemas/Money" } } }, "BusinessAccountInput": { "type": "object", "required": [ "company_name" ], "properties": { "phone": { "type": "string", "description": "Adding an account only" }, "company_name": { "type": "string" }, "vat_number": { "type": "string" }, "cr_number": { "type": "string" }, "contact_name": { "type": "string" }, "email": { "type": "string" }, "address": { "$ref": "#/components/schemas/BusinessAddress" }, "status": { "$ref": "#/components/schemas/BusinessAccountStatus" }, "terms_days": { "type": "integer" }, "credit_limit": { "$ref": "#/components/schemas/Money" }, "note": { "type": "string" }, "buyer_store_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Applying: as this Nouq store (one the verified phone runs)" } } }, "QuoteStatus": { "type": "string", "enum": [ "requested", "sent", "accepted", "declined", "ordered", "expired" ] }, "QuoteSummary": { "type": "object", "required": [ "id", "number", "account_id", "company_name", "status", "total", "pieces", "valid_until", "sent_at", "order_id", "created_at", "token" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "account_id": { "type": "string", "format": "uuid" }, "company_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/QuoteStatus" }, "total": { "$ref": "#/components/schemas/Money" }, "pieces": { "type": "integer" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "order_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "token": { "type": "string", "description": "The buyer's link token (merchant views only)" } } }, "QuoteLine": { "type": "object", "required": [ "variant_id", "title", "variant_title", "quantity", "unit_price", "list_price", "total" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "variant_title": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "list_price": { "$ref": "#/components/schemas/Money", "description": "The tier price for the same quantity" }, "total": { "$ref": "#/components/schemas/Money" } } }, "Quote": { "allOf": [ { "$ref": "#/components/schemas/QuoteSummary" }, { "type": "object", "required": [ "buyer_note", "merchant_note", "lines", "list_total", "link", "store_name", "currency" ], "properties": { "buyer_note": { "type": "string" }, "merchant_note": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteLine" } }, "list_total": { "$ref": "#/components/schemas/Money" }, "link": { "type": "string", "description": "The buyer's page for the quote" }, "store_name": { "type": "string" }, "currency": { "type": "string" } } } ] }, "WholesaleOrderLine": { "type": "object", "required": [ "order_id", "number", "status", "payment_method", "credit", "amount", "paid", "due_at", "receivable", "created_at" ], "properties": { "order_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "credit": { "type": "boolean" }, "amount": { "$ref": "#/components/schemas/Money" }, "paid": { "$ref": "#/components/schemas/Money" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "receivable": { "type": "string", "enum": [ "open", "paid", "void", "prepaid" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "BusinessPrefill": { "type": "object", "required": [ "store_id", "store_name", "company_name", "vat_number", "cr_number", "address" ], "properties": { "store_id": { "type": "string", "format": "uuid" }, "store_name": { "type": "string" }, "company_name": { "type": "string" }, "vat_number": { "type": "string" }, "cr_number": { "type": "string" }, "address": { "$ref": "#/components/schemas/BusinessAddress" } } }, "BusinessMe": { "type": "object", "required": [ "enabled", "pitch", "min_order", "quotes_enabled", "phone", "account", "credit_available", "prefill", "orders", "quotes" ], "properties": { "enabled": { "type": "boolean" }, "pitch": { "type": "string" }, "min_order": { "$ref": "#/components/schemas/Money" }, "quotes_enabled": { "type": "boolean" }, "phone": { "type": "string", "description": "The verified phone (\"\" when signed out)" }, "account": { "oneOf": [ { "$ref": "#/components/schemas/BusinessAccount" }, { "type": "null" } ] }, "credit_available": { "$ref": "#/components/schemas/Money" }, "prefill": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPrefill" }, "description": "Nouq stores the phone runs", "offered as the applying business": null }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/WholesaleOrderLine" } }, "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteSummary" } } } }, "VariantTiers": { "type": "object", "required": [ "variant_id", "tiers" ], "properties": { "variant_id": { "type": "string", "format": "uuid" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/PriceTier" } } } } } } }