Scent

Scent is Linra Omni’s perfume and fragrance product line — the first product on the platform (see Platform overview for how a future second product line would show up here alongside it). Everything below is specific to Scent; the endpoints and concepts on this page live under the /api/v1/scent/** URL segment — see URL conventions for the fleet-wide rule this follows.

Endpoint groups

See API Reference → Scent for every operation, one page per endpoint. The groups:

Resource	What it covers
Scent Orders	Create a Scent order from your priced, locked cart.
Catalog	Browse scents, brands, and variants, with delta-sync support.
Cart	Manage your own cart, price a checkout, optionally lock prices.
Returns	Partner self-serve return requests against a delivered order.
Discount Codes	Define and validate your own discount codes.
Reports	Your own sales figures and cart-behavior analytics.
Webhooks	Scent’s own event subscriptions — see the note on the shared mechanism in URL conventions.

Catalog reads (scents, brands, suggestions) accept a ?lang= query parameter to localize names and descriptions — omit it and you get the catalog’s default language.

With ?include=profile, a scent’s info.notes carries four lists: top, heart and base (the fragrance pyramid) and key. Most scents fill the pyramid and leave key empty; a scent whose brand publishes only a single note list (no pyramid) has empty top/heart/base and lists its notes in key, in importance order. Show key as “Key notes” when it is non-empty.

Deeper guides for several of these already exist and aren’t repeated here: Cart preview & price locks, Catalog delta sync, Discount codes, Product marketing, Your sales & cart analytics, and Fulfilment & returns for tracking an order and handling a return.

Order status

A Scent order’s status is the platform-wide UnifiedOrderStatus value — see Order states & errors for the full breakdown (all 7 reachable values, the failureReason sanitized-code contract, and the create-time reject codes). In short: Processing, Completed, Cancelled, PartiallyDelivered, PartiallyReturned, Returned, Failed.

Scent’s own state catalogue

Every other state/status value you’ll encounter on a Scent response, in one place. Each is a plain string field — decode any value you don’t recognize as “an update shipped since you last read this page” rather than an error, and treat an unrecognized value defensively (don’t crash; show a generic fallback).

Returns

Field	Values	Meaning
Return request status	Requested, Accepted, Processing, Refunded, Rejected, Withdrawn	Your return’s own lifecycle — see GET .../return-requests.
reasonCode	Damaged, WrongItem, NotAsDescribed, ChangedMind, Other	Why you’re returning a line — required when creating a return request.

Settlement mode

Field	Values	Meaning
Order line pricingMode, keys of the create response’s modeBreakdown	Wholesale, Retail	Your own settlement mode with Linra for that line — not a Linra price or figure. Wholesale: you pay your wholesale unit price and resell at a price you set; no commission (rrp is filled on a priced variant). Retail: the customer pays the end-user price and you earn a commission on the line (partnerCommission on the line, commission on a priced variant). modeBreakdown sums the order’s line totals (ex-VAT) per mode, e.g. {"Retail": 640.0} for an all-Retail order whose pricing.subtotal is 640.0.

Shipment tracking

Field	Values	Meaning
shipments[].status	Pending, Packed, AwaitingConsolidation, InTransitToSortingPoint, ArrivedAtSortingPoint, InTransitToCustomer, Delivered, Cancelled, FailedDelivery, RefusedReceipt, ReturnedToSender, Lost	Physical shipment lifecycle on GET .../orders/{orderId}/tracking. The last three are exception states; Lost is terminal.

Cart & checkout

Field	Values	Meaning
Cart status	Open, CheckedOut, Abandoned	Your cart’s own lifecycle.
Checkout-preview line issue	UNAVAILABLE, INSUFFICIENT_STOCK, PRICE_NOT_AVAILABLE, NOT_PRICED, VARIANT_NOT_ASSIGNED	Why a specific line can’t check out yet.
Checkout-preview cartIssue	CART_HAS_PENDING_ORDER, PRODUCT_ACCESS_DISABLED, PRICE_NOT_AVAILABLE	Why the WHOLE cart can’t check out.
Variant availability	Available, Limited, Unavailable	3-state stock indicator with line-quantity context.
Variant availabilityStatus (standalone availability endpoint)	OutOfStock, InStock	A simpler 2-state indicator with no quantity context — don’t confuse it with the 3-state field above.
Marketing badges[]	LIMITED, BACK_IN_STOCK, NEW_ARRIVAL, BEST_SELLER, SAMPLE_AVAILABLE	Purely presentational — never affects price or settlement.

Discount codes

Field	Values	Meaning
discountType	Percent, FixedAmount	How a discount code’s value is interpreted.
Validation reason	EMPTY_CART, NOT_FOUND, INACTIVE, NOT_YET_VALID, EXPIRED, BELOW_MIN_ORDER_VALUE, PRODUCT_SCOPE_MISMATCH, ALREADY_USED_BY_CUSTOMER, CAP_REACHED	Present only when valid is false, on POST .../discount-codes/validate.

Webhooks

Field	Values	Meaning
eventType	order.completed, order.failed, order.cancelled, order.returned, order.fulfilment-updated, variant.back-in-stock, order.return-request.updated	Scent’s current event vocabulary — subscribe to any subset. See Webhooks & HMAC verification for the delivery mechanism.