Partner API · v1

Connect your system to PALAU EXPLORER

A machine-to-machine REST API for travel agencies. Read our tours, off-road and jet-ski departures with your own net rates, check live availability, create and cancel reservations, and reconcile your account.

Server-to-server only. Never put a key in a browser, mobile app or public repository.

Base URL

https://palauexplorer.com/api/v1

Authentication

Bearer API key, issued per agency

Rate limit

120 requests per minute per key

Format

JSON over HTTPS, UTF-8

Currency and dates

USD amounts as strings with two decimals. Dates as YYYY-MM-DD, timestamps in RFC 3339.

Overview

The partner API is a machine-to-machine channel for travel agencies. It serves tours, off-road departures and jet-ski departures. Hotels are not bookable through this API.

Read

Published products, descriptions, images and your net rates.

Book

Live availability, reservations with idempotent writes, and cancellations.

Reconcile

Your invoices, payments and balance for a travel window.

Every call is scoped, rate limited and logged. A key always belongs to one agency and can only read or change the data of that agency.

Getting access

The API is open to travel agencies with a partner agreement. There is no self-service signup: every agency and every key is set up by our team.

  1. Contact our partner team with your company name, country, website, technical contact and expected monthly volume.
  2. We agree your commission rate, cancellation schedule and payment terms, then create your agency record.
  3. We issue a test key. It reads real catalog and availability data, but the bookings it writes are test records that never reserve stock or count in your statement.
  4. You build and test the integration against the test key.
  5. When you are ready, send us the fixed IP addresses your system will call from. We allowlist them and issue a live key.
  6. Switch the token, run the go-live checks below and start booking.
Request partner access

Keys and authentication

Send the key as a bearer token on every authenticated call:

Authorization: Bearer pk_live_01J4Z9K8YQ7V6N5M4P3R2S1T0H.7fK2pQ9wLm4Rx8Tn6Vb1Yc3Ds5Gh0Jk2Mn4Po6Qr8St0Uv
Key What it does
pk_test_ Reads real data. Writes test bookings that never reserve stock, count in revenue or appear in a statement.
pk_live_ Reads and writes real data. Reservations take stock immediately.

Key rules

  • The secret is shown once when the key is issued and stored only as a hash. If it is lost, rotate the key. It cannot be recovered.
  • A key can be restricted to IPv4 or IPv6 addresses and CIDR blocks. A call from anywhere else returns 403 ip_not_allowed.
  • Rotation issues a replacement and revokes the old secret in one step. Deploy the new token immediately, or plan a short maintenance window.
  • Revocation is immediate. A suspended agency receives 403 agency_suspended on every call.
  • The mode in the token must match the key. A test token cannot be used with a live key, or the reverse.
  • Keep the key in a secret manager on your server. Never embed it in a browser, mobile app or public repository.

First calls

Run these three calls before writing any business logic. They prove reachability, credentials and commercial terms in that order.

1. Reachability

This call needs no key. It returns the server clock and proves that DNS, TLS and your outbound firewall are open.

curl https://palauexplorer.com/api/v1/ping

2. Who am I

This call needs a valid key but no scope. It returns your agency, the key mode, the scopes you hold and your rate limit.

curl https://palauexplorer.com/api/v1/me \
  -H "Authorization: Bearer $PALAU_API_KEY"
{
  "data": {
    "agency": { "id": 7, "name": "Blue Lagoon Travel" },
    "key": { "name": "Production integration", "mode": "live" },
    "scopes": ["catalog.read", "inventory.read", "bookings.read", "bookings.write"],
    "rate_limit": { "per_minute": 120 },
    "status": "active"
  }
}

3. Your commercial terms

This call returns the commission, cancellation schedule and payment terms agreed for your agency. Check them against your signed contract before you quote a customer.

curl https://palauexplorer.com/api/v1/terms \
  -H "Authorization: Bearer $PALAU_API_KEY"

Wiring checklist

  • GET /ping returns 200 with status ok.
  • GET /me returns the expected agency and key mode.
  • GET /me lists every scope you asked for.
  • GET /terms matches your signed commission and cancellation schedule.
  • A 401 means the key is missing, malformed, unknown, revoked or expired.
  • A 403 means the key is valid but the agency is suspended, a scope is missing, or your address is not allowlisted.

Scopes

A key holds a set of scopes. A call that needs a scope the key does not hold returns 403 insufficient_scope. Ask for the smallest set your integration needs.

Scope Allows
catalog.read Read the catalog Tours and off-road departures: descriptions, images and prices net of commission.
inventory.read Read live inventory Per-day availability for tours and per-slot seat availability for off-road departures.
bookings.read Read its own bookings The reservations this agency has made, and their status.
bookings.write Create and cancel bookings Create and cancel reservations on this agency's behalf.

Catalog and inventory are separate grants on purpose: a partner may buy the content without live stock, or the reverse. Writes are separate again, so a reconciliation job can read bookings without being able to create or cancel one.

This version has 15 routes under /v1. The full list is in the endpoint table below and in the OpenAPI contract.

Catalog

The catalog is read-only. It returns published products with your own net rates for a reference date. Pass locale=en, zh-Hans or ja; missing translations fall back to English.

Tours

  • GET /tours lists published, titled tours. Paginate with page and per_page; the maximum page size is 200.
  • GET /tours/{slug} opens one tour with its full description, itinerary, inclusions, exclusions, highlights, gallery and state permits.
  • Each card carries id, slug, title, copy, duration, capacity, weekdays, image and price. Use id as product.id when booking. Keep slug as your stable external reference.
  • State permits are bought locally and cannot be booked through the API. Quote them separately, or your price will be short by the fee.
curl "https://palauexplorer.com/api/v1/tours?locale=en&date=2026-11-20&per_page=50" \
  -H "Authorization: Bearer $PALAU_API_KEY"

Off-road and jet ski

Each product has one endpoint and two departures, morning and afternoon. The departure id in that response is the product.id a booking takes.

curl "https://palauexplorer.com/api/v1/off-road?date=2026-11-20" \
  -H "Authorization: Bearer $PALAU_API_KEY"

curl "https://palauexplorer.com/api/v1/jet-ski?date=2026-11-20" \
  -H "Authorization: Bearer $PALAU_API_KEY"

What a price means

  • public is what the public site charges.
  • net is what your agency pays after your commission.
  • rate is your commission percentage.
  • child_public and child_net appear only when the product has a child rate.

A catalog price is a quote for the reference date. Availability and price are checked again when you create the booking.

Availability

Availability is live. A seat can be taken between your read and your write, so always treat a booking as the authoritative answer.

Tours

GET /tours/{slug}/availability returns every day in the window, including closed days. Each day carries state, remaining and price.

  • state is bookable, full or closed.
  • remaining is the number of seats left. It is null when the product is uncapped.
  • price is null when the day is closed or carries no price. A full day still has a price.
  • The window defaults to 90 days from today and may span at most 366 days. A past from date is moved to today. A to before from is 422 validation_failed.
curl "https://palauexplorer.com/api/v1/tours/rock-islands-tour/availability?from=2026-11-20&to=2026-12-20" \
  -H "Authorization: Bearer $PALAU_API_KEY"

Off-road and jet ski

GET /off-road/availability and GET /jet-ski/availability return seats_remaining per departure and date. Only sellable dates appear, and zero means full.

The jet-ski response also carries a skis list for each date. Each ski has assignment, seats_remaining and guide. Pass the assignments you want in party.skis.

  • A customer ski sells two seats. Each rider is one person at the seat price.
  • The guide ski is the only ski that accepts party.pillion. Its rear saddle opens only when every other seat on the date is gone, so its seats_remaining stays zero until then.
  • A ski cannot be named twice in one booking, and the pillion must be the guide ski.
curl "https://palauexplorer.com/api/v1/jet-ski/availability?from=2026-11-20&to=2026-11-27" \
  -H "Authorization: Bearer $PALAU_API_KEY"

Create a booking

POST /bookings creates a reservation and takes stock immediately. It requires the bookings.write scope and an Idempotency-Key header.

Header Value
Authorization Bearer pk_live_...
Content-Type application/json
Idempotency-Key Your unique key for this logical booking, up to 191 characters. Generate one per booking, not per retry.

Tour payload

curl -X POST "https://palauexplorer.com/api/v1/bookings" \
  -H "Authorization: Bearer $PALAU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b0f0f7e-2f4a-4b31-9a8e-2d3c4b5a6f70" \
  -d '{
    "product": { "type": "tour", "id": 3 },
    "date": "2026-11-20",
    "party": { "adults": 2, "children": 1 },
    "guest": { "name": "Ana Reyes", "email": "ana@example.com", "phone": "+680 555 0100" },
    "partner_reference": "INV-2041",
    "hold_ttl_minutes": 60
  }'

Off-road and jet-ski payloads

An off-road booking names seats. A jet-ski booking names whole skis, each with a rider count.

{
  "product": { "type": "off_road", "id": 1 },
  "date": "2026-11-20",
  "party": { "seats": 2 },
  "guest": { "name": "Ana Reyes", "email": "ana@example.com" }
}

{
  "product": { "type": "jet_ski", "id": 1 },
  "date": "2026-11-20",
  "party": {
    "skis": [
      { "assignment": 13, "riders": 2 },
      { "assignment": 14, "riders": 1 }
    ],
    "pillion": 12
  },
  "guest": { "name": "Ana Reyes", "email": "ana@example.com" }
}

Fields

  • product.type is tour, off_road or jet_ski.
  • product.id is the tour id from /tours, or the departure id from /off-road or /jet-ski.
  • date is the travel date in YYYY-MM-DD.
  • end_date is optional and only meaningful for a multi-day tour.
  • party takes adults and children for a tour, seats for off-road, and skis for jet ski.
  • guest.email must be a valid address; it is where the traveller confirmation is sent.
  • partner_reference is echoed back and is the best place for your own booking number.
  • hold_ttl_minutes is optional, from 5 to 10080. Omit it for an open reservation.

Idempotency

A repeat with the same Idempotency-Key and the same body replays the first response instead of creating a second booking. The same key with a different body returns 409 idempotency_conflict. Keys are remembered for 24 hours.

This is what makes a timeout safe: send the same key and body again, and you will learn the original outcome rather than risk a duplicate.

Response

{
  "data": {
    "reference": "PE-01J4Z9K8YQ7V6N5M4P3R2S1T0H",
    "status": "unpaid",
    "test": false,
    "product": { "type": "tour", "id": 3, "name": "Rock Islands Kayak" },
    "date": "2026-11-20",
    "end_date": null,
    "party": { "adults": 2, "children": 1, "seats": null },
    "guest": { "name": "Ana Reyes", "email": "ana@example.com", "phone": "+680 555 0100" },
    "partner_reference": "INV-2041",
    "price": { "public": "300.00", "rate": "15.00", "commission": "45.00", "net": "255.00" },
    "invoice": { "number": "BLT-000042", "amount": "255.00", "status": "outstanding" },
    "hold_expires_at": "2026-11-20T12:00:00+00:00",
    "cancel_reason": null,
    "cancel_penalty": null,
    "created_at": "2026-11-20T11:00:00+00:00"
  }
}

A test-key booking returns test: true. Keep the reference: it is how you read, cancel and reconcile the booking later.

Manage bookings

A key only ever sees its own agency's bookings. Another agency's reference is a plain 404.

  • GET /bookings lists your reservations, newest first. Filter by status (unpaid, confirmed, cancelled), from and to travel dates, page and per_page.
  • GET /bookings/{reference} returns one booking.
  • POST /bookings/{reference}/cancel cancels it, releases its stock and records the penalty your cancellation schedule implies.
curl "https://palauexplorer.com/api/v1/bookings?status=unpaid&from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $PALAU_API_KEY"

curl -X POST "https://palauexplorer.com/api/v1/bookings/PE-01J4Z9K8YQ7V6N5M4P3R2S1T0H/cancel" \
  -H "Authorization: Bearer $PALAU_API_KEY"

Cancellation is naturally idempotent: cancelling an already-cancelled booking returns it unchanged, so a retry is safe. A booking that lapses because its hold expired carries cancel_reason hold_expired; one cancelled by you carries partner.

Reconciliation

GET /statement returns your invoices, payments and balance for a travel window. A booking belongs to the window its start date falls in, and a payment to the window of the booking it settles, whenever the money arrived.

  • The window defaults to the current month. A to earlier than from is 422 validation_failed.
  • An invoice is outstanding, paid or void. A cancelled booking voids its invoice.
  • The figures come from the same service the admin statement uses, so the two can never disagree.
curl "https://palauexplorer.com/api/v1/statement?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $PALAU_API_KEY"

There are no partner webhooks. Poll GET /bookings for status changes and GET /statement for money. A five to fifteen minute interval is usually enough; do not poll on every page view.

Endpoints, errors and rate limits

Every path below is relative to the base URL. The scope a call needs is shown. "Any valid key" means no scope is checked.

Method Path Scope
GET /bookings bookings.read
POST /bookings bookings.write
GET /bookings/{reference} bookings.read
POST /bookings/{reference}/cancel bookings.write
GET /jet-ski catalog.read
GET /jet-ski/availability inventory.read
GET /me Any valid key
GET /off-road catalog.read
GET /off-road/availability inventory.read
GET /ping None (public)
GET /statement bookings.read
GET /terms Any valid key
GET /tours catalog.read
GET /tours/{tour} catalog.read
GET /tours/{tour}/availability inventory.read

Error envelope

Every failure has the same shape, whatever produced it. Branch on code, never on message.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key may not do that.",
    "details": {}
  }
}
Status Code When
401invalid_credentialsMissing, malformed, unknown, revoked or expired key.
403agency_suspendedThe key is valid but its agency is suspended.
403insufficient_scopeThe key lacks the scope the route requires.
403ip_not_allowedThe caller is not in the address list of the key.
404not_foundThe resource does not exist, or belongs to another agency.
409unavailableThe selection exists but cannot be sold: past, closed, full or unpriced. Re-read availability and re-quote.
409idempotency_conflictThe Idempotency-Key was already used with a different body.
422validation_failedThe request did not validate; details carries the field errors.
429rate_limitedToo many requests. Wait for the Retry-After header.
500server_errorOur fault. Nothing internal is leaked. Retry with backoff.

Rate limits

  • An authenticated key may make 120 requests per minute.
  • An unauthenticated caller is limited to 30 requests per minute per address.
  • A 429 carries Retry-After in seconds. Back off exponentially and add jitter; do not retry in a tight loop.

Retry policy

  • Retry GET requests on 429 and 5xx with exponential backoff.
  • Retry POST /bookings only with the same Idempotency-Key and the same body.
  • Do not retry 401, 403, 404 or 422. Those need a configuration or payload fix.
  • On 409 unavailable, re-read availability and re-quote before deciding whether to try another date or departure.

Code recipes

These examples create the same tour booking shown above. Replace the base URL, key and ids with your own.

PHP

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::withToken(config('services.palau.key'))
    ->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
    ->post(config('services.palau.base_url').'/bookings', [
        'product' => ['type' => 'tour', 'id' => 3],
        'date' => '2026-11-20',
        'party' => ['adults' => 2, 'children' => 1],
        'guest' => [
            'name' => 'Ana Reyes',
            'email' => 'ana@example.com',
            'phone' => '+680 555 0100',
        ],
        'partner_reference' => 'INV-2041',
    ]);

if ($response->failed()) {
    $error = $response->json('error');
    // Branch on $error['code'], never on the message.
}

$booking = $response->json('data');

Node.js

const baseUrl = process.env.PALAU_API_BASE_URL;
const key = process.env.PALAU_API_KEY;

const response = await fetch(`${baseUrl}/bookings`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${key}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    product: { type: 'tour', id: 3 },
    date: '2026-11-20',
    party: { adults: 2, children: 1 },
    guest: {
      name: 'Ana Reyes',
      email: 'ana@example.com',
      phone: '+680 555 0100',
    },
    partner_reference: 'INV-2041',
  }),
});

const payload = await response.json();

if (!response.ok) {
  throw new Error(`Booking failed: ${payload.error.code}`);
}

const booking = payload.data;

Use a UUID or another unique value for the Idempotency-Key. Store it next to your own booking attempt so a timeout can be retried with the same value.

Go-live checklist

  • Your live key is issued and restricted to your production egress addresses.
  • The test key is not present in production configuration or logs.
  • The key is stored in a secret manager, never in code or a public repository.
  • Your HTTP client uses a connect timeout of about 10 seconds and a read timeout of about 30 seconds.
  • Every booking attempt has a persisted Idempotency-Key, including retries.
  • Your job polls /bookings and /statement on a schedule and alerts on 401, 403, 429 and 5xx.
  • You have run a test booking end to end: create, read, cancel and reconcile.
  • You know who rotates the key and how the new token reaches production.
  • You have completed one live booking with a real customer before announcing the integration.

FAQ

Can I book hotels through this API?

No. The partner API covers tours, off-road departures and jet-ski departures. Hotel stays are not part of v1.

Is there a separate sandbox URL?

No. Use the same base URL with a pk_test_ key. Test reads return real data; test writes create test bookings that never reserve stock or count in your statement.

Can I call the API from a browser or mobile app?

No. The key is a server secret. Call from your own backend, where the key can be stored and rotated safely.

Do you send webhooks?

No partner webhooks exist in v1. Poll /bookings for status changes and /statement for money.

Why is a booking I just created returning 404?

A booking is only visible to the agency that created it. Check that you are using the same key, and that the reference is complete.

Are catalog prices final?

They are quotes for the reference date. The booking re-checks availability and price, and returns the final net amount. State permits are extra and are not bookable.

Where do I find the id for a tour or a ski?

The tour id is the id field on each /tours card. Ski assignment ids are the assignment values in the skis list of /jet-ski/availability.

Can the rate limit be raised?

Talk to your partner manager. The limit is per key contract, not a global ceiling.

How is the API versioned?

Everything lives under /v1. Additive fields may appear within the version. A breaking change means a new version, never a change under this one.

Still stuck?

Send us the request id, the endpoint, the timestamp and the error code. Never send a full key.

Contact the partner team
Need help?

Need help?

Send us a message and we will reply by email.