Add cart item

Cart

POST/api/v1/scent/cart/{customerRef}/items

Adds a variant and quantity to the cart identified by the required customerRef path segment. Adding a variant that is already in the cart merges the quantity into the existing line rather than creating a duplicate. Creates the cart row on first add if none exists yet (Phase F, D28).

Path parameters

customerRefstringRequired

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.

Body parameters

variantIdstring (uuid)Required

The variant (size/SKU) to add.

quantityintegerRequired

Quantity to add (merged into any existing line for this variant).

Response

idstring (uuid)

Null when there is no persisted cart row yet (a lazy-create GET/preview never creates one).

customerRefstring

statusstring (enum)

None is a RESPONSE-ONLY value for the 200-empty (no cart row) representation.

baseCurrencystring

Hoisted from each line’s own currency (the Scent catalog is SAR-only).

itemsarray of object

totals.chargedWithVatnumber (decimal)

Sum of every line’s goods-sale total including VAT, PLUS the order-level shipping fee — what checkout would actually charge.

totals.commissionWithVatnumber (decimal)

Sum of every CREDITABLE (Retail-mode) line’s commission including VAT — 0 for an all-Wholesale cart, never null.

totals.netAfterCommissionnumber (decimal)

chargedWithVat minus commissionWithVat.

totals.shippingobject

totals.displayobject

Populated only for a supported non-SAR X-Partner-Currency.

pricedAtstring (date-time)

The server UTC time of THIS read; null for the 200-empty representation.

Other responses

400Request validation failed.

401No bearer token (UNAUTHORIZED_MISSING_TOKEN), an invalid token (UNAUTHORIZED_INVALID_TOKEN) or an expired one (UNAUTHORIZED_TOKEN_EXPIRED — mint a new token). UPSTREAM_AUTH_FAILED is different: a dependent service refused the Gateway itself. That is a server-side fault — retry later and do NOT re-mint your token. See the Errors guide.

403The route is not available to your credential (FORBIDDEN).

404Unknown or inactive variant.

415The request body is not sent as application/json (UNSUPPORTED_MEDIA_TYPE).

422The variant can’t be added right now.

429Too many requests — see the Rate limits guide. Retry after the Retry-After header (seconds).

502A dependent service returned an invalid response (BAD_GATEWAY). Retry with backoff.

503The service is temporarily unavailable (SERVICE_UNAVAILABLE). Retry with backoff.

504A dependent service did not respond in time (GATEWAY_TIMEOUT). Retry with backoff.

cURL

curl --request POST \
  --url https://api-omni.linra.net/api/v1/scent/cart/value/items \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "variantId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "quantity": 1
  }'

JavaScript

const res = await fetch('https://api-omni.linra.net/api/v1/scent/cart/value/items', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    variantId: '5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b',
    quantity: 1
  }),
});
const { payload } = await res.json();

C#

var response = await httpClient.PostAsJsonAsync(
    "https://api-omni.linra.net/api/v1/scent/cart/value/items",
    new
    {
        variantId = "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        quantity = 1
    });

var envelope = await response.Content.ReadFromJsonAsync<ApiResponse<CartResponse>>();

Response

{
  "state": "SUCCESS",
  "payload": {
    "id": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "customerRef": "string",
    "status": "None",
    "baseCurrency": "SAR",
    "items": [
      {
        "variantId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        "sku": "string",
        "sizeMl": 0,
        "quantity": 0,
        "pricing": {
          "currency": "SAR",
          "unitPrice": 0,
          "line": {
            "subtotal": 0,
            "goodsVatAmount": 0,
            "totalWithVat": 0,
            "commission": {
              "amount": null,
              "vatAmount": null,
              "netAfterCommission": null,
              "rate": null
            }
          },
          "rrp": 0,
          "display": {
            "unitPrice": 0,
            "line": {
              "subtotal": null,
              "goodsVatAmount": null,
              "totalWithVat": null,
              "commission": null
            },
            "rrp": 0
          }
        },
        "availability": {
          "state": "Available",
          "availableQuantity": 0,
          "insufficientForQuantity": true
        },
        "marketing": {
          "currentPrice": 0,
          "compareAtPrice": 0,
          "discountPercent": 0,
          "badges": [
            "LIMITED"
          ],
          "currentPriceDisplay": 0,
          "compareAtPriceDisplay": 0
        }
      }
    ],
    "totals": {
      "chargedWithVat": 0,
      "commissionWithVat": 0,
      "netAfterCommission": 0,
      "shipping": {
        "amount": 0,
        "vatAmount": 0,
        "amountWithVat": 0,
        "freeThreshold": 0,
        "isFree": true
      },
      "display": {
        "currency": "string",
        "rate": 0,
        "chargedWithVat": 0,
        "commissionWithVat": 0,
        "netAfterCommission": 0,
        "shipping": {
          "amount": 0,
          "vatAmount": 0,
          "amountWithVat": 0,
          "freeThreshold": 0
        }
      }
    },
    "pricedAt": "2026-08-22T09:14:03Z"
  },
  "details": null
}