Skip to main content

Adjust Points in a Basket (with Receipt)

POST 
/client/users/:correlation_id/sessions/:originalTransactionId/adjustments

  • This API call deducts the loyalty points based on the items returned in the cart inside reversalLineItems.

  • The correlationId for the original transaction is passed in the request path.

  • There may be restrictions on how old the transaction can be with adjustments still allowed. If so, adjustments cannot be made outside the adjustment period.

Notes:

  • For a single member, or In a household, if a redemption transaction begins, but one or more of the cards are subsequently set to a non-active state such as Suspended, Lost or Stolen, Fraud/Abuse, Cancelled, or Damaged and there is a subsequent adjustment (full, partial, or void), then to prevent fraud, the adjustment amount is still applied to single members or proportionally to all household members who had active cards before the redemption transaction began.

  • If a single member or household member is in a tier program, and points/status are set to roll over from one period to the next, then any adjustments that reduce or increase member point balances can affect the current tier. If the adjustment is to a previous period, then it can affect the rolled-over tier status as well. In a household, adjustments to this or previous periods may affect the tier status of all members of the household.

Legacy Endpoint​

Note that the endpoint for this call has changed, but ESI still supports the old (legacy) endpoint:

{{pos_url}}/client/sessions/{{originalTransactionID}}/adjustments

Request​

The correlation_id for the original transaction is passed in the request path. The cart details in ES Console will reflect the result of the adjustment in the currency used.

For more information about requests, view the documentation for the Send Finalize Transaction request.

Note that sending the call without the proper "currentCorrelationId" will result in a 400 error.

Path Variables​

  • correlation_id

Body​

AttributeDefinitionFormatNotes
currentCorrelationIdCorrelates the session with the external system that is making the call.NumberRecommend using GUID mapped to the value of your Session ID or something directly referenced in your system as long as it is always globally unique. The Correlation ID also becomes the Transaction ID used to log any session transactions.
externalTransactionIDUnique identifier for transaction used by the client.StringOptional.
localeThe locale of the member from the POS system.StringOptional. Currently "en-CA" or "fr-CA". If locale is set by the POS system in the Start Session request, this overrides locale set in the member provide and as the system default.
actionThe action to be carried out for the adjustment.Enum: "adjustment"The action will always be adjustment for this type of request
channelThe channel through which the transaction was executed.Enum: "STORE", "POS", "WEBSITE", "APP", or "PARTNER"
transactionDateDate and time of transaction.StringDate of the Transaction (Full Date and Time) must be in an ISO-8601-compliant format, for example: 2022-01-17T13:48:59-04:00.
retailBannerName of company.StringFor instance, "BUYCO".
storeNumberThe store number of the store with which the transaction is associated.NumberRequired and must be non-empty.
tillNumberThe till number within the store with which the transaction is associated.NumberThis attribute is optional.
employeeCodeThe employee number of the till operator.NumberThis attribute is optional for operations, but required for analytics.
priceMatrixRetail or employee transaction.Enum: "R" or "E"R = Retail
E = Employee
reversalLineItemsDetails from each transaction item to be reversed.ArrayObject in array, can contain sku, quantity, and salesAmount
skuThe product identifier.NumberFor instance, may be scanned at Point of Sale.
quantityMeasure of the product amount sold.NumberCan be partial value for unit of measure calculations where there is no directly-applicable SKU (for instance, rope sold by the foot).
salesAmountMSRP less the discount, the actual sale price.NumberMRSP minus item discount in pennies.

Response​

AttributeDefinitionFormatNotes
loyaltyIdUnique member identifier for the transaction specified in the Request.Number
receiptMessageMessage to member.StringMay be a reminder to activate offers in future.
pointsAdjustmentShows the amount of points involved in the adjustment.NumberShows negative number if the adjustment removes points.
pointsBalanceNew points balance after adjustment.Number

Error Responses​

statusCodeerrorMessageerrorCodeDefinition
400 Bad RequestTransaction is not adjustableINVALID_REQUESTWhen latest transaction is 'ADJ_NO_RECEIPT'
400 Bad RequestTransaction is older than 30 daysINVALID_REQUESTTransaction cannot be adjusted because it is more than 30 days old
400 Bad RequestAdjustment transaction is lockedINVALID_REQUESTAdjustment cannot be made to a locked transaction
400 Bad RequestAdjustment is not unique (same adjustment is locked until it finishes)INVALID_REQUESTThis adjustment is already underway and locked
400 Bad RequestAdjustment Request of type EXCHANGE not supportedINVALID_REQUESTWhen ‘action’ (body) is ‘EXCHANGE’ and exchange is disabled. See configuration ConfigType = ‘ADJUSTMENT_FEATURE’, attribute ‘Exchange’.’Enable’.
400 Bad RequestSession account does not matchINVALID_REQUESTWhen original transaction's account is different from the current session account
400 Bad RequestSession does not exist.INVALID_REQUESTSession reference for the adjustment does not exist
400 Bad RequestCannot refund items that are not in the original cartINVALID_REQUESTItems that were not in the cart for the original transaction cannot be refunded
400 Bad RequestLoyaltyID is not associated with the Original LoyaltyIDINVALID_REQUESTWhen original transaction's loyalty ID is different from the current session's loyalty ID
400 Bad RequestNo Reversal Items Specified for AdjustmentINVALID_REQUESTWhen 'reversalLineItems' is not provided in the request's body. It can be empty only for VOID transactions.
400 Bad RequestTransaction does not existINVALID_REQUESTThe transaction referenced in the request does not exist
400 Bad RequeststoreNumber is mandatory and required to be non-empty.MISSING_REQUIRED_FIELDS_ERRORRequire storeNumber field including a value
400 Bad RequestTransaction is older than 30 days.INVALID_REQUESTAdjustment cannot be made outside the adjustment period
409 ConflictToo many simultaneous requests for the same account.CONFLICT_REQUESTFIFO sweep process for an account has been blocked because lock has been acquired for processing Adjustment. The event should be sent to the retry module, to be retried with exponential backoff.

Request​

Responses​

200 - Points Adjusted

Response Headers
    Date
    Example: Thu, 21 May 2020 03:42:00 GMT
    Content-Length
    Example: 186
    Connection
    Example: keep-alive
    x-amzn-RequestId
    Example: 973d2962-e98a-489d-a8dd-aa8207c21302
    Referrer-Policy
    Example: no-referrer
    X-XSS-Protection
    Example: 1;mode=block
    Access-Control-Allow-Origin
    Example: *
    Expect-CT
    Example: max-age=86400
    Strict-Transport-Security
    Example: max-age=31536000
    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
    x-amz-apigw-id
    Example: M3PFJEVroAMFs6g=
    cache-control
    Example: no-cache, no-store, must-revalidate
    X-Content-Type-Options
    Example: nosniff
    X-Amzn-Trace-Id
    Example: Root=1-5ec5f887-3b4fc2ee177c7637d58565af;Sampled=0
Last updated on