B2B Partner API

◉ Overview

A REST API over HTTPS. JSON in, JSON out. Every response uses a consistent { data, meta, errors } envelope.

The API exposes HolidaySG's bookable inventory — attractions, tours and tickets — sourced from our suppliers and normalised into a single catalog. You browse products, check live availability, lock a price, and book. Money settles through your wallet or an approved credit line. SEO/marketing content is never exposed; you receive only the fields you need to transact.

➜ API workflow

Five steps from browsing to a confirmed ticket. Each maps to one endpoint.

1. Understand product structure and map our products to yours (Product → Option → Ticket Type).
2. Get live availability & pricing for a date (availability) then lock the price.
3. Provide booking information (quote + customer) to create a paid transaction (book).
4. Receive fulfilment — the e-ticket is delivered to the customer and you are notified by webhook.

🚀 Getting access

1. Apply for a B2B partner account. Once approved you are placed in a commission group (default 1%).
2. We issue a sandbox API key and its signing secret. Store the secret securely — it is shown only once.
3. Build against sandbox (no real money or inventory) and complete the certification checklist.
4. On certification we issue a production key and, if agreed, a credit line.

Verify a key at any time:

curl https://holidaysg.com/api/b2b/v1/me -H "X-Api-Key: <your-key>"

→ { "data": { "partner": { "id": 12, "name": "Acme Travel", "tier": 2, "currency": "SGD" },
      "api_key": { "name": "Prod", "prefix": "hsg_b2b_ab12", "scopes": [], "last_used_at": "..." } } }

🧩 Environments

There is one base URL for everything. Sandbox vs production is decided by which key you send — not by a different host.

🔑 Authentication

Send your API key on every request.

X-Api-Key: hsg_b2b_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are stored hashed — we never see the raw key after issue. Money-moving requests additionally require a signature.

🎚 Scopes

Each key carries a set of scopes. An empty scope list means full access (backward-compatible default); a non-empty list is strictly enforced per endpoint.

✍ Request signing

Money-moving calls — POST /bookings and POST /bookings/{id}/cancel — require an HMAC-SHA256 signature (plus /signature/verify to test it).

X-Api-Timestamp: <unix seconds>
X-Api-Nonce:     <unique per request>
X-Api-Signature: hex( hmac_sha256(canonical, signing_secret) )

canonical = timestamp "\n" METHOD "\n" path "\n" nonce "\n" rawBody

• path includes the leading slash, no query string (e.g. /api/b2b/v1/bookings).
• rawBody is the exact JSON bytes you send — sign the string you transmit.
• Timestamp must be within 5 minutes of server time; each nonce is single-use (replays are rejected).

Dry-run: POST /signature/verify

Validate your signing implementation with no side effects. Note that /signature/verify is itself a signed endpoint — send the same three signature headers you would on a booking, computed over this request's own canonical string (path = /api/b2b/v1/signature/verify). The server recomputes the signature and confirms the match.

POST /signature/verify
Headers: X-Api-Key, X-Api-Timestamp, X-Api-Nonce, X-Api-Signature
{ ...any JSON body (may be empty)... }

→ 200 { "data": { "verified": true,
        "echo": { "method": "POST", "path": "/api/b2b/v1/signature/verify",
                  "timestamp": "...", "nonce": "...", "body_sha256": "..." } } }

♻ Idempotency

Booking is safe to retry. Send a unique Idempotency-Key header on POST /bookings.

Idempotency-Key: 2f9c1e77-....-per-booking-attempt

• First call → 201 and the booking is created.
• Any retry with the same key → 200 returning the original booking. You are never charged twice.
• Reuse the same key only for the same logical booking. Use a fresh key for a new booking.

⏱ Rate limits

Per-partner, by tier. Every response carries the current window.

X-RateLimit-Limit: 60     # your tier's per-minute quota
X-RateLimit-Remaining: 57
Retry-After: 12           # present on 429

Over the limit → 429 RATE_LIMIT_EXCEEDED. Back off and honour Retry-After.

✉ Envelope & pagination

Every response — success or error — has the same shape.

{ "data": ... ,
  "meta": { "request_id": "01J...", "timestamp": "2026-08-15T07:57:00+00:00" },
  "errors": [ { "code": "...", "message": "..." } ] }

Quote request_id when contacting support — it identifies the exact call in our logs.

Cursor pagination

List endpoints are cursor-paginated. meta carries the cursors; pass one back as ?cursor=.

"meta": { "per_page": 20, "next_cursor": "eyJpZCI6...", "prev_cursor": null }

GET /products?per_page=20&cursor=eyJpZCI6...

⚠ Errors

Errors return the standard envelope with a machine code in errors[].code and a matching HTTP status.

▦ Product structure

Every product is organised as Product → Option → Ticket Type. You map these ids to your own catalog, then reference them when quoting and booking.

▤ Catalog

Query parameters

curl "https://holidaysg.com/api/b2b/v1/products?country=Singapore&per_page=20" -H "X-Api-Key: <key>"

📅 Availability

Returns the options and their ticket_type_ids that are bookable for that date — this is where you get the ticket_type_id to quote and book (they are not on the catalog/product record). Availability is fetched live from the source at request time — if the source is unreachable you get 503 SOURCE_UNAVAILABLE (retry), never a stale “available”.

curl "https://holidaysg.com/api/b2b/v1/products/hsgp_1/availability?date=2026-08-20&pax=2" -H "X-Api-Key: <key>"

💲 Pricing model

Simple and transparent: one currency, your price only. You never see supplier nett cost or the margin — your commission is already baked into what you pay.

There is no separate tax or FX step — total is exactly what leaves your wallet/credit. Your own selling price and margin to your customer are yours to set on top.

🔒 Quotes

A quote locks the price for 15 minutes and returns a single-use quote_id you pass to booking. This guarantees the price you saw is the price you pay.

POST /quotes
{ "product_id": "hsgp_1",
  "date": "2026-08-20",
  "items": [ { "ticket_type_id": "tt_94", "quantity": 2 } ] }

→ { "data": {
     "quote_id": "q_XXXX", "product_id": "hsgp_1", "date": "2026-08-20", "currency": "SGD",
     "lines": [ { "ticket_type_id":"tt_94", "name":"ADULT", "quantity":2, "unit_price":56.41, "sub_total":112.82 } ],
     "total": 112.82,
     "expires_at": "2026-08-20T07:57:00+00:00" } }

• A quote is consumed by exactly one successful booking; a used or expired quote → 409 QUOTE_EXPIRED.
• Re-quote if the customer takes longer than the 15-minute window.

🔁 Booking lifecycle

One call books money-safely. Internally we debit first, then confirm with the supplier, and compensate automatically if anything fails — so you are never left paying for an unconfirmed ticket.

🎫 Create a booking

POST /bookings
Headers: X-Api-Key, X-Api-Timestamp, X-Api-Nonce, X-Api-Signature, Idempotency-Key
{ "quote_id": "q_XXXX", "payment_method": "wallet",
  "customer": { "name": "Jane Tan", "email": "jane@example.com" } }

→ 201 { "data": { "booking_id": "b_XXXX", "status": "confirmed",
        "total": 112.82, "currency": "SGD",
        "customer": { "name": "Jane Tan", "email": "jane@example.com" },
        "created_at": "2026-08-15T07:57:00+00:00", "note": null } }

See the lifecycle for the 200 / 202 / 402 / 502 paths.

🔎 Retrieve bookings

Poll GET /bookings/{id} to follow a 202 pending booking to its terminal state, or rely on the webhook.

↩ Cancel & refunds

• 200 cancelled — refund returned to the source of payment (wallet, or credit reversed). Idempotent: cancelling an already-cancelled booking returns 200 without a second refund.
• 409 BOOKING_NOT_CANCELLABLE — already cancelled, or past the supplier cut-off. No money moves.

📩 Vouchers & fulfilment

HolidaySG fulfils the ticket — you don't have to.

On confirmed, the e-ticket / voucher is issued by the supplier and delivered by email to the customer.email on the booking. You can:

• Follow fulfilment via the booking status (GET /bookings/{id}), and
• Receive a webhook when the transaction updates.

🔔 Webhooks

We push booking updates to your endpoint so you don't have to poll. Deliveries retry with backoff and dead-letter after repeated failures.

Verifying a webhook

Each POST to your URL carries a signature over the raw request body, keyed by your webhook secret:

X-Webhook-Event:     BOOKING_TRANSACTION_UPDATE
X-Webhook-Signature: base64( hmac_sha256(rawBody, webhook_secret) )

# verify (pseudo)
expected = base64(hmac_sha256(request.rawBody, webhook_secret))
if !constant_time_equal(expected, header["X-Webhook-Signature"]) -> reject 400

• Respond 2xx quickly to acknowledge; non-2xx (or timeout) triggers retries.
• Treat delivery as at-least-once — dedupe on the booking id + state.

👛 Wallet & credit

Two ways to settle. Both are debited atomically at booking time.

Top-ups are done by card in the partner portal (not via this API — card handling stays on our PCI surface).

📄 Statements

Statements are the source of truth for reconciliation. They are generated at month close and available for every period you were active.

🧪 Sandbox & certification

Build safely on a sandbox key — bookings are simulated (no real inventory, no real money) — then certify to go live.

{ "data": { "sandbox_key": true, "certified": false, "completed": 4, "total": 7,
    "steps": [ {"key":"auth","done":true}, {"key":"catalog","done":true},
               {"key":"availability","done":true}, {"key":"quote","done":true},
               {"key":"signing","done":false}, {"key":"booking","done":false}, {"key":"cancel","done":false} ] } }

📘 Glossary

Need a key, a higher tier, a credit line, or voucher-payload delivery? Contact your HolidaySG account manager.