Developer Console
Sign In
Sign In
Developer Console

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 
{
  "orderId": "string"
}
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

{
  "errorMsg": "string"
}
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