Skip to content

Quickstart

This guide takes you from nothing to a working integration in about 30 minutes. By the end you will have:

  • live prices for hotels in a city, from the Partner API,
  • a booking link that credits bookings to your account,
  • a test booking, and a webhook telling you it happened.

Everything happens in staging, our testing environment. You don’t need to ask us for access, and moving to production later needs no approval either.

You want to…Start here
Show hotels in your app, site or AI product and send travelers to book, earning commissionThis guide
Book on behalf of your clients as a licensed travel agencyThis guide up to Step 5, then Booking as a travel agency
Embed bookable hotels without writing an integrationWeb Components
Let an AI agent search and bookMCP Servers and Agentic Payments
Connect a channel manager or PMSAdd Your Channel Manager

You use the Partner API to find hotels and their live prices. Each hotel comes with a stable urlName. You turn it into a link to the Wink Booking Engine, book.wink.travel, carrying your IDs. The traveler books and pays there, and the booking is credited to your account.

You’ll need:

  • grpcurl, or Postman or Insomnia. The Partner API is gRPC, not REST.
  • curl.

Staging is completely separate from production, with its own logins and accounts.

  1. Go to staging-app.wink.travel, click Sign-In / Register and register.

  2. Click Accounts in the left sidebar, then Create, and choose I am an Affiliate. Bookings you send are credited to this account. See Create Account.

The application gives your code its credentials.

  1. On your account card, click Actions > Manage account, then the Applications tab.

  2. Click Create new application, give it a name and choose Machine-to-machine as the client type.

  3. Under scopes, select Inventory & rates (read). The Partner API checks for inventory.read.

  4. Click Create application and copy the Client ID and Client secret. The secret is shown once and can’t be retrieved later.

See Applications for the other client types and scopes.

Terminal window
curl -X POST https://staging-iam.wink.travel/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "client_secret=<YOUR_CLIENT_SECRET>" \
-d "scope=inventory.read"

Save the access_token from the response:

Terminal window
export WINK_TOKEN=<access_token>

Tokens expire. In your own code, let an OAuth2 library fetch and refresh them. See Authentication.

If the token request is rejected, the response is a JSON body with an error code:

errorHTTP statusUsual cause
invalid_client401Wrong client ID or secret, or production credentials used on staging-iam
invalid_scope400The request asks for a scope the application isn’t registered for
unauthorized_client400The application isn’t allowed to use the client_credentials grant
invalid_request400A required parameter is missing, for example when the body is JSON instead of a form

Every Partner API call names the account you are acting for in a managing-entity-id header. List the accounts your token can act for:

Terminal window
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-d '{}' \
staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccounts

Copy the accountId of the affiliate account from Step 1:

Terminal window
export WINK_ACCOUNT_ID=<accountId>

Staging has test hotels with availability in Bangkok, so this search uses its slug, bangkok-thailand:

Terminal window
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-H "managing-entity-id: $WINK_ACCOUNT_ID" \
-d '{
"urlName": "bangkok-thailand",
"userSession": {
"itinerary": {
"startDate": "2026-12-01",
"nights": 2,
"room": { "adults": 2 }
},
"currencyCode": "USD",
"languageCode": "en"
}
}' \
staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCity

Use a check-in date in the future; a past date is rejected. Each result carries:

  • name, starRating and heroImageUrl, enough to show a result row,
  • roomTypes, the live offers, cheapest room first,
  • urlName, the slug you need for the booking link.

Prices are integers in minor units: divide by 10 to the power of currencyExponent from the response (2 for USD, so 12500 is $125.00).

Don’t know a city’s slug? Resolve it with wink.partner.v1.Lookup/Search. For a property’s full content, use the Content service. The Partner API reference documents every call.

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>
  • <urlName> is the hotel’s urlName from Step 5.
  • client-id is your application’s Client ID from Step 2.
  • configuration-id is your customization ID: Manage account > Customizations. A customization also sets your branding, default language and currency on the booking page.

Add the traveler’s dates, guests, language and currency to the same link so the hotel page opens with them filled in:

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD
ParameterMeaningExample
sdCheck-in datesd=2027-03-14
n or edNumber of nights, or check-out daten=2 or ed=2027-03-16
rcGuests per roomrc=a2 (2 adults)
lDisplay languagel=en
cDisplay currencyc=USD
pPromotion codep=ABC123

These parameters override the defaults set in your customization. The Book Now button guide covers the full rc format, including children and several rooms.

The link opens the hotel page; it can’t pre-select a room or a rate. The traveler picks the room on the hotel page, at the live price.

See Linking directly for linking to the booking engine home page instead of a single hotel.

Open your link, pick dates and a room, and check out with a Stripe test card, for example 4242 4242 4242 4242 with any future expiry date and any CVC. No real card is charged in staging. Note the booking code on the confirmation page; it starts with WNK.

  1. In Portal, go to Applications > Webhooks and add an endpoint that accepts POST requests.

  2. Subscribe to booking.create, or leave the event list empty to receive everything while you develop.

  3. Send yourself a test event, then make another test booking and watch it arrive.

Verify every delivery’s signature before trusting it. See Webhook Integration and the Webhook Events Catalog.

There is no approval step for developers. (Travel agency accounts are certified first; see below.) When your integration works in staging:

  1. Create an account and an application at app.wink.travel, as in Steps 1 and 2. Credentials don’t carry over between environments.

  2. Drop staging- from every host:

    StagingProduction
    https://staging-iam.wink.travelhttps://iam.wink.travel
    staging-partner.wink.travel:443partner.wink.travel:443
    https://staging-book.wink.travelhttps://book.wink.travel
  3. Look up your production account ID (Step 4) and customization ID (Step 6) again. They differ from staging.

Partner API usage is metered in hotel-nights, with a free monthly allowance. See Partner API for pricing and limits.

If your account is a licensed travel agency, you don’t need to send travelers to book.wink.travel: you can create bookings directly with wink.partner.v1.Booking/CreateBooking, and manage them with the other Booking calls. Other accounts send travelers to the booking link instead.

Travel agency accounts are certified: Wink reviews every agency’s registration before it can book. Agencies that want to collect payment from their clients themselves, as merchant of record, must book through the Partner API and get Wink’s written approval. See Getting Started as a Travel Agency and the Partner API reference.