Create discount code

Discount Codes

POST/api/v1/scent/discount-codes

The code string is IMMUTABLE once created — there is no rename operation, and no update endpoint at all: every other field is fixed for the life of the code too. To retire a typo’d or campaign-ended code, deactivate it (PATCH .../{id}/active with isActive: false) and create a new one instead.

Body parameters

codestringRequired

The code string your end customer enters. Immutable once created.

discountTypestring (enum)Required

A percentage (0,100] off, or a flat SAR amount off.

valuenumber (decimal)Required

Percentage, greater than 0 and at most 100, for Percent; a flat SAR amount, greater than 0 and at most 100000, for FixedAmount.

validFromstring (date-time)

Null means open-ended (no start restriction).

validTostring (date-time)

Null means the code never expires. When both validFrom and validTo are given, validTo must be strictly after validFrom.

totalUsageCapinteger

Null means unlimited total redemptions; otherwise 1-1,000,000.

perCustomerCapinteger

Null means no per-customer limit. The only other accepted value is 1 (at most one redemption per customer, ever) — any other positive value is rejected.

scopedVariantIdsarray of string (uuid)

Restricts the code to this explicit variant list — every id must be one of your existing, active variants. Omit, or send an empty list, to apply the code to your whole catalog.

minOrderValuenumber (decimal)

Null means no minimum; otherwise must be >= 0. Compared against the cart’s goods value including VAT, excluding the order-level shipping fee.

Response

idstring (uuid)

codestring

discountTypestring (enum)

A percentage (0,100] off, or a flat SAR amount off.

valuenumber (decimal)

validFromstring (date-time)

validTostring (date-time)

isActiveboolean

totalUsageCapinteger

perCustomerCapinteger

scopedVariantIdsarray of string (uuid)

Present and non-empty ⇒ the code applies only to these variants. Empty ⇒ applies to your whole catalog.

minOrderValuenumber (decimal)

usageCountinteger

Running total of successful redemptions.

createdAtstring (date-time)

lastModifiedAtstring (date-time)

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

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.

409A code with this string (case-insensitive) already exists for your account.

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

422Managing discount codes (new promotional terms) 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

curl --request POST \
  --url https://api-omni.linra.net/api/v1/scent/discount-codes \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "string",
    "discountType": "Percent",
    "value": 0,
    "validFrom": "2026-08-22T09:14:03Z",
    "validTo": "2026-08-22T09:14:03Z",
    "totalUsageCap": 1,
    "perCustomerCap": 0,
    "scopedVariantIds": [
      "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b"
    ],
    "minOrderValue": 0
  }'

JavaScript

const res = await fetch('https://api-omni.linra.net/api/v1/scent/discount-codes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'string',
    discountType: 'Percent',
    value: 0,
    validFrom: '2026-08-22T09:14:03Z',
    validTo: '2026-08-22T09:14:03Z',
    totalUsageCap: 1,
    perCustomerCap: 0,
    scopedVariantIds: [
      '5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b'
    ],
    minOrderValue: 0
  }),
});
const { payload } = await res.json();

C#

var response = await httpClient.PostAsJsonAsync(
    "https://api-omni.linra.net/api/v1/scent/discount-codes",
    new
    {
        code = "string",
        discountType = "Percent",
        value = 0,
        validFrom = "2026-08-22T09:14:03Z",
        validTo = "2026-08-22T09:14:03Z",
        totalUsageCap = 1,
        perCustomerCap = 0,
        scopedVariantIds = new[]
        {
            "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b"
        },
        minOrderValue = 0
    });

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

Response

{
  "state": "SUCCESS",
  "payload": {
    "id": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "code": "string",
    "discountType": "Percent",
    "value": 0,
    "validFrom": "2026-08-22T09:14:03Z",
    "validTo": "2026-08-22T09:14:03Z",
    "isActive": true,
    "totalUsageCap": 0,
    "perCustomerCap": 0,
    "scopedVariantIds": [
      "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b"
    ],
    "minOrderValue": 0,
    "usageCount": 0,
    "createdAt": "2026-08-22T09:14:03Z",
    "lastModifiedAt": "2026-08-22T09:14:03Z"
  },
  "details": null
}