Reserve for Redemption

POST 
/client/users/:correlation_id/reservations/

Intended to reserve rewards for a redemption transaction. Note that if reserved rewards are not used for a redemption, usually within a specific amount of time, the reservation is expired and the points are returned to the available balance in the member's account.

Redemptions cannot be reserved or made using PHONE_NUMBER as the X-Identifier-Type on Start Session, so if it is used, an error message is returned.

Request

Body

Attribute	Definition	Format	Notes
businessUnit	The business unit for the transaction, if applicable.	String	Name of business unit
redeemerId	The unique identifier for the redeemer.	String
redemptionId	The unique identifier for this redemption.	String
reservationAmount	The amount of points to be reserved for the redemption.	String	If this is not provided, the points will be deduced from the sum of each (catalog item point value x quantity)
contributions	If the reserve is for a household where contributions for each member may be define, then this object is used to define each member's contribution	Object	Contains account number and point value key:value pairs for each member contributing to the redemption
catalogueItems	Contains data about the items included in the redemption.	Array containing object(s)	Contains the id and quantity of each item included in the redemption, each in a separate object
id	Unique name for the item.	String
quantity	Number of units of the item.	Number
fulfillmentEmailKey	fulfillmentEmailKey is the refrence to the fulfillmentEmailIDs present in account's EmailAddressBook	String	Required if redemptionId is "STATEMENT_CREDIT" or "DIRECT_DEPOSIT" to reflect fulfillment method; if redemptionId is not one of these values, then a warning is generated; if redemptionId is one of these values, then fulfillmentEmailKey must be provided

Response

Attribute	Definition	Format	Notes
reservationToken	Token associated with the redemption reservation.	String
reservationDuration	The time in days during which the reservation is in effect.	Number
availablePointBalance	The balance of points available for redemption.	Number
pointBalance	The balance of points.	Number
sessionId	Unique identifier for this session	String
catalogueItemsData	Contains data for each catalogue item	Array with an object inside for each catalogue item
catalogueItemId	Unique identifier for the catalogue item, corresponds to id in request	String
catalogueItemName	Name of the catalogue item	String
quantity	Quantity of the item in this redemption, corresponds to quantity in request	Number
pointsAmount	Points amount for this item	Number
totalPointsAmount	pointsAmount x quantity	Number
messages	Contains the localization and prompt and receipt messages	Object
localization object	Sets the localization parameters	Enum: "en-CA", "fr-CA", or "en-US"	Contains prompt and receipt messages
promptText	Text shown in the app	String
receiptLongText	Long text shown on the receipt	String
receiptShortText	Short text shown on the receipt	String
household	The availablePointsBalance and pointsBalance of household	Object	Returns when member belongs to household and member has REDEEM privilege
availablePointsBalance	Total points available for redemption	Number	May be less than points balance depending on redemption increments (for instance, every 25000 points = $10 redeemable)
pointsBalance	Total points balance	Number

Error Responses

statusCode	errorMessage	errorCode	Definition
400 Bad Request	Contribution amount is expected to be a positive integer value.	INVALID_REQUEST	Household member contribution must be positive value.
400 Bad Request	Contributor account(s) are not part of the household: {{accountID_1, accountID_x}}	INVALID_REQUEST	All contributors to redemption must be members of this household.
400 Bad Request	Member is not part of any household.	INVALID_REQUEST	Members who are not part of a household cannot contribute.
400 Bad Request	Secondary members are not allowed to make contributions.	INVALID_REQUEST	In some circumstances, Secondary members in the household cannot contribute to a redemption by the Primary member.
400 Bad Request	Catalogue points amount is not equal to the sum of contributions.	INVALID_REQUEST	Total catalogue points are not equal to total contributions.
400 Bad Request	Reservation amount is not equal to the sum of contributions.	INVALID_REQUEST	Number of points reserved is not the same as the sum of all contributions.
400 Bad Request	Adhoc Redemption feature is not enabled.	INVALID_REQUEST	The redemption reservation cannot proceed because the feature has not been enabled.
400 Bad Request	Account is not eligible for redemption.	INVALID_REQUEST	The x-identifier-type PHONE_NUMBER cannot be used for reservations or redemptions.
400 Bad Request	Account is not eligible for redemption.	INVALID_REQUEST	The x-identifier-type EMAIL cannot be used for reservations or redemptions.
400 Bad Request	Business unit {{businessUnit}} is not a valid business unit	INVALID_BUSINESS_UNIT	The businessUnit provided in the request does not have a valid value
400 Bad Request	Invalid redeemer: {{redeemerId}}.	INVALID_REQUEST	The redeemerId provided in the request does not have a valid value
400 Bad Request	Redemption identifier is invalid	INVALID_REQUEST	The redemptionId provided in the request does not have a valid value
400 Bad Request	Catalogue item: {{catalogueItem}} is invalid	INVALID_REQUEST	The catalogueItem provided in the request does not have a valid value
400 Bad Request	ReservationAmount or catalogueItems must be provided.	INVALID_REQUEST	reservationAmount or catalogItems have not been included in the request
400 Bad Request	Invalid tier amount.	INVALID_REQUEST	Not consistent with the values set in the configuration file for redemption daily minimum, maximum, and increments.
400 Bad Request	Based on the user and account status, user is not eligible for redemption.	INVALID_REQUEST	If status is suspended, lost or stolen, damaged, fraud or abuse, or cancelled, no redemption can proceed.
400 Bad Request	Reservation allowance exceeded	INVALID_REQUEST	The amount of points indicated for reservation exceeds the limits on how many points may be reserved.
400 Bad Request	Insufficient Funds.	INVALID_REQUEST	There are not enough funds available to cover the redemption reservation.
400 Bad Request	businessUnit is mandatory and required to be non-empty.	INVALID_REQUEST	businessUnit must be included in the request and must contain a value.
400 Bad Request	redeemerId is mandatory and required to be non-empty.	INVALID_REQUEST	redeemerId must be included in the request and must contain a value.
400 Bad Request	redemptionId is mandatory and required to be non-empty.	INVALID_REQUEST	redemptionId must be included in the request and must contain a value.
400 Bad Request	ReservationAmount or catalogueItems must be provided.	INVALID_REQUEST	The request must include reservationAmount or catalogueItems.
400 Bad Request	Redeemer is not associated with a Business Unit: [Business Unit].	INVALID_REQUEST	The redeemerId in the request must be associated with the businessUnit in the request.
400 Bad Request	Insufficient funds	INVALID_REQUEST	There are not enough funds available to cover the redemption reservation for this household.
400 Bad Request	Configured redemption logic is not supported	INVALID_REQUEST	This should check only when member belongs to household and household template has invalid redemption logic configured.
400 Bad Request	Unable to reserve points for {accountID}. Please contact Customer Service to get more information	FAILED_REDEMPTION	Not able to redeem due to outstanding fraud prevention advice on account.
400 Bad Request	Fulfillment email key is required.	INVALID_REQUEST	A value is required for the fulfillmentEmailKey field.
400 Bad Request	Fulfillment email key not found in the Email address book of the account.	INVALID_REQUEST	The fullfillmentEmailKey email address does not match any of the approved email addresses.

Request

Responses

200

200 - Reserved for Redemption

400

400 - Contribution Amount to Be a Positive Numeric Value

Response Headers

Date
Example: Fri, 11 Oct 2024 07:55:38 GMT
Content-Length
Example: 129
Connection
Example: keep-alive
x-amzn-RequestId
Example: 8604e748-6d4e-474a-bf0e-074b2efb8364
Referrer-Policy
Example: no-referrer
X-XSS-Protection
Example: 1;mode=block
Access-Control-Allow-Origin
Example: *
MCK-APPID
Example: ES-CB-V1
MCK-MSGID
Example: mck-bcdcfdec-1c1a-45d1-88ab-697cd9ff8464
Expect-CT
Example: max-age=86400
Strict-Transport-Security
Example: max-age=31536000; includeSubDomains; preload
Feature-Policy
Example: vibrate 'none'; geolocation 'none'
X-Frame-Options
Example: sameorigin
Content-Security-Policy
Example: connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.net
MCK-MSGTIMESTAMP
Example: October 11th 2024, 7:55:38
x-amz-apigw-id
Example: feb_KHEHoAMEutQ=
cache-control
Example: no-cache, no-store, must-revalidate
MCK_CORRELATIONID
Example: CORRELATION_ID_NOT_PROVIDED_IN_REQUEST
X-Content-Type-Options
Example: nosniff
X-Amzn-Trace-Id
Example: Root=1-6708d9fa-014370977a6919982aaba7fd;Parent=2f845dadb4c4ad37;Sampled=0;Lineage=1:8112f1f4:0