Handling Out of Stock
Merit tracks gift card availability and publishes each change in two places:
- The public Product Status page, for people who need to see what is out of stock right now.
- An inventory webhook, for your application to update its own catalog, checkout, or storefront.
Use the status page to view open outages. Use webhooks to apply those changes in your system. There is no polling API for inventory.
This guide is part of the Merit V3 API documentation. Signature checks, retries, and the inventory payload fields are defined there.
Product Status page
Open https://productstatus.meritincentives.com/.
Each incident marked Identified is currently out of stock. The incident title is the brand, and the denomination and currency when the outage is for one face value. The message includes:
| Field on the status page | Meaning |
|---|---|
| ID | Merit internal product id. Useful when you talk to Merit support. |
| SKU | Product identifier. This is the same value as product_id on gift card orders, for example product_c92jlkj234h4b3kb8c3d. |
| Denomination | Face value affected. Omitted when the whole product is out of stock. |
An incident stays Identified while the item is out of stock. When stock returns, Merit posts Resolved with the message "This item is back in stock." and the same ID, SKU, and denomination.
The page is public. It does not require an API key. It shows the current list of outages. It does not push updates into your application. Subscribe to webhooks for that.
Register your webhook URL
Inventory events are delivered only after Merit subscribes your endpoint. Sending order webhooks does not automatically include stock events.
- Expose an HTTPS
POSTendpoint on port 443. The requirements, signature check, and retry policy are the same as Webhooks. - Send that webhook URL to the Merit technical team.
- Ask Merit to subscribe the URL to product inventory events:
catalog.giftcards.inventory.out_of_stockcatalog.giftcards.inventory.available
- Merit registers the URL and shares a secret key. Use that key to verify
X-Merit-Signatureon every request. See Handling Webhook requests.
You can send the same URL you already use for giftcards.order.* events, or a separate URL that only handles stock. Say which URL should receive inventory events. To change or remove the URL later, contact the Merit technical team again.
What you receive
Each notification is an Inventory Event. Verify the signature, then read event_type and data.
event_type |
data.inventory_status |
What changed |
|---|---|---|
catalog.giftcards.inventory.out_of_stock |
OUT_OF_STOCK |
The product, or one denomination, can no longer be sold. |
catalog.giftcards.inventory.available |
AVAILABLE |
The product, or one denomination, can be sold again. |
data.sku is the product_id you already send to Single Order Async. data.scope tells you how wide the change is.
data.scope |
data.denomination |
What to update |
|---|---|---|
denomination |
Face value, such as 10 or 50 |
Only that face value of the SKU. Other denominations of the same SKU stay as they are. |
product |
null |
The whole product. A face value is sellable only when the product flag and that denomination are both available. |
One SKU can have several denomination incidents open at the same time. Treat each pair of sku + denomination as its own availability flag. Treat scope: product as a separate flag on the SKU.
Denomination goes out of stock:
{
"id": "evt_3f1c2a9e-7b44-4d1a-9c6e-1a2b3c4d5e6f",
"created_at": 1760000000,
"event_type": "catalog.giftcards.inventory.out_of_stock",
"data": {
"sku": "product_c92jlkj234h4b3kb8c3d",
"denomination": 10,
"scope": "denomination",
"event_type": "catalog.giftcards.inventory.out_of_stock",
"event_timestamp": "2026-10-06T10:14:42Z",
"inventory_status": "OUT_OF_STOCK"
}
}
Whole product is available again.
denominationisnull:
{
"id": "evt_8a4d1b2c-6e55-4f0b-8d7a-9f0e1d2c3b4a",
"created_at": 1760003600,
"event_type": "catalog.giftcards.inventory.available",
"data": {
"sku": "product_c92jlkj234h4b3kb8c3d",
"denomination": null,
"scope": "product",
"event_type": "catalog.giftcards.inventory.available",
"event_timestamp": "2026-10-06T11:14:42Z",
"inventory_status": "AVAILABLE"
}
}
Field definitions are in Inventory Event Object and Inventory Data Object.
How to handle an event
- Read the raw request body. You need the exact bytes to verify the signature.
- Verify
X-Merit-Signaturewith your webhook secret. Reject the request when the signature does not match. Merit retries delivery for up to 2 days, with a maximum of 15 attempts. See Retry Policy. - Parse the JSON. Ignore event types your endpoint does not handle, and still return HTTP
2xxfor those so Merit stops retrying them. A shared order-and-inventory endpoint will receive bothgiftcards.order.*andcatalog.giftcards.inventory.*. - Store the event
id. If you have already processed thatid, return HTTP2xxand stop. Retries send the same event again. - Compare
data.event_timestampwith the timestamp you last applied for thatskuand scope. Apply the event when it is newer. Keep the status you already have when an older retry arrives after a newer one. - Update your catalog:
OUT_OF_STOCKandscope: denomination— mark that face value unavailable. Leave other face values of the same SKU unchanged.OUT_OF_STOCKandscope: product— mark the SKU unavailable.AVAILABLEandscope: denomination— mark that face value available again.AVAILABLEandscope: product— mark the SKU available again.
- A denomination is sellable when the product flag is available and that denomination is available. Treat a flag you have never received as available. When either flag is
OUT_OF_STOCK, hide that option or show it as out of stock, and keep it off Single Order Async. - Return HTTP
2xxonly after the status is stored. A2xxtells Merit the event was accepted. Processing after you have stored the event can finish in the background.
Orders already in progress
Apply inventory events to what you offer next. Leave orders that are already PROCESSING on the order webhook flow. When those orders reach a terminal status, use Get Order Details as you do today.
If you miss an update
Merit retries a failed delivery for up to 2 days. When your endpoint was unavailable for longer than that, or when you suspect the catalog has drifted, reconcile from the Product Status page.
Set each incident that is still Identified to OUT_OF_STOCK. Set an incident to AVAILABLE when Merit has posted Resolved for it. Match on SKU and Denomination. SKU is product_id. When the message has no denomination, treat the incident as scope: product.