Developer Console
Sign In
Sign In
Developer Console

Create Purchases

Amazon will call the Company Ordering Connector API to pass information like shopper identities, payment sources, carts, and cart items. The use of the Ordering connector will enable the Company to implement logic to calculate order totals after applying promotions and discounts to the shopper cart. The Company will also be able to apply loyalty and taxes as applicable.

The Ordering Connector serves as a common API for customers who use Amazon's Just Walkout and Dashcart services. Please refer to the appropriate section for the Company's implementation.

Requests made through the Ordering Connector must be idempotent—meaning no additional effects should occur if Amazon calls your API more than once using the same parameters. Please refer to the idempotentShoppingTripId key for more information on how to ensure the requests are idempotent.

Note: In the future, new attributes might be added. We recommend that you structure your code so that it can handle new attributes gracefully.

Create Purchase

Amazon will use the Company /v1/order/purchases endpoint to create a purchase record

POST /v1/order/purchases

Body parameter

{
  "requestId": "string",
  "idempotentShoppingTripId": "string",
  "storeId": "string",
  "shoppingTrip": {
    "startTime": "2024-03-22T17:09:39Z",
    "endTime": "2024-03-22T17:09:39Z",
    "authEvents": [
      {
        "id": "string",
        "timestamp": "2024-03-22T17:09:39Z",
        "location": "ENTRY",
        "payloadType": "FINANCIAL"
      }
    ]
  },
  "cartItems": [
    {
      "id": "string",
      "type": "SKU",
      "quantity": {
        "value": "string",
        "unit": "string"
      },
      "externalIdentifiers": [
        {
          "id": "string",
          "type": "UPC"
        }
      ],
      "lineItemId": "string"
    }
  ],
  "shopperIdentity": {
    "id": "string"
  },
  "shopperDeviceId": "string",
  "paymentSource": {
    "id": "string"
  }
}
Data Field Required Description
requestId Required The requestId field contains a UUID ,Universally Unique Identifier,for each checkout request. Amazon generates this UUID for each request
idempotentShoppingTripId Required The idempotentShoppingTripId field contains a Universally Unique ID (UUID) for the current shopping trip. Amazon generates a UUID for each shopping trip. 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. In other words, the idempotentShoppingTripId ensures that calls to the API are idempotent. Compare the idempotentShoppingTripId to the requestId field
storeId Required <= 255 characters. The storeId field contains a unique identifier for your store. This identifier is the store ID you defined during your onboarding process with Amazon. You also use this storeId when uploading your catalog into the JWO portal
shoppingTrip Required object (ShoppingTrip) . Provides details about a shopping trip's significant events.Properties
  • startTime - Timestamp when the shopping trip started in UTC format
  • endTime - Timestamp when the shopping trip ended in UTC format
  • authEvents - A list of shopper authentication related events that occurred during the shopping trip.
Data Field Required Description
startTime Required string date-time. The shoppingTrip.startTime field contains a timestamp for the time the shopping trip starts. This timestamp records the time when the shopper walks through the gate and into the store. The timestamp follows the ISO-8601 format
endTime Required string date-time.The shoppingTrip.endTime field contains a timestamp for the time the shopping trip ends. This timestamp records the time when the shopper walks out of the store through the gate. The timestamp follows the ISO-8601 format
authEvents Required Array of objects (AuthEvent). The shoppingTrip.authEvents field contains a list of all authorization events associated with a shopping trip. An authorization event occurs whenever a shopper enters or exists the store through a JWO gate (See the Identity Connector API documentation for more information). In the case of a group shopping trip (multiple QR code scan), Amazon will include the authorization events for all of the shoppers in the group in this list.
Data Field Description Required
id Required string <= 255 characters ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}. The shoppingTrip.authEvents[X].id field contains a UUID value that uniquely identifies each authorization event when a shopper or shopping group interacts with a JWO gate. Please refer to the Identity Connector API documentation for more information
timestamp Optional string date-time. The shoppingTrip.authEvents[].timestamp field contains the timestamp when the authorization event took place
location Optional string (AuthLocation). Enum: "ENTRY", "EXIT", "MANUAL_IN_STORE"
payloadType Required string (AuthPayloadType), Enum: "FINANCIAL", "SCAN_CODE"
scanResult Optional object (ScanResult)
Data Field Description Required
id Required string <= 255 characters, The ScanResult.id is the identifier provided to Amazon systems by the customer.
type Required string (ScanResponseType),Enum: "SHOPPER", "ASSOCIATE", "CASH", "LOYALTY"
cartItems Required Array of objects (CartItem). The cartItems field contains a list of JSON objects that define each item in the shopper’s cart
Data Field Required Description
id Required string <= 255 characters. The cartItems[x].id field will contain a unique identifier for each item in the cart. The identifier will be a SKU that matches the product catalog uploaded to JWO
type Required string (CartItemType). Enum: "SKU", "SCANCODE".The cartItems[x].type field contains a list of JSON objects that define each item in the shopper's cart
lineItemId Optional string <= 255 characters. Optionally provided for dash cart customer by callers so that output cart items can be specifically linked to input cart items. When present, the line item id will be a unique value amongst other cart items in the request and response cart items must contain the same line item id as their corresponding request cart item.
quantity Required object (DecimalMeasure). An example DecimalMeasure for a product sold by weight is 1.1 (value) lb (unit). For a product sold by unit like soda,DecimalMeasure is 'quantity': { 'value': 1.0, 'unit': 'unit'}
Data Field Description Required
value Required string <= 10 characters
unit Required string
externalIdentifiers Optional Array of objects (ExternalIdentifier). Optional field for dash cart customers that includes any additional identifiers to associate with this cart item
Data Field Description Required
id Required string <= 255 characters
type Required string (ExternalIdentifierType).Enum: "UPC","EAN", "BARCODE", "GTIN", "PLU"
shopperIdentity Optional object (ShopperIdentity). Uniquely identifies a shopper. This value is returned by Identity connector APIs for integrations also implementing the Identity connector
Data Field Description Required
id Required string <= 255 characters. The shopperIdentity.id field holds a UUID value that uniquely identifies the shopper associated with each purchase. The identifier in this field must be a UUID string and cannot exceed 255 characters in length
shopperDeviceId Optional <= 255 characters. The shopperDeviceId field holds a UUID value that uniquely identifies the shopper’s mobile device. This ID will remain consistant for all of the shopper’s shopping trips as long as they use the same device
paymentSource Deprecated The paymentSource object contains optional information about the source of payment for this transaction. The object contains a single id field, which is required if the paymentSource field is present
Data Field Description Required
id Deprecated The paymentSource.id field contains a unique identifier for the shopper’s payment information. The company will use this information when charging the shopper for the shopping trip.

Example responses

> 200 Response

Example responses

{
  "purchaseId": "string"
}
Data Field Required Description
purchaseID Required string <= 255 characters .The PurchaseId is a unique identifier for the shopping trip as represented in the Company system. The PurchaseId can be used as a reference to track the shopping cart across the Amazon and Company systems. For example if an empty cart is returned, the purchaseId can be set to an empty string. If the cart contains items, the purchaseId can be set to a unique value in the Company's system

Create Purchase example responses

Status Meaning Description
201 OK Successful response
400 Bad Request The API returns a 400 Bad Request Error when requests to the Ordering Connector might be missing a required value or an incorrect data type is passed to the API
401 Unauthorized The API returns a 401 AuthorizationDeclined Error when requests to the Ordering Connector does not contain the correct authorization. For example the Amazon IAM role is not allow listed in the Company's API Gateway
404 Not Found The API returns a 404 when the request is made to an unknown resource. For example the Company's invoke URL is not properly configured within the Amazon system
429 Throttling 429 response The API returns a 429 when the service needs to throttle it's caller. Caller is instructed to retry after backoff when this error occurs.
500 Internal Server Error Amazon expects a 500 ServerError when the Ordering Connector fails due to a server issue. For example an un-handled exception or error occurs when processing the Amazon API call.
503 Service Unavailable Amazon expects a 503 ServiceUnavailable when the Ordering Connector is unavailable. For example the Company's endpoint is down for unplanned activity or for maintenance