The purpose of this documentation is to provide a guide on how to integrate with the Blue Rewards Issuance API. As part of this documentation, we also include information on RESTful HTTPS requests/responses, error codes, the reconciliation process, integration environments, and support contact information.
Target audience
This material is intended to be used by a Partner wishing to integrate with the Blue Rewards Issuance API.
What is real-time Issuance
The Blue Rewards “Real-Time Checkout” platform provides Partners with a streamlined method for instantly awarding their customers with Blue Rewards Points, online or in-store. “Real-Time Issuance” ensures your customers will be able to see their updated balances immediately following checkout.
Service level objective
Please contact our Partner support team for details on our Service Level Agreement (SLA). Refer to our “Escalation Guide” for contact details.
Did you know
Our “Transaction Day” for real-time Issuance runs from 12:00AM to 11:59PM EST daily.
Integration environments
There are two sets of environments used by partners to integrate with the real-time checkout platform. These environments are configured similarly for consistent production-level quality, whether the partner has deployed to production or is still performing non-production testing.
Contains production code and live user data for real-world 3rd party integrations.
Note
All integration environments must be accessed via HTTPS only.
Your BLUE project team
In preparation for launch, a Blue Rewards team is pulled together to assist Partners with integration and setup. This team will provide the following services:
Consulting Partners on the best technical solution to support Blue Rewards Issuance based on system compatibility.
Providing guidance for assessing Partner requirements, data exchange methods, and reconciliation.
As well as overseeing a broad range of activities to meet the requirements of launch, including:
Planning
Communications
Delivery
Execution
Monitoring
Commonly used acronyms
Name
Definition
BLUE
Blue Rewards: The loyalty program itself consisting both issuance and redemption processes.
BP
BLUE POINTS: The loyalty program currency that Members earn and redeem for travel, merchandise and cash rewards.
RTC
Real-Time Checkout: A Blue Rewards API platform specifically tailored for “Real-Time Issuance” & redemption of Blue Rewards “Blue Points”.
M2M
Machine-to-Machine: Refers to direct communication between devices using any communications channel, including wired and wireless. This includes CLIs, daemons, or services running on your back-end that self-authenticates and/or authorizes an application without collector interaction.
POS
Point-of-Sale: Refers to the software/hardware component that handles transactional messages, as well as processing Blue Rewards issuances and reversals (return transactions).
1 - Authentication & Authorization
The Blue Rewards security layer granting access to member APIs and associated services.
For more information on “Auth0” and the various authentication flows, click the button below.
2 - API Library
This section describes the Blue Rewards Issuance API endpoints. The endpoints are grouped into 2 categories; Blue Rewards Calculated and Partner Calculated. Each API page offers a brief summary of the API endpoint in question, common use-case scenarios, and sample request/response messages with response codes.
Includes the API endpoints POST, POST/EVENT, REVERSE, REVERSE/EVENT, and RECORD.
Idempotent requests
All the API calls (except RECORD) support idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to issue points to a Collector does not receive a response due to a network connection error, you can retry the request with the same idempotency key to guarantee that extra points aren’t accidentally deposited into the Collector’s account.
Note
To perform an idempotent request, you need to provide an additional Idempotency-Key: <key> header to the request.
What is an “Idempotency Key”
An “Idempotency Key” is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
WARNING
If you omit the header in the request, then the content of the transaction itself will be used to detect if it’s a duplicate. This requires that you send the exact same request as before, including an identical timestamp. This process however does not guarantee idempotency and should only be used as a last resort.
As described above, the RESTful specification defines a transaction as a pair of request and response messages that are used for information interchange.
Note
Mandatory parameters will be marked with an asterisk (*) in the subsequent pages.
Message Type
Description
Request
All mandatory parameters MUST be included in each API call.
All other parameters are optional, unless stated otherwise.
Response
Indicates which parameters/elements are always returned.
The “Response” Content-Type is specified in the Header (e.g., application/json.
A “Response” resulting in an ’error condition’ will include an accompanying responseCode.
Partners are expected to verify and handle each Response Code as necessary.
All response values are NOT not case-sensitive.
Data elements that contain null or ’empty’ values are automatically excluded from the response body.
The ‘POS’ terminal may use the response elements to display/print information for the customer.
The Response object should not be validated in strict mode to allow flexibility around optional attributes.
Response code descriptions
Status Code
Description
200
Request processed successfully.
202
Request succeeded, but still processing…
400
Request failed, bad request.
500
Request failed, internal error.
Error code descriptions
Error Code
Status Code
Display Message
Description
202
202
Location Code Not Provided
The request is missing a location code.
203
202
Offer Code Not Found
The Issuance offer code does not exist.
204
202
Offer Code Expired
The Issuance offer code has expired.
205
202
Location Code Inactive
The location code is not currently active.
207
202
Invalid Unit Miles
Miles do not match the allowable ‘Unit Mileage’.
208
202
Invalid Variable Miles
Miles exceed the allowable ‘Variable Mileage’.
221
400
Sponsor Code Not Found
The Sponsor code you entered does not exist.
224
400
Collector Account Closed
The requested Collector account has been closed.
225
202
Sponsor Code Expired
The requested Sponsor code has expired.
230
202
Location Code Not Found
The location code does not exist.
232
400
Collector Account Deleted
The requested Collector has been deleted from the system.
234
400
Collector Account Not Found
The requested Collector does not exist.
601
202
Points Not Allowed
Points are not allowed for issuance offers starting before the cut-over date in the system.
603
202
Miles Not Allowed
Miles are not allowed for issuance offers starting on or after the cut-over date in the system.
000
202
Unknown
The Issuance is pending due to unknown error.
2.1 - Blue Rewards Calculated Endpoints
Includes the API endpoints CALCULATE, ISSUE, RETURN, and RECORD.
The APIs in this section handle all the calculations and logging themselves, which makes things easier for most businesses looking to integrate with the Blue Rewards program. Using the “Blue Rewards Calculated” method means Blue Rewards handles all the logging and billing aspects of the service.
2.1.1 - CALCULATE
Used to calculate how many Points to issue for all eligible items in the basket.
The CALCULATE endpoint is used to calculate how many Points to issue for all eligible items in the basket. This API call DOES NOT issue actual Points to the Collector.
Important
You do not need to make a CALCULATE call prior to making an ISSUE call. The CALCULATE call is only required if you want to see how many Points would be issued for an item (or items), but don’t want to issue those Points.
API call validation process
After making a call to CALCULATE, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
The dollar amount of GST (Government Sales Tax) to be added.
Example: 16.12
basketHSTAmount
The dollar amount of HST (Harmonized Sales Tax) to be added.
Example: 16.12
basketPSTAmount
The dollar amount of PST (Provincial Sales Tax) to be added.
Example: 16.12
basketQSTAmount
The dollar amount of QST (Quebec Sales Tax) to be added.
Example: 16.12
basketPostTaxAmount*
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
Example: 16.12
basketPreTaxAmount*
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
Example: 16.12
checkoutDateTime*
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples:
"2019-05-30T14:12:59.479Z"
"1972-07-16T13:32:05.234+04:00"
checkoutTransactionId*
Unique identifier generated by the Partner for the transaction at checkout.
Example: "12340001111"
collectorNumber*
The customer’s Blue Rewards account number.
Example: "81111111111"
Must be 11 digits in length and must start with an 8
context
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
coupon
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
deviceId
ID number used to identify the POS terminal currently in use.
Example: "001"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax).
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: "ST90"
originalTransactionId
This value represents the transactionId returned in the ISSUE transaction response from Blue Rewards. Alternatively the checkoutTransactionId supplied by the Partner in an ISSUE transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "TEST"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
transactionType*
Transaction Type can be PURCHASE (ISSUE) or RETURN.
Basket item SKUs that contributed for the Issuance.
Example: "SKU123"
issuanceOfferCode
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: ST90
milesAmount
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
transactionId
A unique ID created for the particular transaction.
The ISSUE endpoint is used to both calculate how many Points will be issued for all eligible items in the basket, and deposit those Points to the Collector’s account.
Important
You do not need to make a CALCULATE call prior to making an ISSUE call. The CALCULATE call is only required if you want to see how many Points would be issued for an item (or items), but don’t want to issue those Points.
API call validation process
After making a call to ISSUE, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is SUCCESSFUL but issuances are pending and causing a delay
You will receive a response code of 202
No further action is required
Resubmitting the same request will have no effect on the transaction.
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
WARNING
While a transaction is being processed for a Collector, DO NOT attempt to process an additional transaction in parallel for the same Collector. This will result in an error.
The dollar amount of GST (Government Sales Tax) to be added.
Example: 16.12
basketHSTAmount
The dollar amount of HST (Harmonized Sales Tax) to be added.
Example: 16.12
basketPSTAmount
The dollar amount of PST (Provincial Sales Tax) to be added.
Example: 16.12
basketQSTAmount
The dollar amount of QST (Quebec Sales Tax) to be added.
Example: 16.12
basketPostTaxAmount*
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
Example: 16.12
basketPreTaxAmount*
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
Example: 16.12
checkoutDateTime*
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples:
"2019-05-30T14:12:59.479Z"
"1972-07-16T13:32:05.234+04:00"
checkoutTransactionId*
Unique identifier generated by the Partner for the transaction at checkout.
Example: "12340001111"
collectorNumber*
The customer’s Blue Rewards account number.
Example: "81111111111"
Must be 11 digits in length and must start with an 8
context
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
coupon
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
deviceId
ID number used to identify the POS terminal currently in use.
Example: "001"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
baseAmount*
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: "ST90"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "TEST"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: ST90
milesAmount
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
processedDateTime
The date/time (see ISO-8601) that Miles were issued to the Collector.
Example: "2019-05-30T14:12:59.479Z"
status
The status of the transaction. (Statuses include: PENDING, CONFIRMED, REJECTED)
Example: "CONFIRMED"
transactionId
A unique ID created for the particular transaction.
The RETURN endpoint is used to recalculate the Points earned for each item in the basket, then withdraws the Points for the item(s) being returned.
Important
You do not need to make a CALCULATE call prior to making an ISSUE call. The CALCULATE call is only required if you want to see how many Points would be issued for an item (or items), but don’t want to issue those Points.
API call validation process
After making a call to RETURN, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is SUCCESSFUL but issuances are pending and causing a delay
You will receive a response code of 202
No further action is required
Resubmitting the same request will have no effect on the transaction.
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
WARNING
While a transaction is being processed for a Collector, DO NOT attempt to process an additional transaction in parallel for the same Collector. This will result in an error.
The dollar amount of GST (Government Sales Tax) to be added.
Example: 16.12
basketHSTAmount
The dollar amount of HST (Harmonized Sales Tax) to be added.
Example: 16.12
basketPSTAmount
The dollar amount of PST (Provincial Sales Tax) to be added.
Example: 16.12
basketQSTAmount
The dollar amount of QST (Quebec Sales Tax) to be added.
Example: 16.12
basketPostTaxAmount*
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
Example: 16.12
basketPreTaxAmount*
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
Example: 16.12
checkoutDateTime*
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples:
"2019-05-30T14:12:59.479Z"
"1972-07-16T13:32:05.234+04:00"
checkoutTransactionId*
Unique identifier generated by the Partner for the transaction at checkout.
Example: "12340001111"
collectorNumber*
The customer’s Blue Rewards account number.
Example: "81111111111"
Must be 11 digits in length and must start with an 8
context
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
coupon
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
deviceId
ID number used to identify the POS terminal currently in use.
Example: "001"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
baseAmount*
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: "ST90"
originalTransactionId*
This value represents the transactionId returned in the ISSUE transaction response from Blue Rewards. Alternatively the checkoutTransactionId supplied by the Partner in an ISSUE transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
sponsorCode*
Alpha-numeric value used to identify the partner.
Example: "TEST"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: ST90
milesAmount
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
processedDateTime
The date/time (see ISO-8601) that points were issued to the Collector.
Example: "2019-05-30T14:12:59.479Z"
status
The status of the transaction. (Statuses include: PENDING, CONFIRMED, REJECTED)
Example: "CONFIRMED"
transactionId
A unique ID created for the particular transaction.
This API call DOES NOT issue Points to Collectors.
The RECORD endpoint is used to test and verify the transmission of transactions to Blue Rewards - this includes both Collector and non-Collector transactions. This endpoint can be used initially to test and verify that the API integration is working as expected.
API call validation process
After making a call to RECORD, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
The dollar amount of GST (Government Sales Tax) to be added.
Example: 16.12
basketHSTAmount
The dollar amount of HST (Harmonized Sales Tax) to be added.
Example: 16.12
basketPSTAmount
The dollar amount of PST (Provincial Sales Tax) to be added.
Example: 16.12
basketQSTAmount
The dollar amount of QST (Quebec Sales Tax) to be added.
Example: 16.12
basketPostTaxAmount*
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
Example: 16.12
basketPreTaxAmount*
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
Example: 16.12
checkoutDateTime*
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples:
"2019-05-30T14:12:59.479Z"
"1972-07-16T13:32:05.234+04:00"
checkoutTransactionId*
Unique identifier generated by the Partner for the transaction at checkout.
Example: "12340001111"
collectorNumber
The customer’s Blue Rewards account number.
Example: "81111111111"
Must be 11 digits in length and must start with an 8
context
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
coupon
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
deviceId
ID number used to identify the POS terminal currently in use.
Example: "001"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax).
Example:
[{"id": "SKU1234","name": "Dog Food"}]
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
baseAmount*
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
Example: "ST90"
originalTransactionId
This value represents the transactionId returned in the ISSUE transaction response from Blue Rewards. Alternatively the checkoutTransactionId supplied by the partner in an ISSUE transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "KELL"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
Includes the API endpoints POST, POST/EVENT, REVERSE, REVERSE/EVENT, and RECORD.
Important
The APIs listed here require the partner to calculate and process the transactions themselves. If you are a smaller business who either doesn’t have the infrastructure or doesn’t wish to send us a monthly detailed transaction log, you may be better suited for our Blue Rewards Calculated APIs.
The APIs in this section require the Partner to keep a detailed log of all their transactions, calculate Points to be issued for each transaction, which must be sent to Blue Rewards on a regular basis (i.e., daily, weekly, bi-weekly or monthly) to facilitate issuing these Points to Blue Rewards Collectors. This method is primarily used by businesses that wish to keep their own detailed record of every transaction and remit those records on their own schedule.
2.2.1 - POST
Used to issue Blue Rewards to a Collector’s account in real-time for a basket transaction at checkout.
The POST endpoint is used to issue Blue Rewards to a Collector’s account in real-time for a basket transaction at
checkout. With this method selected the total Blue Rewards to be issued for a transaction are calculated by the Partner.
API call validation process
After making a call to POST, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is SUCCESSFUL but issuances are pending and causing a delay
You will receive a response code of 202
No further action is required
Resubmitting the same request will have no effect on the transaction
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
Basket item SKUs that contributed for the Issuance.
Example: "SKU123"
issuanceOfferCode*
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: ST90
milesAmount*
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId*
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
baseAmount*
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: "ST90"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "KELL"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT","AMCASH"]
provider
The provider of these transactions to Blue Rewards. This can be the Partner Name or their data provider name.
Example: ["PARTNER_NAME"]
program
The program for which these transactions are being sent. If you are part of the core Blue Rewards Program, then this value is always “AIRMILES"
The POST/EVENT endpoint is used to issue Blue Rewards to a Collector’s account in real-time for a non-transactional
reason (e.g., issuing Blue Rewards for desired activity or issuing a manual correction to a Collector’s account). With this
method selected the total Blue Rewards to be issued for a transaction are calculated by the Partner.
API call validation process
After making a call to POST/EVENT, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is SUCCESSFUL but issuances are pending and causing a delay
You will receive a response code of 202
No further action is required
Resubmitting the same request will have no effect on the transaction
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: ST90
milesAmount*
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId*
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "KELL"
To be provided by Blue Rewards
transactionDateTime*
The date and time the request was sent.
Example: "2021-11-09T21:04:45.930Z"
provider
The provider of these transactions to Blue Rewards. This can be the Partner Name or their data provider name.
Example: ["PARTNER_NAME"]
program
The program for which these transactions are being sent. If you are part of the core Blue Rewards Program, then this value is always “AIRMILES"
Basket item SKUs that contributed for the Issuance.
Example: "SKU123"
issuanceOfferCode*
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: ST90
milesAmount*
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId*
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
baseAmount*
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: "ST90"
originalTransactionId
This value represents the transactionId returned in the POST transaction response from Blue Rewards. Alternatively the checkoutTransactionId supplied by the Partner in an POST transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "KELL"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT","AMCASH"]
provider
The provider of these transactions to Blue Rewards. This can be the Partner Name or their data provider name.
Example: ["PARTNER_NAME"]
program
The program for which these transactions are being sent. If you are part of the core Blue Rewards Program, then this value is always “AIRMILES"
The REVERSE/EVENT endpoint is used to reverse Blue Rewards from a Collector’s account in real-time for a
non-transactional reason (e.g., issuing a manual correction to a Collector’s account). With this method selected the
total Blue Rewards to be reversed are calculated by the Partner.
API call validation process
After making a call to REVERSE/EVENT, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is SUCCESSFUL but issuances are pending and causing a delay
You will receive a response code of 202
No further action is required
Resubmitting the same request will have no effect on the transaction
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: ST90
milesAmount*
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId*
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
originalClientTransactionId
This value represents the clientTransactionId returned in the POST/EVENT transaction response from Blue Rewards. Alternatively the checkoutTransactionId supplied by the Partner in an POST transaction can be sent in this field.
This API call DOES NOT issue Blue Rewards to Collectors.
The RECORD endpoint is used to test and verify the transmission of transactions to Blue Rewards - this includes both
Collector and non-Collector transactions. This endpoint can be used initially to test and verify that the API
integration is working as expected. Partners can use this endpoint to send Collector and non-Collector transactions that
did not qualify for the transaction to be sent on the POST, REVERSE, POST/EVENT or REVERSE/EVENT endpoints.
API call validation process
After making a call to RECORD, you will receive one of the following responses:
If the call is SUCCESSFUL
You will receive a response code of 200
No further action is required
If the call is REJECTED due to incorrect or invalid details
You will receive a response code of 400
You must retry the request with a valid transaction record and/or the corrected details
If the call FAILS due to an error or other issue
You will receive a response code of 500
It’s recommended you retry the request at least 2 additional times
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our Support Desk for assistance.
Basket item SKUs that contributed for the Issuance.
Example: "SKU123"
issuanceOfferCode*
The offer code that points are issued against. This is the offer code that is setup by the Partner and Blue Rewards for the sponsorCode in the transaction.
Example: "STANDARD"
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: ST90
milesAmount*
The number of miles to be issued to the Collector.
Example: 2
pointsAmount
The number of points to be issued to the Collector.
Example: 30
multiplier
The multiplier used to convert miles to points.
Example: 16
offerDescription
The description of the offer that the issuance is based on.
Example: "This is a sample description."
offerId*
The identifier for an offer in the Partner's system. This can be the same value as your issuanceOfferCode OR an internal marketing code shared with Blue Rewards.
Example: "11234"
items
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax).
Example:
[{"id": "SKU1234","name": "Dog Food"}]
id*
The basket item's SKU.
Example: "1234"
name*
The name of the item.
Example: "Dog food"
number*
The order in which items were added to the basket.
Example: 2
quantity*
The quantity of an item in the basket.
Example: 3
baseAmount*
The pre-tax dollar amount for a single quantity of an item in the basket.
Example: 9.99
finalAmount*
The pre-tax dollar amount for all identical items in the basket (i.e., baseAmount x quantity).
Example: 29.97
departmentId
This field is mapped to a department value you would use to issue bonus points at a department level
Example: 10001
categoryId
This field is mapped to a category value you would use to issue bonus points at a category level
Example: CAT2
locationCode
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location. While it is not mandatory to be sent on the issuance record, for partners with retail locations including e-commerce, this field should be populated.
Example: "ST90"
originalTransactionId
This value represents the transactionId returned in the RECORD transaction response from Blue Rewards. Alternatively the checkoutTransactionId supplied by the Partner in an POST transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
sponsorCode*
Alpha-numeric value used to identify the Partner.
Example: "KELL"
To be provided by Blue Rewards
tender
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT","AMCASH"]
transactionType*
Transaction Type can be PURCHASE or RETURN.
Example: "PURCHASE"
provider
The provider of these transactions to Blue Rewards. This can be the Partner Name or their data provider name.
Example: ["PARTNER_NAME"]
program
The program for which these transactions are being sent. If you are part of the core Blue Rewards Program, then this value is always “AIRMILES"