Skip to content
Gift Card APIEarly access

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.

curl
# 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
Draft — subject to change
Draft Gift Card API endpoints. Draft — subject to change.
MethodEndpointWhat it does
GET/v1/countriesList countries where gift cards are sold.Returns ISO country codes and names.
GET/v1/currenciesList supported currencies.Returns currency codes and minor-unit precision.
GET/v1/brandsSearch the catalog.Query: country, category. Paginated.
GET/v1/brands/{slug}Get one brand.Denominations, terms and redemption instructions.
POST/v1/quotesPrice a gift card before you buy it.Body: brand, amount, currency. Returns a quote that expires.
POST/v1/ordersOrder 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/balanceGet your prepaid balance.Returns available balance and recent statement lines.
POST/v1/webhooksRegister 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

curl
# 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

TypeScript (fetch)
// 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.

Tell us about your project

Share a few details and our team will get back to you.

Contact sales

Frequently asked questions

Early access is open now. We will share a general availability date with early-access teams as soon as it is set.

Limits will be published with the sandbox. Early-access teams help us set them, so tell us your expected volume.

Production access requires a business verification review as part of our full compliance program. You can build in the sandbox before it is complete.

There is no platform fee. You pay for the gift cards you order, and you see the price in a quote before you commit.

The catalog covers 4,700+ brands in 150+ countries. Call GET /v1/countries and GET /v1/brands to see what is available where.

Yes. The API is plain HTTPS and JSON, and the draft OpenAPI 3.1 spec lets an agent call it as a tool. An MCP server is planned.

Start with the sandbox

Request early access and build your first order today.