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.

Health check

Check service availability (authenticated):

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

→ { "data": { "status": "ok", "service": "HolidaySG B2B API", "version": "v1" } }

Verify your key

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.
• Missing the header → 400 IDEMPOTENCY_KEY_REQUIRED.
• Same key with different quote/customer → 409 IDEMPOTENCY_KEY_MISMATCH.

⏱ 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.

A flood guard of 300 requests / minute per source IP also runs before authentication (invalid-key requests count). Tier 3–4 integrations calling from a single IP should contact us to align the per-IP guard with their tier.

✉ 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": 25, "next_cursor": "eyJpZCI6...", "prev_cursor": null }

GET /products?per_page=25&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" },
        "note": null } }

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

🔎 Retrieve bookings

Query parameters (listing)

Response fields

↩ 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. The listing returns the most recent 36 months.

🧪 Sandbox & certification

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

Certification checklist

{ "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} ] } }

Sandbox test products

The sandbox contains a set of test products designed to cover all integration scenarios. Use these product ids in your sandbox calls:

Mandatory test cases

Partners must complete these test scenarios before going live. Progress is tracked automatically from your sandbox API calls.

1 — Happy path: full booking lifecycle

Complete the standard flow end to end with hsgp_test_1.

2 — Idempotent booking retry

3 — Expired quote

4 — Insufficient funds

5 — Duplicate idempotency key with different payload

6 — Traveller answers required

7 — Signature validation errors

8 — Cancelling a non-cancellable booking

9 — Scope and auth errors

10 — Validation and not-found errors

📘 Glossary

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