{ "info": { "_postman_id": "a3d1e9c2-9b2f-4e3a-8c7a-2f0a6d5b1e10", "name": "Linra Omni — Partner API", "description": "The Linra Omni partner-facing API, reached through the partner Gateway's `/api/v1` facade. Generated from `src/DeveloperPortal/developer-portal-web/openapi/openapi.source.yaml` and the partner Gateway route table (`src/ApiGateway/Linra.Omni.Gateway/appsettings.json`), structured to mirror the [developer docs](https://developers-omni.linra.net) navigation: Platform (Authentication, Wallet, Billing, Commission Periods) then Scent (Orders, Returns, Webhooks, Reports, Catalog, Cart, Wishlist, Stock Notify, Unfulfillable Notices, Discount Codes).\n\nImport the sibling environment file, fill in `clientId`/`clientSecret`, run **Platform > Authentication > Exchange a client ID and secret for an access token** once, and every other request will authenticate automatically via the collection-level Bearer auth referencing `{{accessToken}}`.\n\nThe order surface (`Scent > Orders`) is product-first (`/api/v1/scent/orders/**`), matching the partner Gateway route table (`orders-v1-route`) — the old orders-first `/api/v1/orders/**` / `/api/v1/orders/scent` shape is retired for the partner plane. `Orders` and `Returns` are grouped together under `Scent` since both are now product-first Scent resources.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{accessToken}}", "type": "string" } ] }, "event": [], "variable": [], "item": [ { "name": "Platform", "item": [ { "name": "Authentication", "item": [ { "name": "Exchange a client ID and secret for an access token", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/auth/token", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "auth", "token" ] }, "description": "**Exchange a client ID and secret for an access token**\n\nThe credential-exchange door. Anonymous — no bearer token is required (you don't have one\nyet). Rate-limited independently of every other route (see the Rate limits guide).\nReturns a JWT (audience `partner-api`) valid for 5 minutes; see the Authentication guide\nfor the recommended caching pattern.\n\n_Anonymous endpoint — no bearer token required._", "body": { "mode": "raw", "raw": "{\n \"clientId\": \"{{clientId}}\",\n \"clientSecret\": \"{{clientSecret}}\"\n}", "options": { "raw": { "language": "json" } } }, "auth": { "type": "noauth" } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Auto-extracts the access token from the ApiResponse envelope and stores it in the", "// environment so every other request (collection/folder-level Bearer auth) works immediately.", "let json;", "try {", " json = pm.response.json();", "} catch (e) {", " console.warn('Token response was not JSON — nothing saved.');", " json = null;", "}", "", "pm.test('Status code is 200', function () {", " pm.response.to.have.status(200);", "});", "", "if (json && json.payload && json.payload.accessToken) {", " pm.environment.set('accessToken', json.payload.accessToken);", " console.log('accessToken saved to the environment.');", "} else {", " console.warn('No payload.accessToken found in the response — accessToken was NOT updated.');", "}" ] } } ] } ] }, { "name": "Wallet", "item": [ { "name": "Get your own wallet balance", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/wallet/balance", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "balance" ] }, "description": "**Get your own wallet balance**\n\nSelf-only by construction — there is no `partnerId` parameter anywhere on this endpoint;\nthe partner is whoever the bearer token identifies. `availableBalance` already accounts for\nactive reservations (it is what you can actually spend right now)." }, "response": [] }, { "name": "List your own wallet ledger transactions", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/wallet/transactions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "transactions" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "fromUtc", "value": "2026-01-01T00:00:00Z", "disabled": true }, { "key": "toUtc", "value": "2026-01-01T00:00:00Z", "disabled": true }, { "key": "referenceType", "value": "", "description": "Repeatable match-any filter over reference type (e.g. `?referenceType=Order&referenceType=Refund`). Omit to include every reference type.", "disabled": true } ] }, "description": "**List your own wallet ledger transactions**\n\nLists your own wallet ledger entries, paged and newest first, with optional date-range and\nreference-type filters. This is the same data source used for reconciliation on the internal\nadmin view, so the figures can never drift between the two. Self-only — there is no way to\nrequest another partner's ledger. Each row is a partner-projection — internal-only fields such\nas the internal ledger id and the raw reference key are not included. `referenceType` is a\nREPEATABLE match-any filter (`?referenceType=Order&referenceType=Refund`) — omit to include\nevery reference type." }, "response": [] } ] }, { "name": "Billing", "item": [ { "name": "List your persisted billing statements", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/statements", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "statements" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ] }, "description": "**List your persisted billing statements**\n\nLists your own persisted, immutable, weekly-generated billing statements as lean summary\nrows (paged, newest first). The full rendered document is available only via the by-id read\n(`GET /api/v1/statements/{id}`) or the on-demand report\n(`GET /api/v1/statements/report`) — never over-fetched on this list." }, "response": [] }, { "name": "Compute an on-demand provisional billing report", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/statements/report?from=2026-01-01T00%3A00%3A00Z&to=2026-01-01T00%3A00%3A00Z", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "statements", "report" ], "query": [ { "key": "from", "value": "2026-01-01T00:00:00Z", "description": "Inclusive UTC start of the reporting window.", "disabled": false }, { "key": "to", "value": "2026-01-01T00:00:00Z", "description": "Exclusive UTC end of the reporting window.", "disabled": false } ] }, "description": "**Compute an on-demand provisional billing report**\n\nComputes and returns a LIVE, NEVER-PERSISTED billing document covering exactly the given\n`from`/`to` window — marked `isProvisional: true`. This is a convenience for ad-hoc\nreconciliation; it is NOT a substitute for your persisted statements, and its\n`sequenceNumber`/`statementNumber` are always null. Both `from` and `to` are required." }, "response": [] }, { "name": "Get one persisted billing statement by ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/statements/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "statements", ":id" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Get one persisted billing statement by ID**\n\nReturns one of your billing statements, including its full rendered document, by ID. Self-only — a statement belonging to another partner, or an unknown ID, returns 404." }, "response": [] }, { "name": "Get one persisted billing statement by its statement number", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/statements/by-number/:statementNumber", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "statements", "by-number", ":statementNumber" ], "variable": [ { "key": "statementNumber", "value": "STMT-2026-01-0001", "description": "The statement number, e.g. STMT-...-3." } ] }, "description": "**Get one persisted billing statement by its statement number**\n\nReturns one of your billing statements, including its full rendered document — same shape as\n`GET /api/v1/statements/{id}`, resolved by its human-facing statement number (e.g.\n`STMT-...-3`) instead of its ID. Self-only — a statement belonging to another partner, or an\nunknown/malformed statement number, returns 404." }, "response": [] } ] }, { "name": "Commission Periods", "item": [ { "name": "List your commission periods", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/commission-periods", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "commission-periods" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "status", "value": "Provisional", "description": "Repeatable match-any filter (?status=Provisional&status=Issued). Omit for every status.", "disabled": true } ] }, "description": "**List your commission periods**\n\nLists your own semi-monthly commission operating-cycle periods (paged, newest window first)\nas lean summary rows — the full ledger detail (per-order lines) is available only via the\nby-id read with `?include=document`. A period is generated PROVISIONAL at close, becomes\nISSUED once its objection window passes (frozen figures, remittance clock running), and is\nmarked SETTLED once Linra records your commission invoice as received. See\n[Commission periods](/guides/commission-periods/) for the full lifecycle." }, "response": [] }, { "name": "Get one of your commission periods", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/commission-periods/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "commission-periods", ":id" ], "query": [ { "key": "include", "value": "", "description": "Comma-separated related detail to embed. Currently supports 'document' (embeds provisionalDocument/issuedDocument). Omit for the lean shape.", "disabled": true } ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Get one of your commission periods**\n\nReturns the period's summary, objection, and settlement detail. Pass `?include=document` to\nadditionally embed the provisional document (and, once issued, the issued document too) —\nomitted by default. Self-only: a period belonging to another partner, or an unknown ID,\nreturns 404." }, "response": [] }, { "name": "Object to a provisional commission period", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/commission-periods/:id/objection", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "commission-periods", ":id", "objection" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Object to a provisional commission period**\n\nRaises an objection on your own PROVISIONAL period, before its `issueDate` — this pauses the\nperiod at Provisional until Linra resolves the objection, so it never silently becomes Issued\nout from under a genuine dispute. See\n[Commission periods](/guides/commission-periods/#3-objecting-to-a-provisional-period) for when\nto use this. The response never embeds a document (a write confirmation, not a document\nread) — fetch the by-id read with `?include=document` for the ledger detail.", "body": { "mode": "raw", "raw": "{\n \"reason\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] } ] }, { "name": "Scent", "item": [ { "name": "Orders", "item": [ { "name": "List your orders", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/orders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "orders" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "productType", "value": "", "description": "Scent is the only creatable type today; Topup/Esim are legacy (decommissioned) values kept read-only so historical rows still filter/render.", "disabled": true }, { "key": "status", "value": "", "description": "Repeatable match-any filter over the unified order status (e.g. `?status=Processing&status=Completed`). Omit to include every status.", "disabled": true }, { "key": "createdFrom", "value": "2026-01-01T00:00:00Z", "description": "Only include orders created on or after this UTC instant (inclusive).", "disabled": true }, { "key": "createdTo", "value": "2026-01-01T00:00:00Z", "description": "Only include orders created strictly before this UTC instant (exclusive — half-open window with createdFrom).", "disabled": true }, { "key": "customerRef", "value": "", "description": "Optional per-customer filter (max 128 chars) — narrows to one end-customer's own rows. Can only narrow, never widen, your own scope; omit to include every customer.", "disabled": true }, { "key": "include", "value": "lines", "description": "Comma-separated related detail to embed per row. Currently only `lines` is recognized (embeds `lines` and `fulfillmentGroups`). Omit for the lean row (id/status/pricing/deliveryRollup only).", "disabled": true } ] }, "description": "**List your orders**\n\nLists the calling partner's orders, read directly from the canonical order spine (a single\nBATCHED downstream fetch hydrates the whole page's pricing — never one call per row).\nEvery row carries the categorized `pricing{}` breakdown; pass `?include=lines` to\nadditionally embed each row's line items and fulfilment groups (by-id is always full — see\n`GET /api/v1/scent/orders/{orderId}` below). `status` is a REPEATABLE match-any filter\n(`?status=Processing&status=Completed`) — omit to include every status; the date window is\nhalf-open (`createdFrom` inclusive, `createdTo` exclusive). `customerRef` narrows to one\nend-customer's orders — it can only narrow, never widen, your own scope. Scope is always\nyour own partner; no request parameter can widen it. A spine row whose downstream order was\nnever created (e.g. a pre-create rejection) still appears — `id: null`, `status: \"Failed\"`,\nand `failureReason` explaining why — see the Order states & errors guide." }, "response": [] }, { "name": "Get an order", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/orders/:orderId", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "orders", ":orderId" ], "variable": [ { "key": "orderId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The order's own id (the Scent order's own GUID)." } ] }, "description": "**Get an order**\n\nRetrieves the full order for `orderId` — the Scent order's own GUID, the SAME value the\ncreate response's `id` and every list row's `id` carry. Unlike the list, a by-id read is\nALWAYS full (lines and fulfilment groups included — no `?include=` needed). A cross-tenant\nor unknown order reports 404 (no existence leak, SCOPE-04)." }, "response": [] }, { "name": "Get an order's delivery tracking", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/orders/:orderId/tracking", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "orders", ":orderId", "tracking" ], "variable": [ { "key": "orderId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The order's own id (the Scent order's own GUID)." } ] }, "description": "**Get an order's delivery tracking**\n\nReturns the order's unified status, a delivery rollup, and per-shipment tracking detail\n(status incl. the exception states `FailedDelivery`/`RefusedReceipt`/`ReturnedToSender`/\n`Lost`, tracking number, carrier DISPLAY NAME, movement timestamps) for `orderId` — the\nsame Scent order GUID `GET /api/v1/scent/orders/{orderId}` resolves by. Linra's own internal\nfulfilment details are never exposed — only the carrier's display name (Linra never\nhosts/links a carrier-branded tracking page, but the carrier itself is not a secret). A\ncross-tenant or unknown order reports 404." }, "response": [] }, { "name": "Create a scent order from the caller's own open cart", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/orders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "orders" ] }, "description": "**Create a scent order from the caller's own open cart**\n\nOrder LINES are never part of this request — they are taken from the partner's (optionally\n`customerRef`-scoped) open cart. Call `GET /api/v1/scent/cart/{customerRef}/checkout-preview`\nto price the cart, then `POST /api/v1/scent/cart/{customerRef}/price-lock` to take a price\nlock: `lockId` is REQUIRED here — every order is placed against a frozen price lock and\ncharged the locked prices; live-priced create is no longer allowed. See the Cart preview &\nprice locks guide. A price lock is SINGLE-USE:\nreusing an already-consumed `lockId` is rejected with `409\nCONFLICT_PRICE_LOCK_ALREADY_USED`, carrying the order it was already used for. A repeat\n`externalReference` against an order that already completed is REJECTED, not replayed — see\nthe Idempotency guide. The created order is then read via `GET /api/v1/scent/orders/{orderId}`\n(the `Location` header points there; `orderId` == this response's own `id`).", "body": { "mode": "raw", "raw": "{\n \"externalReference\": \"\",\n \"shippingAddress\": {\n \"recipient\": \"\",\n \"line1\": \"\",\n \"line2\": \"\",\n \"city\": \"\",\n \"nationalAddress\": \"\",\n \"region\": \"\",\n \"postalCode\": \"\",\n \"countryCode\": \"SAU\",\n \"phone\": \"\"\n },\n \"customerRef\": \"\",\n \"lockId\": \"00000000-0000-0000-0000-000000000000\",\n \"discountCode\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Returns", "item": [ { "name": "List every return request submitted against one order", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/orders/:orderId/return-requests", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "orders", ":orderId", "return-requests" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ], "variable": [ { "key": "orderId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The order's own id (the Scent order's own GUID)." } ] }, "description": "**List every return request submitted against one order**\n\nLists every return request you have submitted against one of your own orders (by\n`orderId`), in any status, newest first. A cross-tenant or unknown `orderId` returns 404." }, "response": [] }, { "name": "Request a return for a delivered shipment", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/orders/:orderId/return-requests", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "orders", ":orderId", "return-requests" ], "variable": [ { "key": "orderId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The order's own id (the Scent order's own GUID — same as `/api/v1/scent/orders/{orderId}`)." } ] }, "description": "**Request a return for a delivered shipment**\n\nPartner self-serve: requests a return of one or more lines of a Delivered fulfilment group\non your own order (`orderId` — the same Scent order GUID you already hold from order\ncreation/tracking). Moves NO money by itself — the request is a pending-approval envelope\naround the existing return/refund execution chain; approval triggers the existing refund/\ncommission-clawback chain. Hard PRE-check eligibility gates (fail fast, before any human\ntouches it): the group must be Delivered; each line's quantity must be within its remaining\nreturnable amount; the request must land within the configured return window (measured from\nthe group's delivery date); a line already carrying an unresolved `Requested` request cannot\nbe requested again. You may withdraw the request yourself while it's still `Requested` — see\n`PATCH /api/v1/scent/return-requests/{id}/withdraw` below. An order can ship as more than\none parcel — `fulfillmentGroupId` in the request body identifies WHICH shipment the return\nis against (the same id you already have from the order-detail response's\n`fulfillmentGroups[].id`).", "body": { "mode": "raw", "raw": "{\n \"fulfillmentGroupId\": \"00000000-0000-0000-0000-000000000000\",\n \"lines\": [\n {\n \"scentOrderLineId\": \"00000000-0000-0000-0000-000000000000\",\n \"allocationId\": \"00000000-0000-0000-0000-000000000000\",\n \"quantity\": 0,\n \"reasonCode\": \"Damaged\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Withdraw your own return request", "request": { "method": "PATCH", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/return-requests/:id/withdraw", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "return-requests", ":id", "withdraw" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The return request's own GUID (from the create response or the list above) — NOT the order id." } ] }, "description": "**Withdraw your own return request**\n\nWithdraws the caller's own return request while it is still `Requested` — before any staff\naction (authorize/decline) has occurred. Moves NO money (nothing before the internal\n`InspectionAccepted` transition, far downstream of `Requested`, ever touches money) and\nrestores the underlying line to full returnable eligibility for a fresh request. Locks\npermanently the moment any staff action occurs — rejects a request that already left\n`Requested` with `BUSINESS_RETURN_REQUEST_NOT_PENDING`. Fires both\n`order.return-request.updated` (`newStatus: \"Withdrawn\"`) and the dedicated\n`order.return-request.withdrawn` event — see the Webhooks guide." }, "response": [] }, { "name": "List every one of your own return requests", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/return-requests", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "return-requests" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "status", "value": "", "description": "Requested/Accepted/Processing/Refunded/Rejected/Withdrawn.", "disabled": true }, { "key": "fromDate", "value": "2026-01-01T00:00:00Z", "description": "Only include requests made on or after this UTC instant (inclusive).", "disabled": true }, { "key": "toDate", "value": "2026-01-01T00:00:00Z", "description": "Only include requests made strictly before this UTC instant (exclusive — half-open window with fromDate).", "disabled": true }, { "key": "orderId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "Optional narrowing filter — only this order's return requests.", "disabled": true }, { "key": "customerRef", "value": "", "description": "Optional per-customer filter (max 128 chars) — narrows to one end-customer's own rows. Can only narrow, never widen, your own scope; omit to include every customer.", "disabled": true } ] }, "description": "**List every one of your own return requests**\n\nAPI Docs Review effort, Phase N2 (D70): returns every one of the caller's OWN return\nrequests (every status, across every order), newest first, optionally narrowed by\n`status`, a `fromDate`/`toDate` window on `requestedAt` (`fromDate` inclusive, `toDate`\nexclusive), a specific `orderId`, and/or `customerRef`. Every filter only narrows within\nyour own scope — never widens past it. `status` accepts ONLY the partner-facing vocabulary\nthis endpoint's own response emits (`Requested`/`Accepted`/`Processing`/`Refunded`/\n`Rejected`/`Withdrawn`) — an unrecognized value (including an internal status name, or a\nnumeric ordinal) is rejected with `400 VALIDATION_INVALID_RETURN_STATUS` rather than\nsilently matching nothing." }, "response": [] }, { "name": "List your own return requests for one end customer", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/return-requests/by-customer/:customerRef", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "return-requests", "by-customer", ":customerRef" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**List your own return requests for one end customer**\n\nAPI Docs Review effort, Phase N2 (D71): returns the calling partner's own return requests\n(every status) for one end customer, identified by the required `customerRef` path segment\n(the same opaque reference used at checkout) — newest first. An unknown or never-used\n`customerRef` simply returns an empty page (there's no separate existence to 404 on)." }, "response": [] } ] }, { "name": "Webhooks", "item": [ { "name": "List your webhook subscriptions", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ] }, "description": "**List your webhook subscriptions**\n\nLists every webhook subscription registered by your partner account. The response never includes the signing secret." }, "response": [] }, { "name": "Create a webhook subscription", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks" ] }, "description": "**Create a webhook subscription**\n\nThe response's `secret` is shown EXACTLY ONCE — store it immediately. Up to 5 active\nsubscriptions per partner (`BUSINESS_WEBHOOK_SUBSCRIPTION_LIMIT` above that). See the\nWebhooks guide for the full HMAC verification walkthrough.", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/webhook\",\n \"eventTypes\": [\n \"order.completed\"\n ],\n \"headers\": {\n \"Authorization\": \"Bearer your-own-inbound-token\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Get a webhook subscription by ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks", ":id" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Get a webhook subscription by ID**\n\nRetrieves one of your own webhook subscriptions by ID. The response never includes the signing secret." }, "response": [] }, { "name": "Update a webhook subscription's URL and/or subscribed event types", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks", ":id" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Update a webhook subscription's URL and/or subscribed event types**\n\nIf the URL changes, it is re-validated against the same SSRF guard applied at creation.", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/webhook\",\n \"eventTypes\": [\n \"order.completed\"\n ],\n \"headers\": {\n \"Authorization\": \"Bearer your-own-inbound-token\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Activate or deactivate a webhook subscription", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks/:id/active", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks", ":id", "active" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Activate or deactivate a webhook subscription**\n\nAn inactive subscription receives no deliveries and does not count toward your active-subscription cap.", "body": { "mode": "raw", "raw": "{\n \"isActive\": false\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Rotate a webhook subscription's signing secret", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks/:id/rotate-secret", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks", ":id", "rotate-secret" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Rotate a webhook subscription's signing secret**\n\nThe NEW secret is shown exactly once in this response. The old secret stops verifying immediately." }, "response": [] }, { "name": "Send a real, signed test delivery for one event type", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks/:id/test-fire", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks", ":id", "test-fire" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Send a real, signed test delivery for one event type**\n\nExercises the exact same signing/delivery/retry code path as a real event — useful for verifying your HMAC verification code before going live.", "body": { "mode": "raw", "raw": "{\n \"eventType\": \"order.completed\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "List recent delivery attempts for a subscription", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/webhooks/:id/deliveries", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "webhooks", ":id", "deliveries" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**List recent delivery attempts for a subscription**\n\nDeliveries are retained for 30 days." }, "response": [] } ] }, { "name": "Reports", "item": [ { "name": "Get your own top-line sales figures for a period", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/reports/sales/summary", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "reports", "sales", "summary" ], "query": [ { "key": "fromUtc", "value": "2026-01-01T00:00:00Z", "description": "Period start (UTC), inclusive. Defaults to 30 days before toUtc.", "disabled": true }, { "key": "toUtc", "value": "2026-01-01T00:00:00Z", "description": "Period end (UTC), exclusive. Defaults to now.", "disabled": true } ] }, "description": "**Get your own top-line sales figures for a period**\n\nOrder volume, gross revenue, returns value, net revenue, and average order value for YOUR OWN\norders only — self-only by construction, there is no `partnerId` parameter anywhere on this\nsurface. Deliberately excludes `margin` — that is Linra's own commercial position, derived\nfrom internal data you don't have visibility into anywhere else in the system either, never\na partner-visible figure. `fromUtc` is inclusive, `toUtc` is exclusive; both default to the\nlast 30 days when the window is omitted entirely (`toUtc` defaults to now, `fromUtc` to 30\ndays before it).\nRevenue is GOODS-only (excludes the order-level shipping fee) and GROSS-as-sold — a later\nreturn doesn't rewrite it; the return is its own separately-dated `returnsValue` figure. See\nthe [Sales & cart analytics guide](/guides/sales-and-cart-analytics/)." }, "response": [] }, { "name": "Get your own daily order count and revenue for a period", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/reports/sales/time-series", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "reports", "sales", "time-series" ], "query": [ { "key": "fromUtc", "value": "2026-01-01T00:00:00Z", "description": "Period start (UTC), inclusive. Defaults to 30 days before toUtc.", "disabled": true }, { "key": "toUtc", "value": "2026-01-01T00:00:00Z", "description": "Period end (UTC), exclusive. Defaults to now.", "disabled": true } ] }, "description": "**Get your own daily order count and revenue for a period**\n\nOne point per Riyadh calendar day the requested window spans, INCLUDING zero-order days, for\nYOUR OWN orders only. Same window semantics as the summary endpoint (`fromUtc` inclusive,\n`toUtc` exclusive, defaults to the last 30 days). The response is a bare array, not a paged\nresult — there is one row per calendar day in the window, never a page-worth cutoff." }, "response": [] }, { "name": "Get your own revenue and quantity broken down by product variant", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/reports/sales/by-product", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "reports", "sales", "by-product" ], "query": [ { "key": "fromUtc", "value": "2026-01-01T00:00:00Z", "description": "Period start (UTC), inclusive. Defaults to 30 days before toUtc.", "disabled": true }, { "key": "toUtc", "value": "2026-01-01T00:00:00Z", "description": "Period end (UTC), exclusive. Defaults to now.", "disabled": true }, { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ] }, "description": "**Get your own revenue and quantity broken down by product variant**\n\nOrdered by revenue descending, for YOUR OWN orders only. Deliberately excludes `margin`. The\nsummary endpoint's totals are computed independently over the FULL window — never derive a\ntotal by summing this page." }, "response": [] }, { "name": "Lost-demand per variant for your own shoppers", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/reports/cart-insights/lost-demand", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "reports", "cart-insights", "lost-demand" ], "query": [ { "key": "from", "value": "2026-01-01T00:00:00Z", "description": "Window start (UTC), inclusive. Defaults to 30 days before 'to'.", "disabled": true }, { "key": "to", "value": "2026-01-01T00:00:00Z", "description": "Window end (UTC), exclusive. Defaults to now.", "disabled": true }, { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ] }, "description": "**Lost-demand per variant for your own shoppers**\n\nPer-variant counts of blocked-add events (split by reason: unavailable vs. insufficient\nquantity) within the given window, for YOUR OWN cart events only. Deliberately excludes the\ninternal report's fleet-wide `activeNotifyRegistrations` count — that is a cross-partner\naggregate (how many partners in total are waiting for this variant to restock), not a fact\nabout your own activity. Only variants with at least one blocked event in the window are\nreturned, ordered by total blocked count descending. `from`/`to` default to the last 30 days\nwhen omitted — unlike the sales endpoints above, there is no maximum-window or\nfrom-before-to validation here; an inverted window simply returns an empty page." }, "response": [] }, { "name": "Cart abandonment rate and value for your own carts", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/reports/cart-insights/abandonment", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "reports", "cart-insights", "abandonment" ], "query": [ { "key": "from", "value": "2026-01-01T00:00:00Z", "description": "Window start (UTC), inclusive. Defaults to 30 days before 'to'.", "disabled": true }, { "key": "to", "value": "2026-01-01T00:00:00Z", "description": "Window end (UTC), exclusive. Defaults to now.", "disabled": true } ] }, "description": "**Cart abandonment rate and value for your own carts**\n\nCart-lifecycle counts (created / checked-out / expired-or-abandoned) within the given window\nand the resulting abandonment rate, plus the estimated value CURRENTLY sitting in YOUR OWN\nlive abandoned carts. `abandonedCartsValue` is deliberately NOT restricted to the [from, to)\nwindow — it's a present-tense snapshot of what's parked in abandoned carts right now,\nindependent of when they were abandoned. `from`/`to` default to the last 30 days when\nomitted; no window-size limit applies to this endpoint (see the lost-demand endpoint's\nidentical note above)." }, "response": [] }, { "name": "Add-to-cart to checkout conversion per variant, for your own shoppers", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/reports/cart-insights/conversion", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "reports", "cart-insights", "conversion" ], "query": [ { "key": "from", "value": "2026-01-01T00:00:00Z", "description": "Window start (UTC), inclusive. Defaults to 30 days before 'to'.", "disabled": true }, { "key": "to", "value": "2026-01-01T00:00:00Z", "description": "Window end (UTC), exclusive. Defaults to now.", "disabled": true }, { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ] }, "description": "**Add-to-cart to checkout conversion per variant, for your own shoppers**\n\nPer-variant add→buy conversion within the given window, for YOUR OWN cart events only: how\nmany of your own carts added the variant, and of those, how many were (eventually) checked\nout — the checkout side is not re-windowed, so a cart added-to near the window's end still\ncounts if it converts slightly after the window closes. `from`/`to` default to the last 30\ndays when omitted; no window-size limit applies (see the lost-demand endpoint's identical\nnote above)." }, "response": [] } ] }, { "name": "Catalog", "item": [ { "name": "List scents", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/scents", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "scents" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "lang", "value": "", "disabled": true }, { "key": "brandId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "disabled": true }, { "key": "concentration", "value": "", "disabled": true }, { "key": "audience", "value": "", "disabled": true }, { "key": "changedSince", "value": "2026-01-01T00:00:00Z", "description": "Only return rows changed strictly after this UTC instant. See the Catalog delta sync guide.", "disabled": true }, { "key": "activeOnly", "value": "true", "disabled": true } ] }, "description": "**List scents**\n\nReturns a paged list of scents, optionally filtered by brand, concentration, or audience, and\nlocalized via the `lang` parameter. Passing `changedSince` switches to delta-sync mode — only\nscents changed strictly after that UTC instant, ordered oldest-changed-first instead of by name." }, "response": [] }, { "name": "Get relevance-ranked scent suggestions", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/suggestions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "suggestions" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "lang", "value": "", "disabled": true }, { "key": "brandId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "disabled": true }, { "key": "concentration", "value": "", "disabled": true }, { "key": "audience", "value": "", "disabled": true }, { "key": "note", "value": "", "description": "Repeatable — a scent note to rank/filter by (e.g. ?note=Oud¬e=Amber).", "disabled": true }, { "key": "accord", "value": "", "description": "Repeatable — an accord family to rank/filter by.", "disabled": true }, { "key": "minPrice", "value": "0", "disabled": true }, { "key": "maxPrice", "value": "0", "disabled": true }, { "key": "changedSince", "value": "2026-01-01T00:00:00Z", "description": "Only return rows changed strictly after this UTC instant. See the Catalog delta sync guide.", "disabled": true }, { "key": "activeOnly", "value": "true", "disabled": true } ] }, "description": "**Get relevance-ranked scent suggestions**\n\nAPI Docs Review effort, Phase D24: a discovery variant of `GET /api/v1/scent/scents` —\naccepts the SAME filter set (`brandId`/`concentration`/`audience`/`lang`/`activeOnly`/\n`changedSince`/paging, plus `note`/`accord`/`minPrice`/`maxPrice` for ranking/filtering) and\nreturns the SAME `PagedScentResponse` shape, but results are ordered by relevance — the\ncount of requested `note`s + `accord`s each scent matches (highest first), ties broken by\nthe default name order. Falls back to the default scent ordering when no `note`/`accord` is\nrequested (no ranking signal to rank by)." }, "response": [] }, { "name": "List brands", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/brands", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "brands" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "lang", "value": "", "disabled": true }, { "key": "changedSince", "value": "2026-01-01T00:00:00Z", "description": "Only return rows changed strictly after this UTC instant. See the Catalog delta sync guide.", "disabled": true } ] }, "description": "**List brands**\n\nReturns a paged list of brands, localized via the optional `lang` parameter. Passing\n`changedSince` switches to delta-sync mode — only brands changed strictly after that UTC\ninstant, ordered oldest-changed-first instead of by name." }, "response": [] }, { "name": "List variants", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/variants", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "variants" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "scentId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "disabled": true }, { "key": "changedSince", "value": "2026-01-01T00:00:00Z", "description": "Only return rows changed strictly after this UTC instant. See the Catalog delta sync guide.", "disabled": true } ] }, "description": "**List variants**\n\nReturns a paged list of variants (sizes/SKUs), optionally filtered by scent. Passing\n`changedSince` switches to delta-sync mode — only variants changed strictly after that UTC\ninstant, ordered oldest-changed-first instead of the default order." }, "response": [] } ] }, { "name": "Cart", "item": [ { "name": "Get your own cart", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Get your own cart**\n\nReturns the caller's cart for the required `customerRef` path segment — an opaque,\npartner-namespaced reference for whichever of your own end customers this cart belongs to\n(API Docs Review effort, Phase F, D29: every cart endpoint carries `customerRef` in the\npath — it is no longer an optional query parameter). Pure read — LAZY-CREATE (Phase F,\nD28): when no cart row exists yet for this `customerRef`, returns 200 with an empty\nrepresentation (`id: null`, `status: \"None\"`, `pricedAt: null`, zeroed totals) rather than a\n404 or a created row; the row is born on the first `POST .../items` call. A line whose\nvariant has since become unavailable or unpriceable is KEPT in the response\n(`pricing: null`, `availability` reflecting the real state) rather than silently dropped\n(Phase F, D32) — totals still reflect only the priced lines." }, "response": [] }, { "name": "Add an item to your cart (or merge quantity into an existing line)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/items", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "items" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Add an item to your cart (or merge quantity into an existing line)**\n\nAdds a variant and quantity to the cart identified by the required `customerRef` path\nsegment. Adding a variant that is already in the cart merges the quantity into the existing\nline rather than creating a duplicate. Creates the cart row on first add if none exists yet\n(Phase F, D28).", "body": { "mode": "raw", "raw": "{\n \"variantId\": \"00000000-0000-0000-0000-000000000000\",\n \"quantity\": 0\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Remove every line from your cart", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/items", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "items" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Remove every line from your cart**\n\nRemoves all items from the cart identified by the required `customerRef` path segment.\nPhase F, D31: the cart row itself is always deleted outright (a cart row exists iff it has\nat least one item) — the response is the SAME 200-empty representation `GET\n/api/v1/scent/cart/{customerRef}` returns for a cart that has never had anything added." }, "response": [] }, { "name": "Set a line's quantity, or adjust it by ±1", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/items/:variantId", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "items", ":variantId" ], "variable": [ { "key": "variantId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Set a line's quantity, or adjust it by ±1**\n\nUpdates an existing line in the cart identified by the required `customerRef` path segment.\nSupply EXACTLY ONE of: `quantity` (sets the absolute quantity, must be >= 1) or `action` — a\nrelative ±1 adjustment, `increment` (+1) or `decrement` (-1). A `decrement` that reaches 0\nremoves the line entirely, and if that empties the cart the cart row itself is deleted (the\nsame D31 behavior as `DELETE .../items/{variantId}`). `increment` re-checks product access\nand availability (it is new demand); a decrease can never oversell. Supplying neither, or\nboth, is `400 VALIDATION_ERRORS`. The line must already exist — an increment/decrement/set\nof a variant not in the cart is `404 NOT_FOUND_CART_ITEM`. There is no separate decrement\nendpoint — this single PUT covers both the absolute-set and the ±1-adjustment shapes.", "body": { "mode": "raw", "raw": "{\n \"quantity\": 0,\n \"action\": \"increment\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Remove one line (idempotent — removing an absent line is not an error)", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/items/:variantId", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "items", ":variantId" ], "variable": [ { "key": "variantId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Remove one line (idempotent — removing an absent line is not an error)**\n\nRemoves the line for the given variant (idempotent) from the cart identified by the\nrequired `customerRef` path segment. Phase F, D31: if this removes the LAST line in the\ncart, the cart row itself is deleted outright." }, "response": [] }, { "name": "Preview what checkout would do right now", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/checkout-preview", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "checkout-preview" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Preview what checkout would do right now**\n\nALWAYS call this before `POST /api/v1/scent/orders` — it runs the SAME resolution order-create\nruns (pricing, VAT, availability, and the margin-floor guard) over the cart identified by the\nrequired `customerRef` path segment and reports every line's verdict at once. Read-only with\nrespect to the cart/order domain: takes NO reservations and performs NO wallet-funds check.\nAPI Docs Review effort, Phase F (D33): this endpoint is genuinely pure-read now — it never\ntakes a price lock itself. To freeze the currently-previewed prices, call\n`POST /api/v1/scent/cart/{customerRef}/price-lock` separately, which recomputes this SAME\npreview internally and persists a lock only when it reports `canCheckout: true`. Issue codes:\n`UNAVAILABLE`, `INSUFFICIENT_STOCK`, `PRICE_BELOW_FLOOR`, `NOT_PRICED` (per line);\n`CART_HAS_PENDING_ORDER`, `PRODUCT_ACCESS_DISABLED`, `ORDER_MARGIN_BELOW_FLOOR` (cart-level,\nvia `cartIssue`). An empty cart returns `canCheckout: false` with no lines, not an error." }, "response": [] }, { "name": "Freeze the current checkout preview's prices", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/price-lock", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "price-lock" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Freeze the current checkout preview's prices**\n\nAPI Docs Review effort, Phase F (D33): recomputes the SAME checkout preview\n`GET /api/v1/scent/cart/{customerRef}/checkout-preview` would report, and — ONLY when that\nrecomputed preview reports `canCheckout: true` — persists a price-lock snapshot (default TTL\n15 minutes, admin-configurable) that order-create references via its own `lockId` field to\ncharge EXACTLY these prices regardless of any live price/cost drift in either direction. The\nmargin floor still applies to the locked figures at create time, so a drift that pushes the\ndeal below the required minimum still rejects with `BUSINESS_MARGIN_BELOW_FLOOR` rather than\nbeing silently honored. A broken basket (`canCheckout: false`) is never locked — this call\nrejects outright with `422 BUSINESS_CART_NOT_CHECKOUT_READY` instead (re-run the checkout\npreview to see why). Any cart mutation (add/set/remove/clear) invalidates the cart's active\nlock; stock is never locked — it is always re-checked live at create time. Previously nested\non the checkout-preview GET behind a `?lock=true` query flag — D33 split the side-effecting\nlock create out into this dedicated POST." }, "response": [] }, { "name": "Check a discount code against the current cart", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/cart/:customerRef/discount-codes/validate", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "cart", ":customerRef", "discount-codes", "validate" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Check a discount code against the current cart**\n\nRead-only — never consumes a use or changes any usage count. Resolves the cart identified\nby the required `customerRef` path segment and reports whether the code currently applies\nto it, plus the computed original/discount/discounted totals for display. This never\nchanges what you are charged at order-create — codes are a pure display/reporting overlay\non top of the price Linra computes (see the Discount Codes guide's \"how charging works\"\nsection).", "body": { "mode": "raw", "raw": "{\n \"code\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Wishlist", "item": [ { "name": "Get the customer's wishlist", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/wishlist/:customerRef", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "wishlist", ":customerRef" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Get the customer's wishlist**\n\nAPI Docs Review effort, Phase G (D37): returns the calling partner's favorited variants for\nthe required `customerRef` path segment, as full mini-cards (`variantId`/`sku`/`sizeMl`/\n`scentName`/`brandName`/`imageUrl`/`currentPrice`/`availability`/`addedAt`) — never a second\nround trip per item. An untouched (partner, `customerRef`) pair returns 200 with `items: []`,\nnever a 404." }, "response": [] }, { "name": "Favorite a variant", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/wishlist/:customerRef/items", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "wishlist", ":customerRef", "items" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Favorite a variant**\n\nAdds a variant to the customer's wishlist, identified by the required `customerRef` path\nsegment. Idempotent — favoriting an already-favorited variant is a no-op, never a 409.\nReturns the updated wishlist.", "body": { "mode": "raw", "raw": "{\n \"variantId\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Clear the wishlist", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/wishlist/:customerRef/items", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "wishlist", ":customerRef", "items" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Clear the wishlist**\n\nRemoves every favorited variant from the customer's wishlist, identified by the required `customerRef` path segment (idempotent — clearing an already-empty wishlist is a no-op). Returns the updated (empty) wishlist." }, "response": [] }, { "name": "Unfavorite a variant", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/wishlist/:customerRef/items/:variantId", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "wishlist", ":customerRef", "items", ":variantId" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." }, { "key": "variantId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Unfavorite a variant**\n\nRemoves the given variant from the customer's wishlist, identified by the required `customerRef` path segment (idempotent — removing an absent favorite is a no-op). Returns the updated wishlist." }, "response": [] } ] }, { "name": "Stock Notify", "item": [ { "name": "List a customer's back-in-stock registrations", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/stock-notifications/:customerRef", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "stock-notifications", ":customerRef" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**List a customer's back-in-stock registrations**\n\nReturns the given customer's live notify-when-available registrations (identified by the\nrequired `customerRef` path segment), newest first. No `activeOnly` filter — a registration\nhas no active/inactive concept: it exists until it fires or is cancelled." }, "response": [] }, { "name": "Register for a back-in-stock notification", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/stock-notifications/:customerRef", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "stock-notifications", ":customerRef" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." } ] }, "description": "**Register for a back-in-stock notification**\n\nAPI Docs Review effort, Phase G follow-up (D34 / R-CUSTOMERREF): the notify-when-available\nsurface moved off `/api/v1/scent/cart/notify/**` onto this dedicated, `customerRef`-scoped\nbase. Registers the given customer (identified by the required `customerRef` path segment) to\nbe notified when an out-of-stock variant becomes Available/Limited again. One registration per\n(partner, customerRef, variant) — a duplicate call for the same customer is idempotent, and\ntwo distinct `customerRef`s under one partner register independently. No stock is reserved.", "body": { "mode": "raw", "raw": "{\n \"variantId\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Cancel a back-in-stock notification registration", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/stock-notifications/:customerRef/:variantId", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "stock-notifications", ":customerRef", ":variantId" ], "variable": [ { "key": "customerRef", "value": "cust-1001", "description": "The per-customer cart/registration selector this endpoint operates on (max 128 chars, URL-encoded) — every cart/wishlist/stock-notification endpoint carries it in the path (API Docs Review effort, Phase F/G, D29/R-CUSTOMERREF). Also the value a per-customer redemption cap, if any, is checked against." }, { "key": "variantId", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Cancel a back-in-stock notification registration**\n\nRemoves the given customer's notify-when-available registration for this variant, if any. Idempotent — a no-op when none exists." }, "response": [] } ] }, { "name": "Unfulfillable Notices", "item": [ { "name": "List your own open unfulfillable-line notices", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/unfulfillable-notices", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "unfulfillable-notices" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true } ] }, "description": "**List your own open unfulfillable-line notices**\n\nSelf-serve recovery path: your own OPEN (still `AwaitingPartnerResponse`) unfulfillable-line\nnotices, newest first — use this when the 72-hour `order.line-unfulfillable` webhook was\nmissed or never arrived. A notice is raised when a line becomes unfulfillable AFTER you've\nalready been charged for it (a receiving-time shortage/damage that couldn't be replaced in\ntime, or a lost shipment), and gives you 72 hours to choose `CancelWhole` (cancel the whole\noutstanding line, full refund) or `ShipAvailable` (ship what's available, cancel + refund\nonly the shortfall) via `PATCH .../{id}/respond` below. If you don't respond in time, the\nsystem applies its own documented default and the notice leaves this list (no longer open).\nEach row carries the affected line's context and the projected money impact of each choice." }, "response": [] }, { "name": "Get an unfulfillable-line notice", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/unfulfillable-notices/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "unfulfillable-notices", ":id" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The notice's own GUID." } ] }, "description": "**Get an unfulfillable-line notice**\n\nReads one of your own unfulfillable-line notices by its own GUID (from the\n`order.line-unfulfillable` webhook's `data.noticeId`, or from the list above). A cross-tenant\nor unknown id returns 404 — no existence leak. The response carries the affected line's\ncontext and, while still awaiting a response, the projected money impact of each choice;\n`impact` is null once the notice is resolved or expired." }, "response": [] }, { "name": "Respond to an unfulfillable-line notice", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/unfulfillable-notices/:id/respond", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "unfulfillable-notices", ":id", "respond" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "The notice's own GUID." } ] }, "description": "**Respond to an unfulfillable-line notice**\n\nWithin the 72-hour window, choose `CancelWhole` (cancel the whole outstanding line, full\nrefund) or `ShipAvailable` (ship what's available, cancel + refund only the shortfall).\nReturns the notice with the resulting refund figures now applied (`status` becomes\n`Resolved`). A cross-tenant or unknown id returns 404 (no existence leak). Rejects a notice\nthat isn't currently `AwaitingPartnerResponse` with `422 BUSINESS_NOTICE_NOT_AWAITING_RESPONSE`\n(already resolved, or already expired past its own deadline). If your response races the\n72-hour expiry sweep for the same notice, the loser gets `409\nCONFLICT_NOTICE_ALREADY_RESOLVED` — the money already landed under whichever side won; retry\nwith a fresh read to see the outcome.", "body": { "mode": "raw", "raw": "{\n \"choice\": \"CancelWhole\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Discount Codes", "item": [ { "name": "List your discount codes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/discount-codes", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "discount-codes" ], "query": [ { "key": "page", "value": "1", "disabled": true }, { "key": "pageSize", "value": "20", "disabled": true }, { "key": "activeOnly", "value": "true", "description": "Filter to active-only codes.", "disabled": true } ] }, "description": "**List your discount codes**\n\nLists every discount code your partner account owns, newest first, including usage statistics." }, "response": [] }, { "name": "Create a discount code", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/discount-codes", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "discount-codes" ] }, "description": "**Create a discount code**\n\nThe `code` string is IMMUTABLE once created — there is no rename operation, and no update\nendpoint at all: every other field is fixed for the life of the code too. To retire a\ntypo'd or campaign-ended code, deactivate it (`PATCH .../{id}/active` with\n`isActive: false`) and create a new one instead.", "body": { "mode": "raw", "raw": "{\n \"code\": \"\",\n \"discountType\": \"Percent\",\n \"value\": 0,\n \"validFrom\": \"2026-01-01T00:00:00Z\",\n \"validTo\": \"2026-01-01T00:00:00Z\",\n \"totalUsageCap\": 0,\n \"perCustomerCap\": 0,\n \"scopedVariantIds\": [\n \"00000000-0000-0000-0000-000000000000\"\n ],\n \"minOrderValue\": 0\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Get one of your discount codes by ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/discount-codes/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "discount-codes", ":id" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Get one of your discount codes by ID**\n\nReturns a single discount code by ID, including usage statistics. A code belonging to another partner, or an unknown ID, returns 404." }, "response": [] }, { "name": "Delete a discount code that has never been redeemed", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/scent/discount-codes/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "discount-codes", ":id" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Delete a discount code that has never been redeemed**\n\nA code with at least one redemption cannot be deleted — deactivate it instead (`PATCH .../{id}/active` with `isActive: false`)." }, "response": [] }, { "name": "Activate or deactivate a discount code", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/scent/discount-codes/:id/active", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "scent", "discount-codes", ":id", "active" ], "variable": [ { "key": "id", "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "description": "**Activate or deactivate a discount code**\n\nThe ONLY mutation a discount code supports after creation — every other field (the code\nstring, discount type/value, validity window, caps, scope, minimum order value) is\nimmutable for the life of the code (deactivate + create a new one instead of editing a\nterm). This is also how you retire a code that has already been redeemed at least once,\nsince a redeemed code can never be deleted.", "body": { "mode": "raw", "raw": "{\n \"isActive\": false\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] } ] } ] }