The gift card API for people and agents
One REST API to quote, order and deliver gift cards from 4,700+ brands in 150+ countries. Early access is open now.
# 1. Quote a gift card
curl -X POST "$BIDALI_API_URL/v1/quotes" \
-H "Authorization: Bearer $BIDALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"brand": "starbucks-us", "amount": 25, "currency": "USD"}'
# 2. Order it and email it to the recipient
curl -X POST "$BIDALI_API_URL/v1/orders" \
-H "Authorization: Bearer $BIDALI_API_KEY" \
-H "Idempotency-Key: 6f1c2b7e-9d3a-4e58-b1a0-2c5d7e8f9a10" \
-H "Content-Type: application/json" \
-d '{"quote_id": "qt_123", "delivery": {"method": "email", "to": "sam@example.com"}}'Draft, subject to change
API overview
Nine endpoints, one workflow
Find a brand, quote the price, place the order and let the webhook tell you it is done.
- Auth
- Bearer API key in the Authorization header
- Idempotency
- Idempotency-Key header on POST /v1/orders
- Delivery
- email, sms, link or inline in the order response
- Sandbox host
- Announced at early access
| Method | Endpoint | What it does |
|---|---|---|
GET | /v1/countries | List countries where gift cards are sold.Returns ISO country codes and names. |
GET | /v1/currencies | List supported currencies.Returns currency codes and minor-unit precision. |
GET | /v1/brands | Search the catalog.Query: country, category. Paginated. |
GET | /v1/brands/{slug} | Get one brand.Denominations, terms and redemption instructions. |
POST | /v1/quotes | Price a gift card before you buy it.Body: brand, amount, currency. Returns a quote that expires. |
POST | /v1/orders | Order a gift card from a quote.Body: quote_id, delivery (email, sms, link or inline). Send an Idempotency-Key header. |
GET | /v1/orders/{id} | Get an order and its status.Returns the gift card once the order is fulfilled. |
GET | /v1/balance | Get your prepaid balance.Returns available balance and recent statement lines. |
POST | /v1/webhooks | Register a webhook.Body: url, events (order.fulfilled, order.failed, balance.low). |
In code
From catalog to delivered gift card
Plain HTTPS and JSON. If you can call curl or fetch, you can sell a gift card.
Browse and register a webhook
# Groceries available in Canada
curl "$BIDALI_API_URL/v1/brands?country=CA&category=groceries" \
-H "Authorization: Bearer $BIDALI_API_KEY"
# Get told when an order is done or your balance runs low
curl -X POST "$BIDALI_API_URL/v1/webhooks" \
-H "Authorization: Bearer $BIDALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/bidali", "events": ["order.fulfilled", "order.failed", "balance.low"]}'Quote and order
// uuid() is any UUID generator; store the key with your own order record.
const base = process.env.BIDALI_API_URL!;
const headers = {
Authorization: `Bearer ${process.env.BIDALI_API_KEY}`,
'Content-Type': 'application/json',
};
const quote = await fetch(`${base}/v1/quotes`, {
method: 'POST',
headers,
body: JSON.stringify({ brand: 'starbucks-us', amount: 25, currency: 'USD' }),
}).then((res) => res.json());
const order = await fetch(`${base}/v1/orders`, {
method: 'POST',
headers: { ...headers, 'Idempotency-Key': uuid() },
body: JSON.stringify({
quote_id: quote.id,
delivery: { method: 'email', to: 'sam@example.com' },
}),
}).then((res) => res.json());
console.log(order.id, order.status);Built for production
What you need to ship it
Sandbox
Test every call with fake orders before you touch production, with the same responses and errors.
Webhooks
Get told when an order is fulfilled or fails, and when your balance runs low.
Idempotent orders
Send an Idempotency-Key and retry safely. A network error never buys the same gift card twice.
Balance and statements
Check your balance in one call and reconcile every order against your statement.
Machine-readable docs
An OpenAPI 3.1 spec for SDK generators and AI agents, so a tool call is one import away.
Use cases
What teams build with it
The same calls power rewards, payroll perks and AI agents.
Customer incentives
Sign-up bonuses, referrals and research payouts.
Employee rewards
Rewards your team will use, in any country.
Agentic commerce
Give your AI agent a budget, not a credit card.
Early access
Get access to the sandbox
Tell us what you are building. We are onboarding a small group of teams and will reply with sandbox details.