NAV
cURL

Handling Out of Stock

Merit tracks gift card availability and publishes each change in two places:

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.

  1. Expose an HTTPS POST endpoint on port 443. The requirements, signature check, and retry policy are the same as Webhooks.
  2. Send that webhook URL to the Merit technical team.
  3. Ask Merit to subscribe the URL to product inventory events:
    • catalog.giftcards.inventory.out_of_stock
    • catalog.giftcards.inventory.available
  4. Merit registers the URL and shares a secret key. Use that key to verify X-Merit-Signature on 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. denomination is null:

{
  "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

  1. Read the raw request body. You need the exact bytes to verify the signature.
  2. Verify X-Merit-Signature with 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.
  3. Parse the JSON. Ignore event types your endpoint does not handle, and still return HTTP 2xx for those so Merit stops retrying them. A shared order-and-inventory endpoint will receive both giftcards.order.* and catalog.giftcards.inventory.*.
  4. Store the event id. If you have already processed that id, return HTTP 2xx and stop. Retries send the same event again.
  5. Compare data.event_timestamp with the timestamp you last applied for that sku and scope. Apply the event when it is newer. Keep the status you already have when an older retry arrives after a newer one.
  6. Update your catalog:
    • OUT_OF_STOCK and scope: denomination — mark that face value unavailable. Leave other face values of the same SKU unchanged.
    • OUT_OF_STOCK and scope: product — mark the SKU unavailable.
    • AVAILABLE and scope: denomination — mark that face value available again.
    • AVAILABLE and scope: product — mark the SKU available again.
  7. 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.
  8. Return HTTP 2xx only after the status is stored. A 2xx tells 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.