Availability

`POST /api/v1/products/:id/availability`

Check whether a product can be fulfilled at a given denomination and quantity. This is a real-time check against current inventory — use it before placing orders to avoid failures.

This endpoint is not cached. Each call checks live inventory.

Request

curl -X POST "{{host}}/api/v1/products/123/availability" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 50.00,
    "quantity": 5
  }'

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "denomination": 50.00,
        "quantity":     5,
    })

    req, _ := http.NewRequest("POST", "{{host}}/api/v1/products/123/availability", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result struct {
        IsAvailable bool `json:"is_available"`
    }
    json.NewDecoder(resp.Body).Decode(&result)

    if result.IsAvailable {
        fmt.Println("Product is available — safe to order")
    } else {
        fmt.Println("Product is currently unavailable at this denomination/quantity")
    }
}

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Product ID (path parameter)
`denomination`	number	Yes	Face value to check. Must be greater than 0.
`quantity`	integer	Yes	Number of vouchers to check. Must be greater than 0.

Response

{
  "is_available": true
}

Response Fields

Key	Type	Description
`is_available`	boolean	`true` if the product can be fulfilled at the requested denomination and quantity

How Availability is Determined

The platform checks whether there is sufficient inventory for the requested denomination and quantity. A product is available if inventory can fulfill the order.

Errors

400 Bad Request — Product ID is not valid.

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid product ID"
  }
}

400 Bad Request — Denomination or quantity is invalid.

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Denomination must be > 0"
  }
}

404 Not Found — Product does not exist or is blacklisted.

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}

401 Unauthorized — Missing or invalid JWT token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

POST /api/v1/products/:id/availability