Ordering API v1 reference
Amazon Business Ordering API Model
Overview
With Amazon Business ordering API, integrators can build applications that allow Amazon Business customers to define and execute an order request.
Version information
Version : 1.0.0
URI scheme
Host : www
Schemes : HTTPS
Operations
Paths
POST /ordering/2022-10-30/orders
Operation: placeOrder
Description
Attempts to place an order with the given attributes and expectations from the order request.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | request required | A request to place an order. | PlaceOrderRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | The order was successfully placed. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestid (string) : Unique request reference identifier. | PlaceOrderResult |
| 400 | Request has missing or invalid parameters and can't be parsed. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string) : Unique request reference identifier. | ErrorList |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers : x-amzn-requestId (string) : Unique request reference identifier. | ErrorList |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string) : Unique request reference identifier. | ErrorList |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string) : Unique request reference identifier. | ErrorList |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
GET /ordering/2022-10-30/orders/{externalId}
Operation: orderDetails
Description
Retrieves order details with externalId.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | externalId required | The unique identifier provided by the customer while placing the order. | string |
| Header | x-amz-user-email required | The email address of the user requesting this resource. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Order details successfully retrieved. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestid (string) : A unique request reference identifier. | OrderDetailsResult |
| 400 | The request has missing or invalid parameters and can't be parsed. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string) : A unique request reference identifier. | ErrorList |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers : x-amzn-requestId (string) : A unique request reference identifier. | ErrorList |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string) : A unique request reference identifier. | ErrorList |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RateLimit-Limit (string) : The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string) : A unique request reference identifier. | ErrorList |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 404 | The specified resource doesn't exist. Headers: x-amzn-RateLimit-Limit (string):The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string):A unique request reference identifier. | ErrorList |
| 415 | The request payload is in an unsupported format. Headers: x-amzn-RateLimit-Limit (string):The allowed rate limit (requests per second) for this operation. x-amzn-requestId (string):Unique request reference identifier. | ErrorList |
Definitions
PlaceOrderRequest
A request to place an order.
| Name | Description | Schema |
|---|---|---|
| externalId required | A customer-specified identifier that is unique for each order. minLength : 1 maxLength : 255 | string |
| lineItems required | Items in the order. | < RequestLineItem > array |
| attributes required | Customer-determined order properties. | < Attribute > array |
| expectations required | Customer expectations about aspects of an order they do not directly control. | < Expectation > array |
RequestLineItem
A single line item in an order request.
| Name | Description | Schema |
|---|---|---|
| externalId required | A customer-specified identifier that is unique for each line item. minLength : 1 maxLength : 127 | string |
| quantity required | The total number to order for this item. Minimum value : 1 | integer |
| attributes required | Customer-determined line item properties. | < Attribute > array |
| expectations required | Line-item-specific customer expectations about aspects of the order they do not directly control. | < Expectation > array |
Attribute
A customer-determined aspect of the order.
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
Expectation
A customer's expectation about an aspect of an order they do not control.
| Name | Description | Schema |
|---|---|---|
| expectationType required | The schema name for a subtype. | string |
PlaceOrderResult
The result of a request to place an order. Specifies how line items in the request were broken up into ordered and rejected portions.
Polymorphism : Composition
| Name | Description | Schema |
|---|---|---|
| lineItems required | Order results for specific line items. | < ResultLineItem > array |
| acceptanceArtifacts required | Results of a successful order. | < AcceptanceArtifact > array |
| rejectionArtifacts required | Reasons the order was rejected. | < RejectionArtifact > array |
OrderDetailsResult
The details of the order. Specifies how line items are broken up into ordered and rejected portions.
Polymorphism : Composition
| Name | Description | Schema |
|---|---|---|
| lineItems required | Order results for specific line items. | < ResultLineItem > array |
| acceptanceArtifacts required | Results of a successful order. | < AcceptanceArtifact > array |
| rejectionArtifacts required | Reasons the order was rejected. | < RejectionArtifact > array |
OrderResult
| Name | Description | Schema |
|---|---|---|
| lineItems required | Order results for specific line items. | < ResultLineItem > array |
| acceptanceArtifacts required | Results of a successful order. | < AcceptanceArtifact > array |
| rejectionArtifacts required | Reasons the order was rejected. | < RejectionArtifact > array |
ResultLineItem
Results of an order for a specific line item.
| Name | Description | Schema |
|---|---|---|
| externalId required | The customer-specified identifier for this line item. | string |
| acceptedItems required | Portions of the requested line item quantity that were successfully ordered. | < AcceptedItem > array |
| rejectedItems required | Portions of the requested line item quantity that couldn't be ordered. | < RejectedItem > array |
AcceptedItem
A portion of requested item quantity that was successfully ordered.
| Name | Description | Schema |
|---|---|---|
| quantity required | The accepted line item quantity. | integer |
| artifacts required | Details about the ordered line item quantity. | < AcceptanceArtifact > array |
RejectedItem
A portion of requested item quantity that couldn't be ordered.
| Name | Description | Schema |
|---|---|---|
| quantity required | This rejected portion's item quantity. | integer |
| artifacts required | Details about the rejected line item quantity. | < RejectionArtifact > array |
AcceptanceArtifact
The details of a successful order.
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
RejectionArtifact
Details the reason for order rejection.
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
ErrorList
A list of error responses for an unsuccessful request.
| Name | Schema |
|---|---|
| errors required | < Error > array |
Error
An error response for an unsuccessful request.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message describing the error condition. | string |
| details optional | Additional details to help the caller understand or fix the issue. | string |
Region
The country or region where the buyer places an order.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| region required | The Amazon Business stores. | enum (DE, FR, UK, IT, ES, US, CA, JP) |
SelectedProductReference
Contains a reference to the product to order. This attribute can be passed at line-item or order level. If passed at order level, the product reference will apply to all line items that has no set attribute.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| productReference required | The type of reference selected for a product. | ProductReference |
SelectedBuyingOptionReference
Contains a reference to the buying option to order. This attribute can be passed at line-item or order level. If passed at order level, the buying option reference will apply to all line items that has no set attribute.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| buyingOptionReference required | The type of reference selected for a buying option. | BuyingOptionReference |
ShippingAddress
The address where the order will be shipped.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| address required | The address where an item or order will be sent. This attribute can be passed at line-item or order level. If passed at order level, the address will apply to all line items that has no set attribute. | Address |
SelectedPaymentMethodReference
The payment method where the charges for the order will apply. This attribute can only be passed at order level.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| paymentMethodReference required | The payment method used to purchase the item or order. | PaymentMethodReference |
BuyingGroupReference
A reference to the buying group associated with an order request. This attribute can only be passed at order level.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| groupReference required | A reference to the buying group. | GroupReference |
BuyerReference
A reference to the buying customer. This attribute can only be passed at order level.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| userReference required | A reference to the buyer. | UserReference |
PurchaseOrderNumber
A unique reference to the purchase order form of the order request. This attribute can only be passed at order level.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| purchaseOrderNumber required | A numerical string acting as the identifier for the purchase order form. Length : 1 - 255 | string |
BlanketPurchaseOrderNumber
Identifies if the order request is placed against the blanket purchase order.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| purchaseOrderNumber required | A numerical string acting as the identifier for the purchase order form. Length : 1 - 255 | string |
TrialMode
Indicates that an order is a trial order. The steps to place an order will be completed, but no actual order will be created. This attribute can only be passed at order level.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
ExpectedUnitPrice
The unit price value the customer expects for an item. This expectation can be passed at line-item or order level. If passed at order level, the expected monetary charge will apply to all line items that has no set expectation.
Polymorphism : Inheritance
Discriminator : expectationType
| Name | Description | Schema |
|---|---|---|
| expectationType required | The schema name for a subtype. | string |
| amount required | The expected unit price for an item. | Money |
ExpectedCharge
The monetary charge that is expected for an item or order. This expectation can be passed at line-item or order level. If passed at order level, the expected monetary charge will apply to all line items that has no set expectation.
Polymorphism : Inheritance
Discriminator : expectationType
| Name | Description | Schema |
|---|---|---|
| expectationType required | The schema name for a subtype. | string |
| amount required | The expected charge amount. | Money |
| source required | Indicates where the charges come from. | ChargeSource |
OrderIdentifier
The Amazon-generated identifier for a placed order. This artifact will be included at acceptance-item level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
| identifier required | The identifier. | string |
DeliveryTimeRange
The time range when a product is expected to reach its specified location. This artifact will appear at acceptance-item level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
| lowerBoundary required | The earliest estimated delivery date when an item or order is expected to reach the buyer or recipient. | DateTime |
| upperBoundary required | The latest estimated delivery date when an item or order is expected to reach the buyer or recipient. | DateTime |
UnitPrice
The unit price for an item. This artifact will appear at acceptance-item level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
| amount required | The unit price. | Money |
Charge
A qualified monetary charge for an item or an order. This artifact will appear at acceptance-item level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
| amount required | The charge. | Money |
| category required | The charge category. | enum (SUBTOTAL, SHIPPING, GIFT_WRAP, PAYMENT_METHOD_FEE, EXPORT_FEE, OTHER) |
| type required | These are the type of charges applied to an item or order. | enum (PRINCIPAL, TAX, DISCOUNT) |
PriceSuppressionDirective
Indicates that price information should be omitted in packing slips for all shipments in the order. This attribute can only be passed at order level.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
UnavailableQuantity
The number of unavailable quantity deducted from the total requested quantity. The order can only be fulfilled by the number of available quantity. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
| quantity required | The number of unavailable items. | integer |
AvailableQuantity
The number of available items. The order may be rejected because of the ordering constraints. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
| quantity required | The number of available items. | integer |
RejectionMessage
A message that summarizes a reason for rejection. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
| message required | The rejection message. | string |
RejectionCode
A code that maps to a reason for rejection. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
| code required | The rejection code. | string |
AgeRestriction
A non-compliance with the age limit requirement results in order rejection. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
| minimumAge required | The minimum age required to purchase the item. | number |
DeliveryTimeRangeIncongruity
The estimated delivery time is outside the delivery time range, which led to order rejection. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
BrokenUnitPriceExpectation
The unit price exceeds the expected limit, which led to order rejection. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
BrokenChargeExpectation
The charges exceed the expected limit, which led to order rejection. This artifact will appear at rejected-item level.
Polymorphism : Inheritance
Discriminator : rejectionArtifactType
| Name | Description | Schema |
|---|---|---|
| rejectionArtifactType required | The schema name for a subtype. | string |
| boundary required | The broken boundary for the charge. | Money |
| actualAmount required | The actual amount charged to an item or order. | Money |
| sources optional | The list of charges with sum that exceeds the limit. | < ChargeSource > array |
ChargeSource
The source of a monetary charge in an item or an order.
Type : enum
| Value | Description |
|---|---|
| SUBTOTAL | The sum of adding some numbers together but isn't the final total. |
| SHIPPING | The cost of shipping an item or order. |
| TAX | The tax charges for an item or order. |
Signed
Indicates that all accepted items have been placed as Amazon Business orders. This artifact will appear at order-result level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
Shipment
The shipment details for an order. This artifact will appear at order-level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
| identifier required | The identifier for a shipment. | string |
| packages required | The collection of packages in this shipment. | < Package > array |
Package
The package within the shipment.
| Name | Description | Schema |
|---|---|---|
| packageReference required | A reference to the package. | PackageReference |
| packageAttributes required | The attributes of the package. | < packageAttribute > array |
ShipmentGroup
The shipment group details for a line item. This artifact will appear at line item level.
Polymorphism : Inheritance
Discriminator : acceptanceArtifactType
| Name | Description | Schema |
|---|---|---|
| acceptanceArtifactType required | The schema name for a subtype. | string |
| identifier required | The identifier for a shipment. | string |
| packageReferences required | The collection of package references. | < PackageReference > array |
| quantity required | The total number of quantities in the package or shipment. | integer |
PackageReference
The base type for a reference to a package.
| Name | Description | Schema |
|---|---|---|
| packageReferenceType required | The schema name for a subtype. | string |
CarrierTrackingNumber
The carrier tracking number of the package.
Polymorphism : Inheritance
Discriminator : packageReferenceType
| Name | Description | Schema |
|---|---|---|
| packageReferenceType required | The schema name for a subtype. | string |
| value required | The carrier tracking number. Minimum length : 1 | string |
PackageAttribute
The base type for a package attribute.
| Name | Description | Schema |
|---|---|---|
| packageAttributeType required | The schema name for a subtype. | string |
PackageTrackingAttribute
The tracking package attribute.
Polymorphism : Inheritance
Discriminator : packageAttributeType
| Name | Description | Schema |
|---|---|---|
| packageAttributeType required | The schema name for a subtype. | string |
| carrierName required | The carrier name. Minimum length : 1 | string |
| deliveryDateRange required | The delivery date range when a package is expected to reach the buyer. | deliveryDateRange |
ProductReference
A unique reference for a product.
| Name | Description | Schema |
|---|---|---|
| productReferenceType required | The schema name for a subtype. | string |
BuyingOptionReference
A unique reference for a buying option.
| Name | Description | Schema |
|---|---|---|
| buyingOptionReferenceType required | The schema name for a subtype. | string |
Address
The base type for an address.
| Name | Description | Schema |
|---|---|---|
| addressType required | The schema name for a subtype. | string |
PaymentMethodReference
A unique reference to a payment method.
| Name | Description | Schema |
|---|---|---|
| paymentMethodReferenceType required | The schema name for a subtype. | string |
GroupReference
A unique reference for a group.
| Name | Description | Schema |
|---|---|---|
| groupReferenceType required | The schema name for a subtype. | string |
UserReference
A unique reference for a user.
| Name | Description | Schema |
|---|---|---|
| userReferenceType required | The schema name for a subtype. | string |
Money
Represents a monetary value in currency.
| Name | Description | Schema |
|---|---|---|
| currencyCode required | The three-digit currency code based on ISO 4217. Pattern : "^[A-Z]{3}$" | string |
| amount required | The amount in currency value. | number |
DateTime
The date format based on ISO 8601.
| Name | Description | Schema |
|---|---|---|
| date required | The date and time format based on ISO 8601. Time zone is optional. The format is YYYY-MM-DD HH:MM:SS:MMS. For example, 2020-07-10 15:00:00.000, represents the 10th of July 2020 at 3 p.m. | string (date-time) |
Auxiliary
Additional fields for customers to send additional information for pre- or post-order processing.
Polymorphism : Inheritance
Discriminator : attributeType
| Name | Description | Schema |
|---|---|---|
| attributeType required | The schema name for a subtype. | string |
| values required | A reference to auxiliary values. | AuxiliaryValues |
AuxiliaryValues
Auxiliary field values.
Max properties: 30
| Name | Description | Schema |
|---|---|---|
| values required | An array of auxiliary values. | AuxiliaryValue |
AuxiliaryValue
An auxiliary value.
| Name | Description | Schema |
|---|---|---|
| value required | A value of an auxiliary field. minLength: 1 maxLength: 100 | String |
Updated 5 months ago