Developers
Bidali gift card store API
A free, read-only JSON API for the gift card catalogue on this site: countries, categories, currencies and brands, with amounts, redemption instructions and terms. No sign-up and no API key.
Quickstart
Your first requests
Every endpoint is a GET request that returns JSON. Copy a command and run it.
List the countries with gift cards
curl -s https://giftcards.bidali.com/api/v1/countriesFind grocery gift cards in Canada
curl -s "https://giftcards.bidali.com/api/v1/countries/canada/brands?category=groceries&limit=5"Get one brand: amounts, redemption and terms
curl -s https://giftcards.bidali.com/api/v1/countries/canada/brands/doordash-caRead any page as Markdown
curl -s -H "Accept: text/markdown" https://giftcards.bidali.com/brands/canada/doordash-ca
Reference
Endpoints
All paths are relative to https://giftcards.bidali.com. The OpenAPI document describes every parameter and response.
| Path | Method | What it returns |
|---|---|---|
/api/v1 | GET | Describe the Catalogue API |
/api/v1/countries | GET | List the countries with gift cards |
/api/v1/categories | GET | List the gift card categories |
/api/v1/currencies | GET | List the currencies gift cards are priced in |
/api/v1/countries/{country}/brands | GET | List the brands on sale in a country |
/api/v1/countries/{country}/brands/{brand} | GET | Get one brand: amounts, redemption and terms |
/api/v1/openapi.json | GET | Get this OpenAPI document as JSON |
/api/v1/openapi.yaml | GET | Get this OpenAPI document as YAML |
Machine-readable
Everything an agent can read
OpenAPI 3.1
/openapi.json and /openapi.yaml describe every endpoint, parameter and response, for SDK generators and tool calling.
Markdown pages
Send Accept: text/markdown to any page, or add .md to its path (/index.md for the home page), to get it as Markdown.
llms.txt
/llms.txt explains the store in plain language and when to use it.
Sitemap
/sitemap.xml lists every page, with its address in each language.
Errors
Errors are JSON, with the HTTP status that fits: 400 for a missing or invalid parameter, 404 for an unknown country, brand or path, 405 for any method but GET, and 502 or 504 when the catalogue service fails. The code field does not change; the hint field says what to do next.
{
"error": {
"code": "country_not_found",
"message": "No country matches \"atlantis\".",
"hint": "Use a slug or an ISO 3166-1 alpha-2 code from GET /api/v1/countries.",
"docs": "https://giftcards.bidali.com/developers#errors"
}
}Responses are cached for up to five minutes. A page holds at most 100 brands: follow pagination.next for the rest.
Buying in code
Buy gift cards with the Bidali Gift Card API
This API only reads the catalogue. To buy gift cards from your own software or an AI agent, use the Bidali Gift Card API. It works with API keys and is in early access.
MCP access is coming.
Questions from developers
Do I need an API key?
Not for the catalogue API on this site: it is public and read-only. The Bidali Gift Card API, which places orders, uses API keys.
Can I buy a gift card with this API?
No, it only reads the catalogue. Send a person to the brand's page on this site (links.page in every response) to buy it, or use the Bidali Gift Card API to buy in code.
Is there a rate limit?
There is no published limit. Responses are cached for a few minutes, so fetch a list once and reuse it.
Is there an MCP server?
MCP access is coming.