{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"Bidali gift card store Catalogue API","version":"1.0.0","summary":"Read-only API for the public gift card catalogue of giftcards.bidali.com.","description":"A read-only API for browsing the public gift card catalogue of the Bidali gift card store: which countries, categories and currencies gift cards are available in, which brands are on sale in a country, and the amounts, redemption instructions and terms of one brand.\n\nUse it to answer questions such as \"which grocery gift cards can I buy for Canada?\" or \"what amounts does this gift card come in?\", and to send a person the storefront link where they can buy it (`links.page` on every brand). Bidali Inc. is a software company and an independent reseller of gift cards; brands do not sponsor or endorse Bidali.\n\nThis API does not sell anything. To buy gift cards in code, use Bidali's commercial Gift Card API, which uses API keys: see https://www.bidali.com/products/gift-card-api and the documentation at https://docs.bidali.com, or talk to sales at https://www.bidali.com/contact?intent=sales.\n\nNo authentication. Every response is JSON (UTF-8) with `Access-Control-Allow-Origin: *`. Errors always have the shape `{ \"error\": { \"code\", \"message\", \"hint\", \"docs\" } }`. Responses are cached for a few minutes, so a brand added or removed can take that long to show. Amounts are in major units of the currency (12.5 is 12.50).","contact":{"name":"Bidali","url":"https://giftcards.bidali.com/developers"},"termsOfService":"https://www.bidali.com/legal/terms"},"externalDocs":{"description":"Developer guide","url":"https://giftcards.bidali.com/developers"},"servers":[{"url":"https://giftcards.bidali.com","description":"Bidali gift card store"}],"tags":[{"name":"Catalogue","description":"Countries, categories, currencies and brands."},{"name":"Meta","description":"The API itself."}],"paths":{"/api/v1":{"get":{"operationId":"getApiIndex","tags":["Meta"],"summary":"Describe the Catalogue API","description":"Returns what this API is for, where its OpenAPI document and documentation are, and the list of endpoints. Start here.","parameters":[],"responses":{"200":{"description":"The API index.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/v1/countries":{"get":{"operationId":"listCountries","tags":["Catalogue"],"summary":"List the countries with gift cards","description":"Every country with at least one brand on sale, with the number of brands and the storefront and API URLs for it. A gift card is listed under the country it is for; use the `slug` or `code` with the brand endpoints.","parameters":[],"responses":{"200":{"description":"Countries, sorted by name.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryList"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","tags":["Catalogue"],"summary":"List the gift card categories","description":"The categories brands are grouped in (groceries, gaming, travel…). Use a category `slug` as the `category` filter of the brand list.","parameters":[],"responses":{"200":{"description":"Categories, sorted by name.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/v1/currencies":{"get":{"operationId":"listCurrencies","tags":["Catalogue"],"summary":"List the currencies gift cards are priced in","description":"Every currency a gift card on this store has its value in (ISO 4217), with the number of brands and the countries they are for. A gift card keeps the currency it is priced in.","parameters":[],"responses":{"200":{"description":"Currencies, most brands first.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrencyList"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/v1/countries/{country}/brands":{"get":{"operationId":"listBrands","tags":["Catalogue"],"summary":"List the brands on sale in a country","description":"The brands you can buy a gift card for in one country, featured brands first, then by name. Filter by category, product type or a search term, and page through with `limit` and `offset`. Each item links to the brand endpoint and to the storefront page where a person can buy it.","parameters":[{"name":"country","in":"path","required":true,"description":"The country the gift cards are for: its slug (`canada`) or its ISO 3166-1 alpha-2 code (`CA`), as listed by `GET /api/v1/countries`.","schema":{"type":"string","pattern":"^(?:[a-z0-9]+(?:-[a-z0-9]+)*|[A-Za-z]{2})$","maxLength":64},"example":"canada"},{"name":"category","in":"query","required":false,"description":"Only brands in this category: a `slug` from `GET /api/v1/categories`.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","maxLength":64},"example":"groceries"},{"name":"type","in":"query","required":false,"description":"Only brands of this product type. `giftcard` is a gift card; the others are mobile and prepaid products.","schema":{"type":"string","enum":["giftcard","topup","data","pin","bundle","digitaltv","esim","longdistance"]},"example":"giftcard"},{"name":"q","in":"query","required":false,"description":"Search term, matched against brand names in this country.","schema":{"type":"string","minLength":2,"maxLength":100},"example":"amazon"},{"name":"limit","in":"query","required":false,"description":"How many brands to return, 50 by default, at most 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":20},{"name":"offset","in":"query","required":false,"description":"How many brands to skip. Use `pagination.next` to get the next page.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"example":0}],"responses":{"200":{"description":"One page of brands.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"502":{"$ref":"#/components/responses/UpstreamError"},"504":{"$ref":"#/components/responses/UpstreamTimeout"}}}},"/api/v1/countries/{country}/brands/{brand}":{"get":{"operationId":"getBrand","tags":["Catalogue"],"summary":"Get one brand: amounts, redemption and terms","description":"Everything about one brand's gift card in one country: the product type, the amounts it is sold in and their currency, how it is delivered and redeemed, the issuer's description and terms, and the storefront URL to send a person to.","parameters":[{"name":"country","in":"path","required":true,"description":"The country the gift cards are for: its slug (`canada`) or its ISO 3166-1 alpha-2 code (`CA`), as listed by `GET /api/v1/countries`.","schema":{"type":"string","pattern":"^(?:[a-z0-9]+(?:-[a-z0-9]+)*|[A-Za-z]{2})$","maxLength":64},"example":"canada"},{"name":"brand","in":"path","required":true,"description":"The brand slug, as returned in `slug` by the brand list.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","maxLength":128},"example":"doordash-ca"}],"responses":{"200":{"description":"The brand.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"502":{"$ref":"#/components/responses/UpstreamError"},"504":{"$ref":"#/components/responses/UpstreamTimeout"}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiJson","tags":["Meta"],"summary":"Get this OpenAPI document as JSON","description":"This document, also served at `/openapi.json`.","parameters":[],"responses":{"200":{"description":"OpenAPI 3.1 document.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/v1/openapi.yaml":{"get":{"operationId":"getOpenApiYaml","tags":["Meta"],"summary":"Get this OpenAPI document as YAML","description":"The same document as YAML, also served at `/openapi.yaml`.","parameters":[],"responses":{"200":{"description":"OpenAPI 3.1 document.","headers":{"Cache-Control":{"description":"How long the response may be reused.","schema":{"type":"string"}}},"content":{"application/yaml":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}}},"components":{"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","docs"],"properties":{"code":{"type":"string","enum":["invalid_parameter","unknown_parameter","country_not_found","brand_not_found","not_found","method_not_allowed","internal_error","upstream_error","upstream_timeout"],"description":"Stable, machine-readable error code."},"message":{"type":"string","description":"What went wrong, in one sentence."},"hint":{"type":"string","description":"What to do about it."},"docs":{"type":"string","format":"uri","description":"Where the error format and every endpoint are described."}}}},"example":{"error":{"code":"country_not_found","message":"No country matches \"atlantis\".","hint":"Use a slug or code from GET /api/v1/countries.","docs":"https://giftcards.bidali.com/developers#errors"}}},"CountryRef":{"type":"object","additionalProperties":false,"required":["code","slug","name"],"properties":{"code":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 code."},"slug":{"type":"string","description":"URL slug of the country."},"name":{"type":"string","description":"English name."}}},"Country":{"type":"object","additionalProperties":false,"required":["code","slug","name","brandCount","links"],"properties":{"code":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 code."},"slug":{"type":"string","description":"URL slug of the country."},"name":{"type":"string","description":"English name."},"brandCount":{"type":"integer","minimum":1,"description":"Brands on sale for this country when the site was last built."},"links":{"type":"object","additionalProperties":false,"required":["page","browse","brands"],"properties":{"page":{"type":"string","format":"uri","description":"Storefront page about gift cards in this country."},"browse":{"type":"string","format":"uri","description":"Storefront page listing every brand in this country."},"brands":{"type":"string","format":"uri","description":"API URL of the brands in this country."}}}}},"CountryList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}},"Category":{"type":"object","additionalProperties":false,"required":["id","slug","name","description","links"],"properties":{"id":{"type":"string","description":"Stable identifier."},"slug":{"type":"string","description":"Use as the `category` filter of the brand list."},"name":{"type":"string","description":"English name."},"description":{"type":"string","description":"One line about what the category holds."},"links":{"type":"object","additionalProperties":false,"required":["page"],"properties":{"page":{"type":"string","format":"uri","description":"Storefront page of the category."}}}}},"CategoryList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"CategoryRef":{"type":"object","additionalProperties":false,"required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"Currency":{"type":"object","additionalProperties":false,"required":["code","slug","name","brandCount","countries","links"],"properties":{"code":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code."},"slug":{"type":"string","description":"Lowercase code, as used in storefront URLs."},"name":{"type":"string","description":"English name."},"brandCount":{"type":"integer","minimum":1,"description":"Brands priced in this currency."},"countries":{"type":"array","description":"Countries with brands priced in this currency, most brands first.","items":{"type":"object","additionalProperties":false,"required":["code","slug","name","brandCount"],"properties":{"code":{"type":"string","pattern":"^[A-Z]{2}$"},"slug":{"type":"string"},"name":{"type":"string"},"brandCount":{"type":"integer","minimum":1}}}},"links":{"type":"object","additionalProperties":false,"required":["page"],"properties":{"page":{"type":"string","format":"uri","description":"Storefront page of gift cards priced in this currency."}}}}},"CurrencyList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Currency"}}}},"BrandLinks":{"type":"object","additionalProperties":false,"required":["page","markdown","api"],"properties":{"page":{"type":"string","format":"uri","description":"Storefront page where a person can buy this gift card. Send people here."},"markdown":{"type":"string","format":"uri","description":"The same page as Markdown."},"api":{"type":"string","format":"uri","description":"API URL of this brand."}}},"BrandSummary":{"type":"object","additionalProperties":false,"required":["id","slug","name","type","featured","country","categories","imageUrl","links"],"properties":{"id":{"type":"string","description":"Stable identifier."},"slug":{"type":"string","description":"URL slug, unique within a country."},"name":{"type":"string"},"type":{"type":"string","description":"Product type. Known values: giftcard, topup, data, pin, bundle, digitaltv, esim, longdistance. `giftcard` is a gift card.","examples":["giftcard"]},"featured":{"type":"boolean","description":"Promoted by the store."},"country":{"$ref":"#/components/schemas/CountryRef"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryRef"}},"imageUrl":{"type":["string","null"],"format":"uri","description":"Brand logo."},"links":{"$ref":"#/components/schemas/BrandLinks"}}},"BrandList":{"type":"object","additionalProperties":false,"required":["data","country","filters","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BrandSummary"}},"country":{"$ref":"#/components/schemas/CountryRef"},"filters":{"type":"object","additionalProperties":false,"required":[],"properties":{"category":{"type":"string"},"type":{"type":"string","enum":["giftcard","topup","data","pin","bundle","digitaltv","esim","longdistance"]},"q":{"type":"string"}}},"pagination":{"type":"object","additionalProperties":false,"required":["total","limit","offset","next"],"properties":{"total":{"type":"integer","minimum":0,"description":"Brands matching the filters."},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page; null on the last page."}}}}},"Pricing":{"type":"object","additionalProperties":false,"required":["currency","minAmount","maxAmount","variableAmount","denominations","amountStep"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code."},"minAmount":{"type":"number","minimum":0,"description":"Smallest amount, in major units of `currency`."},"maxAmount":{"type":"number","minimum":0,"description":"Largest amount, in major units of `currency`."},"variableAmount":{"type":"boolean","description":"True when the buyer picks any amount between minAmount and maxAmount; false when only the denominations are sold."},"denominations":{"type":"array","items":{"type":"number","minimum":0,"description":"A fixed amount."},"description":"Fixed amounts, smallest first. Empty when the amount is variable."},"amountStep":{"type":["number","null"],"description":"Variable amounts must be a multiple of this, when above 1."}}},"Product":{"type":"object","additionalProperties":false,"required":["name","type","currency","delivery","variableAmount","minAmount","maxAmount","denominations","validityDays"],"properties":{"name":{"type":"string"},"type":{"type":["string","null"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"delivery":{"type":["string","null"],"description":"`email`: the code is emailed. `phone` / `account`: applied to a number."},"variableAmount":{"type":"boolean"},"minAmount":{"type":["number","null"],"minimum":0,"description":"Smallest amount, in major units."},"maxAmount":{"type":["number","null"],"minimum":0,"description":"Largest amount, in major units."},"denominations":{"type":"array","items":{"type":"number","minimum":0,"description":"A fixed amount."}},"validityDays":{"type":["integer","null"],"description":"Days the product is valid for."}}},"Brand":{"type":"object","additionalProperties":false,"required":["id","slug","name","type","available","country","categories","description","terms","importantNotes","redemption","delivery","pricing","products","websiteUrl","imageUrl","links"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"Product type. Known values: giftcard, topup, data, pin, bundle, digitaltv, esim, longdistance. `giftcard` is a gift card.","examples":["giftcard"]},"available":{"type":"boolean","description":"False when the brand is temporarily out of stock."},"country":{"$ref":"#/components/schemas/CountryRef"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryRef"}},"description":{"type":["string","null"],"description":"The issuer's description, verbatim."},"terms":{"type":["string","null"],"description":"The issuer's terms, verbatim."},"importantNotes":{"type":["string","null"],"description":"Notes from the issuer, verbatim."},"redemption":{"type":"object","additionalProperties":false,"required":["instructions","url","methods"],"properties":{"instructions":{"type":["string","null"],"description":"How to redeem, verbatim."},"url":{"type":["string","null"],"format":"uri","description":"Where the issuer explains redemption."},"methods":{"type":"array","items":{"type":"string"},"description":"Online, In store…"}}},"delivery":{"type":["string","null"],"description":"How the first product is delivered: `email`, `phone` or `account`."},"pricing":{"description":"What the brand sells for, in the currency of its first product. Null when no price is published.","oneOf":[{"$ref":"#/components/schemas/Pricing"},{"type":"null"}]},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"websiteUrl":{"type":["string","null"],"format":"uri","description":"The brand's own website."},"imageUrl":{"type":["string","null"],"format":"uri","description":"Brand logo."},"links":{"$ref":"#/components/schemas/BrandLinks"}}},"ApiIndex":{"type":"object","additionalProperties":false,"required":["name","description","version","openapi","documentation","llms","purchasing","endpoints"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"openapi":{"type":"string","format":"uri","description":"OpenAPI 3.1 document of this API."},"documentation":{"type":"string","format":"uri","description":"Human documentation."},"llms":{"type":"string","format":"uri","description":"Plain-language guide to the store for AI agents."},"purchasing":{"type":"string","format":"uri","description":"Bidali's commercial Gift Card API, for buying in code."},"endpoints":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["method","path","summary","operationId"],"properties":{"method":{"type":"string"},"path":{"type":"string"},"summary":{"type":"string"},"operationId":{"type":"string"}}}}}},"OpenApiDocument":{"type":"object","description":"An OpenAPI 3.1 document.","required":["openapi","info","paths"]}},"responses":{"BadRequest":{"description":"A parameter is missing, unknown or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The country or brand does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MethodNotAllowed":{"description":"Only GET, HEAD and OPTIONS are accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamError":{"description":"The catalogue service failed. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamTimeout":{"description":"The catalogue service was too slow. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}