How to check product availability before purchase

Before letting a customer add a gift card to the cart or complete checkout, verify that the product is in stock. Use POST /orders/check with the product’s item code and desired quantity.

When to use this

Call this endpoint when you need to know “Can I fulfill this many units of this product?” — for example before add-to-cart, on the cart page, or at checkout. Do not use it to get the status of an existing order; for that use GET /orders/{id}.

Step 1: Send a stock check request

Endpoint: POST https://api.cardpluspay.com/v1/orders/check

Body (JSON):

  • item_id (required) — The product item code from the catalog (e.g. GOOGLE-5USD-KOXx).
  • quantity (optional) — Number of units to check; default is 1.

Example request

curl -X POST "https://api.cardpluspay.com/v1/orders/check" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "GOOGLE-5USD-KOXx", "quantity": 1}'

Step 2: Interpret the response

If the product is available in the requested quantity, you get success: true and a message such as “Gift card in Stock”. The data object includes:

  • price — Per-unit amount charged (what you pay per card). Use this for the checkout total so you don’t need to call the catalog again.
  • state — "in_stock" when the requested quantity is available.
  • status — Boolean; true when available.
  • message — Short text (e.g. "Available").
  • requested — The quantity you asked to check.
{
  "success": true,
  "message": "Gift card in Stock",
  "data": {
    "price": 0.85,
    "state": "in_stock",
    "status": true,
    "message": "Available",
    "requested": 1
  }
}

Use success (and data.state === "in_stock" if you prefer) to decide whether to allow the customer to proceed. On failure, show an “out of stock” or “unavailable” message and do not create an order for that item.

Integration tip

Call this after the user selects a product and quantity (or at cart/checkout). If the check fails, disable the purchase button or show a clear message. Then use the same item_id and quantity when you create the order.

← Display products · Integration Guide · Create order →