Checkout Service
The Checkout API is responsible for validating the data necessary for charging the shopper for their
shopping trip and gathering receipt data. The checkout step occurs right after Amazon calls into your
Ordering Connector to pass you all of the cart information for a shopping trip.
After Amazon calls your Ordering Connector API and provides you with all the cart information for a
shopping trip, you will need to provide Amazon with the following information:
- The Total Cost for the shopping trip
- The Total of All Promotions in the shopping cart
- The Total of All Sales Tax in the shopping cart
- The Shelf Price of All Line Items before you have calculated any taxes, fees, or promotions
Amazon will validate this data and send it to the payment processor to charge the shopper’s account. We
will charge the credit card the shopper used to enter your JWO-enabled store. Amazon also uses this
information to generate the shopper’s receipt.
Note: In the future, new attributes might be added. We recommend that you structure your code so that
it can handle new attributes gracefully
CheckoutCart
POST /v1/checkout/carts
You will use Amazon’s /v1/checkout/carts endpoint to tell Amazon you’re ready to charge the shopper and
generate their receipt for the corresponding shopping trip.
Body parameter
{
"idempotentShoppingTripId": "string",
"storeId": "string",
"lineItems": [
{
"productId": "string",
"type": "SKU",
"quantity": {
"value": "string",
"unit": "string"
},
"unitPrice": {
"totalPrice": {
"amount": "string",
"currencyCode": "USD"
},
"price": {
"amount": "string",
"currencyCode": "USD"
},
"depositsAndFees": [
{
"depositAndFeeAmount": {
"amount": "string",
"currencyCode": "USD"
},
"depositAndFeeDescription": "string",
"salesTax": {
"amount": "string",
"currencyCode": "USD"
}
}
],
"salesTax": {
"amount": "string",
"currencyCode": "USD"
},
"promotions": [
{
"promotionAmount": {
"amount": "string",
"currencyCode": "USD"
},
"promotionDescription": "string"
}
]
}
}
],
"orderTotals": {
"priceTotal": {
"amount": "string",
"currencyCode": "USD"
},
"subTotal": {
"amount": "string",
"currencyCode": "USD"
},
"promotionsTotal": {
"amount": "string",
"currencyCode": "USD"
},
"salesTaxTotal": {
"amount": "string",
"currencyCode": "USD"
}
}
}
Data Field |
Required |
Description |
idempotentShoppingTripId |
Required |
string, The idempotentShoppingTripId field contains a UUID string that Amazon generates to identify each shopping trip uniquely. The API uses this UUID to ensure that the service correctly handles multiple calls to the API using the same information with no unintended side effects |
storeId |
Required |
string <= 255 characters, The storeId field contains the store identifier that Amazon assigned to you during your onboarding process. If you have multiple stores, each store will have a unique identifier. |
lineItems |
Required |
Array of objects (LineItem) non-empty. The lineItems field contains a list of JSON objects that define each item in the shopper’s cart. This JSON object includes the following top-level fields:
- productId: Stores the SKU value that identifies each catalog item uniquely
- quantity: Stores the count for each line item the customer purchased
- type: Stores the type of ID you are using in the productId field (currently, only SKU values are supported)
- unitPrice: Stores all prices, promotions, sales tax, and deposits and fees associated with each line item in the cart. You must include at least one line item in the cart, and your lineItems must match the cart data Amazon sent to your Ordering Connector
|
Data Field |
Required |
Description |
productId |
Required |
string <= 255 characters. The productId field contains a unique identifier for each item in the cart. Currently, we only support SKU identifiers in this field. Also, the SKU you use in this field must be the same as the SKU in the product catalog you uploaded using the JWO portal |
type |
Required |
string (ProductIdType),Value: "SKU",The type field contains the unique ID your store uses to identify each item in the cart. Currently, we only support the SKU type |
quantity |
Required |
object (DecimalMeasure). The quantity field contains a JSON object that stores:
- How many of each item the shopper purchased. We store this data in the value field
- The unit-of-measurement for each item (i.e., unit and each). We store this data in the unit field
|
Data Field |
Required |
Description |
value |
Required |
string <= 10 characters. The value field contains the number of each item the shopper purchased. For example, if the shopper bought three loaves of bread, you would receive a 3 in this field. |
unit |
Required |
string. The unit field stores the measurement unit for each item in the cart |
|
unitPrice |
Required |
object (DecimalMeasure),The quantity field contains a JSON object that stores:
- Any deposit and fee amounts for each line item in the depositsAndFees object
- The shelf price of each line item before applying any promotions, sales tax, deposits, or fees in the price object
- Any promotions associated with each line item in the promotions object
- The sales tax for each line item in the salesTax object
- The total price of each line item, including any deposits and fees, promotions, and sales tax, in the totalPrice object
|
Data Field |
Required |
Description |
totalPrice |
Required |
object (Price) |
Data Field |
Required |
Description |
amount |
Required |
string <= 10 characters. The amount field contains the monetary amount |
unit |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
price |
Required |
object (Price) |
Data Field |
Required |
Description |
amount |
Required |
string <= 10 characters. The amount field contains the monetary amount |
unit |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
depositsAndFees |
Optional |
Array of objects (DepositAndFee) .The depositsAndFees field contains a list of JSON objects that store the following deposit/fee-related information:
- The amount of the deposit/fee in the depositsAndFees object.
- A description of the deposit/fee in the depositAndFeeDescription field.
- Any sales tax associated with the deposit/fee in the optional sales_tax object. You can have multiple deposit/fee entries on a single line item.
|
Data Field |
Required |
Description |
depositAndFeeAmount |
Required |
object (Price) |
Data Field |
Required |
Description |
value |
Required |
string <= 10 characters. The amount field contains the monetary amount. |
currencyCode |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
depositAndFeeDescription |
Required |
string <= 100 characters ^[0-9a-zA-Z_-]$.,'/@. This field contains a stringthat describes the purpose of the deposit/fee |
salesTax |
Optional |
object (Price) |
Data Field |
Required |
Description |
value |
Required |
string <= 10 characters. The amount field contains the monetary amount. |
currencyCode |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
|
salesTax |
Required |
object (Price) |
Data Field |
Required |
Description |
amount |
Required |
string <= 10 characters. The amount field contains the monetary amount |
unit |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
promotions |
Optional |
Array of objects (Promotion). The promotions field contains a list of JSON objects that store promotional information for any relevant line items in the cart. The fields in this JSON object include:
- The value of the promotion in the promotionAmount object
- A description of the promotion in the promotionDescription field. Each item in the cart can have more than one promotion associated with it
|
Data Field |
Required |
Description |
promotionAmount |
Required |
string <= 10 characters. The value field contains the number of each item the shopper purchased. For example, if the shopper bought three loaves of bread, you would receive a 3 in this field. |
Data Field |
Required |
Description |
value |
Required |
string <= 10 characters. The amount field contains the monetary amount. |
currencyCode |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
promotionDescription |
Required |
string <= 100 characters ^[0-9a-zA-Z_-]$.,'/@. This field contains a description of the promotion you are applying to a line item. |
|
|
|
orderTotals |
Required |
object (OrderTotal). The orderTotals field contains a JSON object that holds the following fields:
- The priceTotal field, which contains the sum of all the totalPrice fields in the cart
- The promotionsTotal field, which contains the sum of all the promotions fields in the cart
- The subTotal field, which contains the sum of all the price fields in the cart
- The salesTaxTotal field, which contains the sum of all the salesTax and salesTax fields in the cart
|
Data Field |
Required |
Description |
priceTotal |
Required |
object (Price) |
Data Field |
Required |
Description |
amount |
Required |
string <= 10 characters. The amount field contains the monetary amount |
unit |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
promotionsTotal |
Required |
object (Price) |
Data Field |
Required |
Description |
amount |
Required |
string <= 10 characters. The amount field contains the monetary amount |
unit |
Required |
string (CurrencyCode). Value: "USD". 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. |
|
salesTaxTotal |
Required |
object (Price) |
Data Field |
Required |
Description |
amount |
Required |
string <= 10 characters. The amount field contains the monetary amount |
unit |
Required |
string (CurrencyCode). Value: "USD". 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
> 201 Response
Value |
Description |
orderId |
string <= 255 characters. If your request to Amazon’s Checkout API is successful, you will receive a 201 HTTP Status Code and a JSON object containing the orderId. For your request to be successful, your request to Amazon’s Checkout API will need to pass the following validations:
- All promotions and promotions must calculate correctly
- All sales taxes, regulatory fees, and special taxes must calculate correctly
- The subtotal and shopping trip total must calculate correctly
- The cart must be the same as the one we sent to the store when the shopper checked out
|
Failure example responses
Status |
Meaning |
Description |
400 |
UnknownShoppingTripException |
You will receive a 400 UnknownShoppingTrip if you attempt to checkout using an invalid shoppingTrip |
400 |
InvalidRequestException |
The API Gateway will return a 4xx level error when requests to the Checkout API contain invalid data |
400 |
CartContentValidationFailedException |
You will receive a 4xx CartContentValidationFailedException if you attempt to submit an empty
cart to Amazon’s Checkout API. You will also get this error if the contents of the cart you submit
do not match the contents of the cart Amazon sent to you when the shopper checked out |
400 |
CartOrderTotalInvalidException |
Amazon will return a 400 CartOrderTotalInvalidException if any of the items do not have a price. |
403 |
AuthenticationException |
Amazon will return a 403 AuthenticationException if the API call fails due to authorization. For example the IAM role used to call the API has not been authorized by the Amazon service |
500 |
InternalServerException |
Amazon expects a 500 InternalServerException when the checkout call fails due to a server issue.For example an un-handled exception or error occurs when processing the Amazon API call |