Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

Ring

AWS

文档

Support

My Cases

Console

Docs

Resources

Ecommerce Plug-ins

Publish

Connect

Docs

FAQ

感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Create Purchases

Create Purchases
Body parameter

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 Purchases

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": "2025-05-02T00:05:18Z",
        "location": "ENTRY",
        "payloadType": "FINANCIAL",
        "scanResult": {
          "id": "string",
          "type": "SHOPPER"
        }
      }
    ]
  },
  "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

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" for Credit card entry, "SCAN_CODE" for application QR code entry,

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

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

JSON

{
  "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

Error example responses

JSON

{
  "message": "string"
}

422 PurchaseRejected example

{
  "__type": "PurchaseRejected",
  "errorMsg": "1 cart item(s) were rejected.",
  "rejectedItems": [
    {
      "id": "SKU-1001",
      "type": "SCANCODE",
      "reason": "SKU_NOT_FOUND",
      "detail": "not in catalog",
      "lineItemId": "line-1"
    }
  ]
}

Status code response samples

Status	Meaning	Description
201	OK	You will respond with a 201 status code after successfully validating the API content against the API model and accepting all cart items in the request.
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	You will respond with 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
422	Purchase Rejected	You will respond with a 422 PurchaseRejected error when the request is well-formed but one or more cart items cannot be accepted. For example, the SKU or scancode is not present in the catalog, the item is not sellable, the price is unavailable, or the requested quantity is invalid. The response should include an `errorMsg` summary and a `rejectedItems` list identifying each rejected item and the machine-readable rejection reason.
404	Not Found	You will respond with 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	You will respond with 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	You will respond with 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	You will respond with a 503 ServiceUnavailable when the Ordering Connector is unavailable. For example the Company's endpoint is down for unplanned activity or for maintenance