Adjust Charge
The Payment service API provides the Company a single point of integration with Amazon to facilitate
payment processor integration. The payment service allows the Company to complete one integration while
getting access to multiple payment processors.
Note: In the future, new attributes might be added. We recommend that you structure your code so that it can handle new attributes gracefully
Adjust Charge
POST /v1/adjust/charge
The Adjust method is used to allow the Company to charge the total price for the cart to the shopper payment
instrument authrozied on store entry. While the company provides the cart total price in the adjust call,
Amazon will perform the incremental adjustment based upon the difference between the total cart price and the initial pre-auth.
Body parameter
{
"storeId": "string",
"shoppingTripId": "string",
"amount": {
"amount": 0,
"code": "str"
}
}
| Data Field |
Required |
Description |
| storeId |
Required |
string <= 255 characters ^[0-9a-zA-Z_-]*$. The storeId field contains the store identifier designated during your onboarding process. If you have multiple stores, each store will have a unique identifier. You use this field to identify in which one of your store locations a shopper is requesting access |
| shoppingTripId |
Required |
string <= 255 characters ^[0-9a-zA-Z_-]+$. The ShoppingTripId field contains a Universally Unique ID (UUID) for the current shopping trip. Amazon generates a UUID for each shopping trip. |
| amount |
Required |
number, The amount field contains the calculated price for the cart that will be charged to the shopper payment mechanism. |
| Data Field |
Required |
Description |
| amount |
Required |
number. The amount field contains the calculated price for the cart that will be charged to the shopper payment mechanism. |
| code |
Required |
string <= 3 characters ^[A-Z]{3}$. CurrencyCode field contains an enumerated string representing the type of currency you are collecting. For example, if you’re collecting U.S. dollars, you would enter USD into this field. |
|
Success example responses
> 200 Response
{
"status": "APPROVED",
"authorizedAmount": {
"amount": 0,
"code": "str"
}
}
| Data Field |
Required |
Description |
| status |
Required |
string (AdjustStatus). Enum: "APPROVED" "DECLINED" "PENDING". Shows the status of the Adjust transaction. Approved and Declined are terminal states. Pending requires retries until Payment reaches a terminal state. |
| authorizedAmount |
Required |
object. The total amount currently authorized on the charge. This value represents the maximum amount available for a subsequent CaptureCharge request. See Understanding authorizedAmount by Status below for critical usage guidance. |
| Data Field |
Required |
Description |
| amount |
Required |
number. The amount field contains the value of the last known approved amount for the shopper's payment mechanism. This is the maximum amount that can be captured via CaptureCharge. |
| code |
Required |
string <= 3 characters ^[A-Z]{3}$. CurrencyCode field contains an enumerated string representing the type of currency you are collecting. For example, if you're collecting U.S. dollars, you would enter USD into this field. |
|
Understanding authorizedAmount by Status
The authorizedAmount field behavior varies depending on the status returned. It is critical to read this value and use it to determine the correct amount for your subsequent CaptureCharge request.
| Status |
authorizedAmount behavior |
What This Means |
| APPROVED |
Updated to the new adjusted amount |
The issuing bank approved the incremental authorization. The full adjusted amount is now authorized and available for capture. |
| DECLINED |
Remains at the previously authorized amount (i.e. the original pre-auth value) |
The issuing bank declined the incremental authorization. Only the original pre-auth amount remains authorized. You must use this value as the maximum for any subsequent CaptureCharge request. |
| PENDING |
May reflect the previously authorized amount |
The adjustment is still being processed. Retry until a terminal state (APPROVED or DECLINED) is reached. |
Important: Handling a DECLINED Adjust Response
When status = "DECLINED":
- The
authorizedAmount returned represents the maximum amount you are permitted to capture. It will not be null or blank — it will contain the original pre-auth value.
- Do not submit a CaptureCharge request for an amount exceeding
authorizedAmount.amount. The system will reject any capture where the requested amount is greater than the authorized amount with a RejectedException (e.g. "Capture amount X should be less than or equal to charge amount Y").
- If you wish to capture the pre-authorized amount after a declined adjust, you must explicitly send a CaptureCharge request at or below the
authorizedAmount.amount returned in the Adjust response.
- There is no automatic fallback that captures the pre-auth amount on your behalf. If no valid capture is submitted within the authorization window (typically 72 hours), the authorization will auto-cancel and no funds will be collected.
- In the Partial Delegation flow, the merchant (Company) owns the capture-amount decision. Your integration must read
authorizedAmount from the Adjust response and use it accordingly.
⚠️ Important: If you send the full basket total to CaptureCharge after a declined adjust (instead of the authorizedAmount), the capture will be rejected. If no valid capture is retried at the approved amount before the authorization auto-cancels (typically 72 hours), the result will be zero funds collected and a full loss for the transaction.
Example: Declined Adjust Flow
| Step |
Action |
Outcome |
Details |
| 1 |
CreateCharge (pre-auth) for $5.00 |
✅ Approved |
authorizedAmount = $5.00 |
| 2 |
AdjustCharge to $25.02 |
❌ Declined by issuing bank |
authorizedAmount = $5.00 (unchanged) |
| 3 |
CaptureCharge at $25.02 |
❌ Rejected (over-capture) |
"Capture amount $25.02 should be less than or equal to charge amount $5.00" |
| 4 |
✅ Correct: CaptureCharge at $5.00 |
✅ Capture succeeds |
$5.00 collected |
Failure example responses
| Status |
Meaning |
Description |
| 400 |
UnknownShoppingTrip |
You will receive a 400 UnknownShoppingTrip if you attempt to checkout using an invalid shoppingTrip |
| 400 |
BadRequestException |
The API returns a 400 Bad Request Error when requests to the payment service might be missing a required value or an incorrect data type is passed to the API. For example an incorrect storeId or shoppingTripId |
| 429 |
Too Many Requests |
Too Many Requests – The client has sent too many requests in a given amount of time (rate limiting. A Retry-After header will be included in the response indicating how long to wait before making a new request. Retry-After: 600 (5 minutes) is the current setting |
| 500 |
ServiceException |
A 500 ServerError is received when the payment servie call fails due to a server issue. For example an un-handled exception or error occurs when processing the API call. You are encouraged to retry the API call to Amazon using an exponential backoff algorithm |
503 ServiceUnavailableException, example responses
{
"errorMsg": "string",
"retryAfter": "string"
}
| Data Field |
Required |
Description |
| errorMsg |
Required |
string. A 503 ServiceUnavailable is returned when the payment serivce is unavailable. If you receive a 503, you should re-try the API call after the indicated time in the API response. |
| retryAfter |
Required |
string. The the time to wait for retry in seconds. |
