Points Bank API
Enable your customers use their loyalty earnings to book travel
You choose whether your White Label Template site will connect to your loyalty program, for earning or redeeming loyalty currency (or both). Your loyalty program defines which of your customers’ purchases are eligible to earn loyalty currency (whatever form that takes in your program—points, dollars, or otherwise), including the ones on your template site. You can also allow them to redeem their accumulated earnings on your template site to book travel.
Your customers will have two options for redeeming their loyalty earnings—directly through your template site, or with an Expedia agent on the phone. With the Points Bank API, your customers will be able to:
- Redeem earned loyalty currency
- Roll back travel purchases (also called cancelling or voiding)
- Receive a full or partial refund to their loyalty total for any cancelled travel plans
- Get their loyalty account balance
See the Common data and responses page for additional information.
We can display your customer’s loyalty balance in the header of your template site. Because the API calls happen on page load, though, the displayed points will not update until the page is refreshed, so it may not reflect other loyalty usage.
The Points Bank API has endpoints that cover redemption, rollback, and refund of loyalty currency. It can also call an account balance endpoint. For accuracy, this API must be queried at the time of the transaction. Each of the endpoints are detailed in the tabs below, but they all—and the account balance endpoint—share the same header fields.
Header variables
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
partnerId | Unique identifier for your business, provided by Expedia | YOUR BRAND | String, max 20 characters | Yes |
Authorization | Access token received by Expedia from your authorization server, to be validated by your team | Standard JSON web token (JWT) | String, standard JWT length | No |
Authorization2 | JSON web token (JWT) sent by Expedia; signature and claims to be validated on your end | Standard JWT | String, standard JWT length | No |
Check out our sample request and response page for payload details.
Redemption
This one-step commit process allows your customers to redeem their loyalty rewards via the points bank, using POST /redeem.
Request
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
requestId | Unique identifier for the transaction request | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
membershipId | Your unique customer identifier, received via SSO | a6fgju7he1bf | String, max 40 characters | Yes |
loyaltyAccountNumber | The customer’s loyalty account number (also called programAccountNumber); this should only be populated if an identifier other than membershipId is required for loyalty operations | 234986576 | String, max 40 characters | No |
programId | Identifier for the loyalty program the customer is affiliated to or the tier name associated with the loyalty program | Silver Gold Platinum | String, max 20 characters | No |
sourceConfirmationId | Confirmation identifier on the Expedia side (also called orderId); it’s sent in redeem, refund, and void requests and should be sent back as part of the the response payload and as part of the daily points recon file | 9223371998507503799 | String, max 50 characters | Yes |
totalproductCost | Total cost of booking (up to 2 decimals); equal to cash equivalent of amount paid in points + amount paid in cash or card | 230.09 | String, max 10 characters | Yes |
PaymentDetails | Loyalty currency and cash or card payment details; see PaymentDetails table for nested fields | Yes |
Response
| Field | Description | Sample value |
|---|---|---|
status | Transaction status (values: Approved or Declined) | Declined |
requestId | Unique identifier for the transaction request (from request payload) | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | Date and time of the transaction, as recorded on partner system | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | Order identifier from Expedia side(also called orderId); sent in redeem, refund, and void requests and should be included in the response payload and daily points recon file | 9223371998507503799 |
redemptionDetails | Confirmation of redeemed loyalty award; see RedemptionDetails table for nested items | |
DeclineReason | Reason transaction was declined; see the common data DeclineReason table for nested items | |
reasonMessage | A custom message to accompany a decline response for better logging; see the common data DeclineReason table for nested items |
PaymentDetails
| Field | Description | Mandatory? |
|---|---|---|
redemptionDetails | Details of the loyalty redemption; see RedemptionDetails table for nested items | Yes |
amountPaidInCash | Amount customer paid for the booking in cash or on a card; see the common data Amount table for nested items | Yes |
RedemptionDetails
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | Total number of points, miles (or any other loyalty currency) paid for the booking; see the common data Amount table for nested fields | Yes | ||
redemptionConfirmationId | Identifier for the redemption operation; will be sent in the refund or void request from Expedia, and should be populated in daily points recon report as "Partner Confirmation Id" for redemption transaction | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 50 characters | Yes |
loyaltyRedemptionCode | Redemption code required by some implementations, usually populated in the request; it's a one-time-password or predefined redemption code for a product, if required | SKU | String, max 20 characters | No |
Rollbacks
To process rollbacks (that is, reversal of loyalty transactions, also called cancellations or voids) at the points bank, you’ll use the POST /rollback endpoint.
This API is triggered when a redemption operation is successful, but Expedia must reverse it for a reason such as supply failure (for example, while the customer is attempting to book, the hotel sells out). Because this is a rollback of a redemption, it will require reconciliation before the loyalty earnings are available again.
Note: Neither the redemption nor rollback transactions should feature in the daily points reconciliation report.
Request
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
requestId | Unique identifier for the transaction request | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
membershipId | Unique identifier for your customer from your loyalty program | a6fgju7he1bf | String, max 40 characters | Yes |
sourceConfirmationId | Order identifier from Expedia side (also called orderId); sent in redeem, refund, and void requests; should be included in the response payload and daily points recon file | 9223371998507503799 | String, max 50 characters | Yes |
CancellationDetails | Details about the rollback transaction; see the CancellationDetails table for nested items |
Response
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
status | Rollback transaction status indicating whether the cancellation was successful (values: Approved or Declined) | Approved | String | Yes |
requestId | Unique identifier for the transaction request (from request payload) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
transactionDateTime | Date and time of the transaction, as recorded on your system | 2023-04-20T12:01:23.203057Z | String, max 40 characters | Yes |
sourceConfirmationId | Order identifier from Expedia side (also called orderId); sent in redeem, refund, and void requests; should be included in the response payload and daily points recon file | 9223371998507503799 | String, max 50 characters | Yes |
CancellationDetails | Details about the rollback transaction (mandatory if status value is Approved); see CancellationDetails table for nested items | |||
Balance | Number of points, miles, or any other loyalty currency available in the customer’s account; see the common data Amount table for nested items | |||
DeclineReason | Reason transaction was declined; see the common data DeclineReason table for nested items | |||
reasonMessage | A custom message to accompany a decline response; see the common data DeclineReason table for nested items |
CancellationDetails
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
redemptionConfirmationId | Confirmation identifier for redemption; sent in redemption response; if rolled back, should not be populated in daily points report | a5783c58-c5ce-4ff9-b83c-58c5cedff991 | String, max 50 characters | Yes |
cancellationConfirmationId | Confirmation identifier for rollback operation (mandatory if status value is Approved); should not be populated in daily points report | a5783c58-c5ce-4ff9-b83c-58c5cedff993 | String, max 50 characters | No |
Refunds
This API is used to process loyalty refunds to your points bank with POST /refund. It’s triggered when the customer needs to cancel their plans after they’ve already used their loyalty earnings to book. Because it’s a refund to their loyalty earnings, it will require reconciliation before the refunded currency is available in the customer’s account.
Request
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
requestId | Unique identifier for the refund request | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
membershipId | Unique customer identifier | a6fgju7he1bf | String, max 40 characters | Yes |
sourceConfirmationId | Order identifier from Expedia side (also called orderId); sent in redeem, refund, and void requests; should be included in the response payload and daily points recon file | 9223371998507503799 | String, max 50 characters | Yes |
RefundDetails | Details on the refund transaction; see RefundDetails table for nested items |
Response
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
status | Refund status (values: Approved or Declined) | Approved | String | Yes |
requestId | Unique identifier for the refund request (from request payload) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
transactionDateTime | Date and time of the transaction, as recorded on your system | 2023-04-20T12:01:23.203057Z | String, max 40 characters | Yes |
sourceConfirmationId | Order identifier from Expedia side (also called orderId); sent in redeem, refund, and void requests; should be included in the response payload and daily points recon file | 9223371998507503799 | String, max 50 characters | Yes |
RefundDetails | Details of the refund request; see RefundDetails table for nested items | |||
Balance | Number of points, miles, or any other loyalty currency available in the customer’s account; see the common data Amount table for nested items | |||
DeclineReason | Reason transaction was declined; see the common data DeclineReason table for nested items | |||
reasonMessage | A custom message to accompany a decline response; see the common data DeclineReason table |
RefundDetails
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
loyaltyRefundAmount | Total number of points, miles, or any other loyalty currency refunded; see common data Amount table for nested items | |||
redemptionConfirmationId | Identifier for the redemption operation; sent in the redemption response | a5783c58-c5ce-4ff9-b83c-58c5cedff918 | String, max 50 characters | Yes |
refundConfirmationId | Identifier for the refund operation; will be sent in refund or void request from Expedia, and should be populated in daily points recon file as "Partner Confirmation Id" for refund transaction | a324554f03-c5ce-4ff9-b83c-58c5cedff988 | String, max 50 characters | No |
Account balance
To fetch the customer’s loyalty account balance, you’ll use the POST /balance endpoint.
Request
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
requestId | Unique identifier for the transaction request | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
membershipId | Unique identifier for your customer from your loyalty program | a6fgju7he1bf | String, max 40 characters | Yes |
loyaltyAccountNumber | The customer’s loyalty account number (also called programAccountNumber); this should only be populated if an identifier other than membershipId is required for loyalty operations | 234986576 | String, max 40 characters | No |
programId | Identifier for the loyalty program the customer is affiliated with or the tier name associated with the loyalty program | Platinum | String, max 20 characters | No |
Response (successful)
| Field | Description | Sample value | Field type and length | Mandatory? |
|---|---|---|---|---|
requestId | Unique identifier for the transaction request | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, max 40 characters | Yes |
Balance | Number of points, miles, or any other loyalty currency available in the customer’s account; see the common data Amount table for nested items |