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 |