RETURN

Used to recalculate the Miles earned for each item in the basket, then withdraws the Miles for the returned items.

POST /checkout/issuance/return

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

The RETURN endpoint is used to recalculate the Miles earned for each item in the basket, then withdraws the Miles 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 Miles would be issued for an item (or items), but don’t want to issue those Miles.

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.

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/return \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
        {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"DEPT2",
            "categoryId" : "CAT2"
        }
    ],
    "locationCode": "1137",
    "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
    "sponsorCode": "TEST",
    "tender": ["CASH", "CREDIT"]
}

Request parameters

* required field

Parameter	Description
`basketGSTAmount`	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 AIR MILES 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 miles at a department level Example: `10001` categoryId This field is mapped to a category value you would use to issue bonus miles 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 AIR MILES. 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 AIR MILES
`tender`	The method of payment used to pay for the transaction at checkout. Example: `["CASH","CREDIT"]`

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber":"81111111111",
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "confirmationNumber": "0ed100a4-fc9a-41bb-a747-942c2593b683",
      "contributingItemIds": ["SKU1234","SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454",
      "processedDateTime": "2019-05-30T14:12:59.479Z",
      "status": "CONFIRMED"
    }],
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
              {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"DEPT2",
            "categoryId" : "CAT2"
        }],
  "locationCode": "1137",
  "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
  "sponsorCode": "TEST",
  "tender": ["CASH","CREDIT"],
  "context": {"key1": "value1","key2": "value2"},
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Parameter Description

Parameter	Description
`issuances`	Array value describing the issuance offers redeemed by the Collector. Example: `[{"confirmationNumber: 0ed100a4-fc9a-41bb-a747-942c2593b683", status: "confirmed"}]` confirmationNumber The UUID generated after processing an issuance request. Example: `"0ed100a4-fc9a-41bb-a747-942c2593b683"` contributingItemIds Basket item SKUs that contributed for the Issuance. Example: `"SKU123"` errors Errors that occur during an issuance transaction. Example - `errorCode`): `"CollectorNotFound"` Example - `errorReason`): `"The requested collector does not exist."` Click here to view the "Error Codes" table issuanceOfferCode The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES 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` 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 AIR MILES. 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. Example: `"c4f6cd00-dd00-4aaf-9099-b0685ab710b3"` To be provided by AIR MILES

issuances

Array value describing the issuance offers redeemed by the Collector.

Example:

[{"confirmationNumber: 0ed100a4-fc9a-41bb-a747-942c2593b683", status: "confirmed"}]

confirmationNumber: The UUID generated after processing an issuance request.; Example: "0ed100a4-fc9a-41bb-a747-942c2593b683"
contributingItemIds: Basket item SKUs that contributed for the Issuance.; Example: "SKU123"
errors: Errors that occur during an issuance transaction.; Example - errorCode): "CollectorNotFound"; Example - errorReason): "The requested collector does not exist."; Click here to view the "Error Codes" table
issuanceOfferCode: The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES 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
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 AIR MILES.; 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.

Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"

To be provided by AIR MILES

Status codes

Refer to our Audit report errors table for more information.

Status Code	Description
200	Request processed successfully.
202	Request still processing, please wait.
400	Bad request, failed to process.
500	Request failed due to internal error.