Register stock notify

Stock Notify

POST/api/v1/scent/stock-notifications/{customerRef}

API Docs Review effort, Phase G follow-up (D34 / R-CUSTOMERREF): the notify-when-available surface moved off /api/v1/scent/cart/notify/** onto this dedicated, customerRef-scoped base. Registers the given customer (identified by the required customerRef path segment) to be notified when an out-of-stock variant becomes Available/Limited again. One registration per (partner, customerRef, variant) — a duplicate call for the same customer is idempotent, and two distinct customerRefs under one partner register independently. No stock is reserved.

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 out-of-stock variant to register an alert for.

Response

idstring (uuid)

variant.idstring (uuid)

variant.skustring

variant.scentNamestring

variant.brandNamestring

registeredAtstring (date-time)

Other responses

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).

404No API route matches this path (NOT_FOUND_ROUTE). A missing resource on a real route returns that service’s own NOT_FOUND_* code instead.

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

422Registering on a variant that is already sellable, or notify is disabled for your account.

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 --request POST \
  --url https://api-omni.linra.net/api/v1/scent/stock-notifications/value \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "variantId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b"
  }'

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

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

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

Response

{
  "state": "SUCCESS",
  "payload": {
    "id": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "variant": {
      "id": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
      "sku": "string",
      "scentName": "string",
      "brandName": "string"
    },
    "registeredAt": "2026-08-22T09:14:03Z"
  },
  "details": null
}