Skip to main content

Update Redemption Reservation

PUT 
/client/users/:correlation_id/reservations/:reservation_token

  • This API will update the existing reservation.

  • The number of points reserved in the update cannot be greater than the number in the original redemption reservation.

  • If the redeemer is not a member of a household: If the update decreases the reservation amount, then the difference in points is awarded back to the member's account. For instance, if the reserved amount for the original reservationToken was 25000 and the updated reservation is 20000, then 5000 points are added back into the member's available point balance.

  • If the redeemer is a member of a household: If the update decreases the reservation amount, then points are awarded back to each household member account in the same proportions by which they originally contributed points.

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

Body​

AttributeDescriptionFormatNotes
reservationAmountSpecifies the number of reward units to reserve for redemptionNumber
redemptionIdOptional

Specifies against which redemption identifier we are reserving the points		String
redeemerIdOptional

It's mandatory if redemptionId is provided. Specifies the owner of the redemptionId and catalogueItems(if provided)		String
catalogueItemsOptional

If provided, redemptionId and redeemerId should be present.
This represents the array of products/items which user wants to redeem.

catalogueItems[].#productCode: Corresponds to product which user want to redeem.

catalogueItems[].#quantity: Corresponds to quantity of the productCode. Needs to be positive value.		Product objects within the catalogueItems arrayFor example:

"catalogueItems": [
{
"productCode":"123xy"
}
{
"productCode": "456za",
"quantity":2
}
]

productCode is a string and quantity a number. If quantity is not included, it is assumed to be 1 for that productCode.
extendedExpiryOptionalBooleanExtends the expiration duration of the existing reservation.
offlineOptionalBooleanIf the reservation token does not exist, an offline attribute is passed as true, then a new reservation gets created.
isExcludedFromCapWhether the redemption is excluded from redemption caps (for example, the number of points that can be redeemed in a day).Boolean: Enum: true or false

Response​

AttributeDescriptionFormatNotes
reservationTokenToken provided to confirm reservation statusStringRequired for redemption requests
reservationDurationHow long the reservation will be in placeNumber
availablePointBalanceTotal number of points available for reservationNumber
pointBalanceTotal balance of points for this accountNumber
sessionIdUnique identifier for this sessionStringGUID format. Optional attribute
redemptionNameOptional

Name of redemption identifier against which points are reserved.
It is returned if it's item level redemption.		String
catalogueItemsDataOptional

Description of the items used for reservation of points. Returned only if request has item level redemption.

productCode: Product code sent in the request.

quantity: Quantity sent via request.

catalogueItemId: ID of the catalogueItem mapped to the product code.

catalogueItemName: Name of the catalogueItem mapped to the product code.

pointsAmount: pointsAmount which the catalogueItem corresponds to.

totalPointsAmount:
pointsAmount * quantity

messages : localized messages related to the catalogue item.		catalogueItemsData array containing product data objectsExample:

{
"catalogueItemId": "CATALOGUE_ITEM_ID_6199",
"catalogueItemName": "Item Name 6199",
"quantity": 5,
"productCode": "89947774-01",
"redemptionType": "TENDER",
"pointsAmount": 500,
"totalPointsAmount": 2500,
"messages": {
"en-CA": {
"promptText": "Prompt for BUYCO 1",
"receiptTextLong": "buyco 2",
"receiptTextShort": "buyco2"
}
}
}

The pointsAmount is multiplied by the quantity to derive the totalPointsAmount.
householdContains the household pointsBalance and availablePointsBalance.ObjectReturned when member belongs to household and member has REDEEM privilege
pointsBalanceOverall balance of pointsNumber
availablePointsBalancePoints available for redemptionNumber

Error Responses​

statusCodeerrorMessageerrorCodeDefinition
400 Bad RequestAccount is not eligible for redemption.INVALID_REQUESTError shown if account cannot redeem or if PHONE_NUMBER is used as x-identifier-type in headers of Start Session call (not allowed).
400 Bad RequestInvalid tier amount.INVALID_REQUESTThe tier amount referenced is not valid for that tier.
400 Bad RequestEither reservationAmount or catalogueItems is required.INVALID_REQUESTIf both, reservationAmount and catalogueItems are absent in request. Either of them should be present.
400 Bad RequestredemptionId and redeemerId, both are required .INVALID_REQUESTIf only one of redemptionId or redeemerId is provided. Both are allowed together or none of them should be present.
400 Bad Request"invalidCatalogueItems": [
{
"productCode": "89947774-03",
"quantity": -50
},
{
"productCode": "Invalid Product code",
"quantity": 50
}
]		INVALID_REQUESTIf productCode and quantity provided in catalogueItem is not valid.
400 Bad Request"Reservation Token is invalid.",INVALID_REQUESTReservation token does not exist and offline attribute is false.
400 Bad RequestTotal points for catalogue items should be less than or equal to the reservation amount.INVALID_REQUEST
400 Bad RequestNew reservation amount cannot be greater than existing reservation amount.INVALID_REQUEST
400 Bad RequestInvalid redemption identifier: INVALID_redemption_id.INVALID_REQUEST
400 Bad RequestInvalid RedeemerINVALID_REQUEST
400 Bad RequestAccount is not eligible for redemption.INVALID_REQUESTError shown if account cannot redeem or if PHONE_NUMBER is used as x-identifier-type in headers of Start Session call (not allowed).
400 Bad RequestReservation belongs to a different session.INVALID_REQUESTIf reservation is made using one x-identifier-type, then session is started again with a different x-identifier-type, this error is shown.
400 Bad RequestInvalid catalogue item(s).INVALID_REQUESTSpecific errors in data for catalogue items are returned in the response.
400 Bad RequestChannel should be a string value.INVALID_REQUESTWhen channel not a string we will get this error.

Request​

Responses​

200 - Expiry Extended According to extendedExpirationDuration in Config

Response Headers
    Date
    Example: Mon, 15 May 2023 07:03:47 GMT
    Content-Length
    Example: 190
    Connection
    Example: keep-alive
    x-amzn-RequestId
    Example: bf99c8cf-a30b-4bdb-809d-6ee750c60d6d
    Referrer-Policy
    Example: no-referrer
    X-XSS-Protection
    Example: 1;mode=block
    Access-Control-Allow-Origin
    Example: *
    MCK-APPID
    Example: ES-POS-V1
    MCK-MSGID
    Example: mck-969239ea-fc42-4960-85d4-aed9f563a31c
    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: May 15th 2023, 7:03:47
    x-amz-apigw-id
    Example: E87lDEFCIAMFfww=
    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-6461d953-59a55bc5634fdb09703daf59;Sampled=0;lineage=8112f1f4:0
Last updated on