Documentation

Catalogue

GET /v1/catalog returns the offers this partner can sell in the requested currency. The catalogue is partner-specific: discounts, currency conversion and eligibility are applied before the response.

Code
GET /v1/catalog?currency=USD

Query	Values	Default
`currency`	`USD`, `EUR`, `GBP`	`USD`

Unknown currency values fall back to USD.

Eligibility

An offer is returned only when all of these are true:

It covers exactly one country.
The listing is active in a live store.
The upstream product is approved for sale.
The wholesale cost is positive.
The current retail price is at or above the contribution-margin floor.
The product is deduplicated by its upstream product identifier.

The current selector enforces the single-country rule. Regional and global offers are part of the target catalogue contract but are Planned; do not depend on them yet.

Response

Code
{
  "currency": "USD",
  "offers": [
    {
      "offerId": "11111111-1111-4111-8111-111111111111",
      "name": "Thailand 15 GB 7 days",
      "network": "ExampleNet",
      "validityDays": 7,
      "destination": "TH",
      "dataGbPerDay": null,
      "dataGbTotal": 15,
      "isUnlimited": false,
      "available": true,
      "prices": {
        "USD": 899,
        "EUR": 829,
        "GBP": 719
      },
      "discount": {
        "requestedPercent": 10,
        "appliedPercent": 10,
        "amount": 90,
        "finalAmount": 809,
        "capped": false
      }
    }
  ]
}

Field	Meaning
`offerId`	Opaque, stable identifier. Use it in quotes and one-call orders.
`name`	Sanitised public title. Never contains an upstream store or product code.
`network`	Public network label.
`validityDays`	Validity window in days.
`destination`	ISO 3166-1 alpha-2 country code.
`dataGbPerDay`, `dataGbTotal`, `isUnlimited`	Allowance description.
`available`	Advisory stock flag. Not a reservation.
`prices`	List price in minor units for all three currencies.
`discount`	Partner discount, applied discount, amount, final unit price and cap flag.

Amounts are integer minor units: cents for USD and EUR, pence for GBP.

Pricing and FX

The catalogue is priced in USD and converted using the latest FX snapshot. If the EUR or GBP rate is missing or stale, that currency returns:

Code
{
  "error": {
    "code": "fx_unavailable",
    "message": "The selected currency is temporarily unavailable.",
    "requestId": "..."
  }
}

HTTP status is 503. Retry later or request USD. The quote pins the FX snapshot used for its pricing, so the order recheck uses the same contract as the quote.

Availability and stock

available is advisory. A catalogue read does not reserve stock. The quote and the order both recheck price and stock; the order is the first operation that can fail with 409 out_of_stock or 409 price_changed.

Discounts and caps

Each partner has a discount percentage. requestedPercent is the partner's entitlement; appliedPercent is what the margin floor allows. When the requested discount would breach the floor, capped is true and finalAmount is raised to the floor. Always use finalAmount, not the arithmetic of requestedPercent.

What is not exposed

The response deliberately omits upstream store, product code, cost, margin floor, stock count and upstream identity. Public names are sanitised. If an offer cannot be sold white-label, it is not in the catalogue. Do not attempt to infer or reconstruct those fields.

Planned catalogue controls

The target contract adds filters and cursor pagination. These parameters are Planned and their names may change:

Parameter	Purpose
`country`	ISO country code or destination filter.
`type`	Local, regional or global.
`validityDays`	Exact or ranged validity filter.
`search`	Name, destination or network search.
`cursor`	Opaque cursor from a previous page.
`limit`	Page size.

Until they ship, request the currency and page through the returned offers array. Treat the response as the full eligible set for that currency, not as a promise that every upstream product is present.

Quotes to bind an offer and quantity.
Orders to buy the quote or use one-call ordering.
Errors for out_of_stock, price_changed and fx_unavailable.

Errors Quotes