> For the complete documentation index, see [llms.txt](https://kbase.whitelabel-loyalty.com/product/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types/merchandise.md). # Merchandise ## Merchandise Use merchandise rewards to deliver physical goods or stock-limited items, with built-in inventory tracking and optional delivery address capture at purchase. Merchandise rewards are designed for items that have a finite supply and may require a delivery address — branded products, event tickets, limited-edition goods, or any other item you fulfil outside the Loyalty Engine. Unlike voucher rewards, which issue codes for redemption, merchandise rewards track stock levels directly and can prompt users to enter a delivery address during purchase. This makes them the right choice when you need to know *where to send something* and *how many you have left*. {% hint style="info" %} **Fulfilment is handled outside the Loyalty Engine.** Merchandise rewards capture the purchase and delivery details. You export this data and handle shipping, dispatch, or delivery through your own processes. {% endhint %} *** ### When to use merchandise rewards Merchandise rewards are best for: * Physical goods that need to be shipped to a user * Digital items fulfilled externally (e.g. emailed tickets) where stock tracking is still needed but no delivery address is required #### Merchandise vs vouchers Choose merchandise when you need inventory control and/or address capture. Choose vouchers when you need code-based redemption (discount codes, POS validation, static codes). If you need both stock tracking and a code, use a voucher with a code pool — the pool size acts as the stock limit. Quick guide: * Use [**Merchandise**](/product/loyalty-engine/rewards-and-points/rewards/reward-types/merchandise.md) for stock-managed items, shipped goods, or limited allocations * Use [**Vouchers**](/product/loyalty-engine/rewards-and-points/rewards/reward-types/vouchers.md) for code-based redemption, POS validation, or discount workflows * Use [**Reward Fulfilment**](/product/modules/reward-fulfilment.md) when you want WLL to handle third-party gift card delivery If you're still deciding, see [**Which reward type should I use?**](/product/loyalty-engine/rewards-and-points/rewards/reward-types/which-reward-type-should-i-use.md). | Capability | Merchandise | Vouchers | | ---------------- | ------------------------- | -------------------- | | Stock tracking | Built-in (capacity model) | Via code pool size | | Address capture | Yes (optional per reward) | No | | Redemption codes | No | Yes (multiple types) | | POS integration | No | Yes | *** ### Stock management Every merchandise reward tracks inventory using three values: | Field | Description | Editable | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | **Stock Capacity** | The total number of units you have made available for this reward. This is a cumulative ceiling — it increases as you receive new stock. | Yes (admin) | | **Stock Consumed** | The number of units that have been purchased by users. Incremented automatically with each purchase. | No (system-managed) | | **Stock Remaining** | The number of units still available. Calculated as Stock Capacity minus Stock Consumed. | No (derived) | #### Adding and removing stock To add stock, enter the number of new units in the console. The system adds this to the current Stock Capacity automatically. For example, if your current capacity is 100 and you receive 90 new units, add 90 — the capacity updates to 190 and remaining stock adjusts accordingly. You can also remove stock — for example, if a batch is damaged. The system will not allow you to reduce capacity below the current consumed count. #### Out of stock behaviour When Stock Remaining reaches zero, the reward stays visible but becomes non-purchasable. Users can still see the reward in listings, but they cannot purchase it. The reward becomes purchasable again once you increase the Stock Capacity. #### Low-stock notifications You can configure email alerts when stock drops below a threshold. This works the same way as low-stock notifications for voucher code pools. Set a quantity threshold and one or more email addresses in the reward’s notification settings. When remaining stock falls below the threshold after a purchase, the system sends a notification. *** ### Delivery address capture **How address capture works** When *Requires Delivery Address* is enabled on a merchandise reward, the purchase API response includes an address capture prompt. Your front end should present an address collection form before confirming the purchase. The expected fields are: * Recipient name * Street address * City * Region * Postcode * Country * Telephone number If the user already has an address saved in their profile, the API returns those details so your front end can pre-fill the form. The user can edit the address before confirming — the delivery address does not need to match their profile. The delivery address is stored as a snapshot on the merchandise benefit, not as a reference to the user’s profile. If the user later updates their profile address, it does not affect previously purchased merchandise benefits. **Restrict delivery to specific countries** You can optionally restrict the countries available for delivery by selecting one or more countries from the *Restrict to Specific Countries* dropdown on the reward. When configured, the API includes only the selected countries in the address capture response, allowing your front end to limit the country options presented to the user. If no restrictions are set, all countries are available. *** ### Purchase and benefits #### What happens when a user purchases 1. The user selects the merchandise reward and clicks purchase. 2. If the reward requires a delivery address, the API returns an address capture prompt for your front end to process and present. 3. Points are deducted (if a price is set). 4. Stock is decremented atomically — if another user purchases the last unit at the same moment, only one purchase succeeds. 5. A merchandise benefit is created in the user’s wallet, recording the delivery address (if applicable). 6. A `PURCHASED_REWARD` event is emitted. #### Merchandise benefits Each purchase creates a merchandise benefit tied to the user. The benefit stores the delivery address snapshot and appears in the user’s wallet. Unlike voucher benefits, merchandise benefits do not have a code or a user-facing redemption step — the benefit represents a fulfilled order rather than a redeemable token. *** ### Fulfilment The Loyalty Engine captures the purchase and delivery data. Fulfilment is your responsibility. You can export merchandise benefit data — including delivery addresses — through reporting tools or the API, then process shipping through your own warehouse, fulfilment partner, or manual workflow. The system does not currently track shipment status, provide tracking numbers, or manage returns. These are handled outside the Loyalty Engine. {% hint style="success" %} Contact your account manager if you'd like to discuss how White Label Loyalty can support with redemption reporting and physical item fulfilment. {% endhint %} *** ### How to configure a merchandise reward Use this flow when setting up a merchandise reward in the Loyalty Console: 1. Create the reward and choose **Merchandise** as the reward type. 2. Set **Stock Capacity** to your current available quantity. 3. Configure other standard fields such as price, reward title, description and artwork. See [reward details](/product/loyalty-engine/rewards-and-points/rewards/reward-details.md) for more information. 4. Optionally configure availability. See [reward availability](/product/loyalty-engine/rewards-and-points/rewards/reward-availability.md) for more details. 5. In the Redemption tab, choose whether the reward requires a delivery address and configure low-stock notifications. {% hint style="success" %} The redemption message of the merchandise reward can be used to communicate next steps to the user. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types/merchandise.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.