Reporting API v1 reference
Amazon Business API for Order History
Overview
With Amazon Business API for Order History, you can analyze your order and supplier data, track shipments, and track progress towards your spending goals. This API fetches orders from all legal entities under the account.
Version information
Version : 2021-01-08
License information
License : Amazon Software License
License URL : https://aws.amazon.com/asl/
URI scheme
Host : api.business.amazon.com
Schemes : HTTPS
Consumes
application/json
Produces
application/json
External Docs
Description : Learn more about the Amazon Business API.
URL : http://business.amazon.com
Operations
getOrdersByOrderDate
getOrdersByOrderId
Paths
GET /reports/2021-01-08/orders
Operation: getOrdersByOrderDate
Description
Returns a paginated list of orders with order dates that fall within the date range that you specify. You can optionally retrieve lineItem, charges, and shipments for these orders.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Query | startDate required | The lower limit for the search range. This date represents the order date. | string (date-time) | - |
| Query | nextPageToken optional | A page token returned in the response to your previous request when the number of results exceed the page size (100). To get the next page of results, include nextPageToken as the only parameter. There are no more pages to return when the response returns no nextPageToken. This token needs to be encoded. | string | - |
| Query | endDate required | The upper limit for the search range. This date represents the order date. | string (date-time) | - |
| Query | includeLineItems optional | An option to get all line items associated with the order. | boolean | "false" |
| Query | includeShipments optional | An option to get all shipments associated with the order. | boolean | "false" |
| Query | includeCharges optional | An option to get all charges associated with the order. | boolean | "false" |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Orders were successfully retrieved. Headers : Access-Control-Allow-Origin (string) x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-requestid (string) : Amazon auto-generated unique request reference identifier. | OrdersOutput |
For error status codes, descriptions and schemas, see Error responses and schemas.
Produces
application/json
GET /reports/2021-01-08/orders/{orderId}
Operation: getOrdersByOrderId
Description
API to fetch details for a specific order based on order identifier. You can optionally retrieve lineItem, charges, and shipments for this order.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Path | orderId required | The unique identifier for an order to get the corresponding order details. | string | - |
| Query | includeLineItems optional | An option to get all line items associated with the order. | boolean | "false" |
| Query | includeShipments optional | An option to get all shipments associated with the order. | boolean | "false" |
| Query | includeCharges optional | An option to get all charges associated with the order. | boolean | "false" |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Orders were successfully retrieved. Headers : Access-Control-Allow-Origin (string) x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-requestid (string) : Amazon auto-generated unique request reference identifier. | OrdersOutput |
For error status codes, descriptions and schemas, see Error responses and schemas.
Produces
application/json
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 400 | The request has missing or invalid parameters and can't be parsed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated unique request reference identifier. | ErrorList |
| 401 | The request's authorization header isn't formatted correctly or doesn't contain a valid token. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated 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-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated unique request reference identifier. | ErrorList |
| 404 | The specified resource doesn't exist. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated unique request reference identifier. | ErrorList |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated unique request reference identifier. | ErrorList |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers: Access-Control-Allow-Origin (string) x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated unique request reference identifier. | ErrorList |
| 504 | A gateway timeout occurred. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-requestId (string):Amazon auto-generated unique request reference identifier. | ErrorList |
Definitions
Money
The monetary value.
| Name | Description | Schema |
|---|---|---|
| currencyCode required | The three-digit currency code in ISO 4217 format. | string |
| amount required | The currency amount. | string |
Order
The response schema for the getOrdersByDates and getOrdersById operations.
| Name | Description | Schema |
|---|---|---|
| orderDate required | The date when the order was placed. | string (date-time) |
| orderId required | Amazon auto-generated identifier for the order. | string |
| purchaseOrderNumber required | The Purchase Order Number assigned to the order. | string |
| orderQuantity required | The item quantity relevant to this order. | integer |
| orderStatus required | The status of the order. | enum (OrderStatus) |
| lastOrderApproverName required | The name of the last person who approved the order. | string |
| buyingCustomer required | The requisitioner or buyer who placed the order. | Customer |
| buyerGroupName required | The group within the business from which the order was placed. | string |
| businessOrderInfo required | Additional information provided at checkout. | < string, string > map |
| orderSubTotal required | The principal amount on the order. This only includes the price and excludes shipping, taxes, or discounts. | Money |
| orderShippingAndHandling required | The total shipping charges on the order. This excludes shipment tax and discounts. | Money |
| orderPromotion required | The total discount on the order. This includes discounts on items and shipping. We don't show shipping discounts separately for each individual order. | Money |
| orderTax required | The total taxes for the order. | Money |
| orderNetTotal required | The total amount charged for the order. | Money |
| lineItems optional | The items in the order. | < LineItem > array |
| shipments optional | The shipments in the order. | < Shipment > array |
| charges optional | The charges for the order. | < Charge > array |
Charge
The charged amount and the payment details for the order.
| Name | Description | Schema |
|---|---|---|
| transactionDate required | The date when the payment was processed. | string (date-time) |
| transactionId required | The transaction reference identifier for the transaction. | string |
| amount required | The amount charged for a particular transaction. This is the amount for which Amazon received an authorization if the transaction isn’t settled yet. | Money |
| paymentInstrumentType required | Credit card, Pay by Invoice, Bank Account, Reward Account. | string |
| paymentInstrumentLast4Digits required | The last 4 digits of the payment card used in the transaction. If Pay by Invoice was used, this value is null. | string |
Customer
A customer with a role in a purchase such as buyer, payer, or approver.
| Name | Description | Schema |
|---|---|---|
| id required | The unique customer identifier internal to Amazon. This is currently in testing | string |
| name optional | The customer's name. | string |
| email optional | The customer's email address. | string |
OrdersOutput
A paginated list of orders
| Name | Description | Schema |
|---|---|---|
| orders required | The orders for the orderId or given date range. | < Order > array |
| nextPageToken required | A page token returned in the response to your previous request when the number of results exceed the page size (100). To get the next page of results, include nextPageToken as the only parameter. There are no more pages to return when the response returns no nextPageToken. This token needs to be encoded. | string |
| size required | The quantity of orders returned in the current response. | integer |
LineItem
A line item in an order.
| Name | Description | Schema |
|---|---|---|
| productCategory required | The Amazon Business category for the product. | string |
| asin required | The Amazon Standard Identification Number (ASIN) for the product. | string |
| title required | The title of the product. | string |
| unspsc required | The United Nations Standard Products and Services Code for the product. | string |
| productCondition required | The condition of the product purchased such as new, used, or used good. | string |
| listedPricePerUnit required | The listed price for each unit. | Money |
| purchasedPricePerUnit required | The price for each purchased unit. | Money |
| itemQuantity required | The number of purchased item. | integer |
| itemSubTotal required | The base amount paid for an item. This excludes shipping and handling, tax, promotions, and discounts. | Money |
| itemShippingAndHandling required | The base amount paid for shipping and handling an item. This excludes tax and discount amounts. | Money |
| itemPromotion required | The total discounts and promotions applied to an item. This includes all discount components such as discount on price, shipping, gift wrapping, or other fees. This excludes tax. | Money |
| itemTax required | The tax charged for an item. | Money |
| itemNetTotal required | The total amount charged for an item. This includes shipping and handling, tax, discounts, and item price. | Money |
| purchaseOrderLineItem required | Applicable only to customers who are using Punchout. | string |
| taxExemptionApplied required | Indicates if tax exemption was applied. | boolean |
| taxExemptionType required | Specifies the type of tax exemption applied. | string |
| taxExemptOptOut required | Indicates if tax exemption was opted out. | boolean |
| discountProgram required | Negotiated Pricing or Quantity Discounts | string |
| discountType required | The type of discount applied. | string |
| discountAmount required | The discounted amount in currency. | Money |
| discountRatio required | The percentage discount. | string |
| seller required | The information about the selling merchant including name, city, state, and postal code. | Seller |
| sellerCredentials required | The seller's credentials or certifications such as minority-owned business or veteran-owned business. | < string > array |
| sellerCredentialDetails required | The information about seller's credentials or certifications including certificate issuing agency name and certificate expiration. | < SellerCredentialDetails > array |
| brandCode required | The brand code provided by the vendor or seller. | string |
| brandName required | The brand provided by the vendor or seller. | string |
| manufacturerName required | The name of the manufacturer provided by the vendor or seller. | string |
| transactionIds required | The transaction reference identifiers. | < string > array |
| carrierTrackingNumbers required | The tracking numbers from the shipment carrier. | < string > array |
Seller
The information about the selling merchant including name, city, state, and postal code.
| Name | Description | Schema |
|---|---|---|
| sellerName required | The name of the selling merchant. | string |
| sellerPrimaryAddress optional | The primary physical address of a seller. | SellerAddress |
| sellerCity optional | [DEPRECATED: Please use city in sellerPrimaryAddress instead] The city of the selling merchant. | string |
| sellerState optional | [DEPRECATED: Please use state in sellerPrimaryAddress instead] The state of the selling merchant. | string |
| sellerPostalCode optional | [DEPRECATED: Please use postalCode in sellerPrimaryAddress instead] The postal code of the selling merchant. | string |
SellerAddress
A detailed physical address.
| Name | Description | Schema |
|---|---|---|
| addressLine1 required | The primary address of the seller with the street name, building number, city, state, and postal code. | string |
| addressLine2 required | The secondary address of the seller which can contain apartment, suite, room, or floor numbers. | string |
| city required | The city of the selling merchant. | string |
| state required | The state of the selling merchant. | string |
| postalCode required | The postal code of the selling merchant. | string |
| countryCode required | The country code of the selling merchant. | string |
SellerCredentialDetails
A list of a seller's credentials or certifications, including the certificate-issuing agency name and certificate expiration date. For a complete list of supported certificates, see Reporting API certificate types.
| Name | Description | Schema |
|---|---|---|
| certificateType required | The name of the credential or certificate. | string |
| certifyingAgenciesDetails optional | Details of issuing agency and expiration date of certificate. | < SellerCertifyingAgenciesDetails > array |
SellerCertifyingAgenciesDetails
Details of issuing agency and expiration date of certificate.
| Name | Description | Schema |
|---|---|---|
| certifyingAgencyName optional | The name of the agency that issued the certificate. | string |
| certificateExpirationDate optional | The expiration date of certificate. | String (date-time) |
Shipment
The shipment sent to the customer.
| Name | Description | Schema |
|---|---|---|
| shipmentDate required | Date when the item was shipped. | string (date-time) |
| shipmentStatus required | The current status of the shipment. | enum (ShipmentStatus) |
| carrierTracking required | The tracking number from the shipment carrier. | string |
| deliveryInformation required | The delivery status and estimated delivery date. | DeliveryInformation |
| shipmentQuantity required | The total number of items for shipping. | integer |
| shipmentSubTotal required | The cost of shipment excluding shipping, taxes, and discounts. | Money |
| shipmentShippingAndHandling required | The shipping and handling charges for the shipment. | Money |
| shipmentPromotion required | The discounts for the shipment. | Money |
| shipmentTax required | The tax amount for the shipment. | Money |
| shipmentNetTotal required | The total amount charged for the shipment. | Money |
| carrierName required | The name of the shipment carrier. | string |
| shippingAddress optional | The primary physical shipping address. | Address |
DeliveryInformation
The delivery status and estimated delivery date.
| Name | Description | Schema |
|---|---|---|
| expectedDeliveryDate required | The expected delivery date of the shipment. | string (date-time) |
| deliveryStatus required | The current delivery status of the shipment. | enum (DeliveryStatus) |
Address
A detailed physical address.
| Name | Description | Schema |
|---|---|---|
| addressLine1 required | The primary address with the street name, building number, city, state, and postal code. | string |
| addressLine2 required | The secondary address which can contain apartment, suite, room, or floor numbers. | string |
| city required | The city of the address. | string |
| state required | The state of the address. | string |
| postalCode required | The postal code of the address. | string |
| countryCode required | The country code of the address. | string |
ErrorList
A list of error responses returned when a request is unsuccessful.
| Name | Schema |
|---|---|
| errors required | < Error > array |
Error
The error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
OrderStatus
The status of the order.
Type : enum
| Value | Description |
|---|---|
| Pending Approval | The order has been submitted for approval. |
| Payment Confirmed | The payment information has been collected by Amazon Business. This doesn't mean that payment has been authorized by the bank or that Amazon Business have the collected funds. |
| Pending Fulfillment | The order is due for fulfillment. |
| Pending | The order details are being processed by Amazon Business. |
| Cancelled | The order has been cancelled either by the buyer or by Amazon Business. |
| Closed | The order has been delivered to the buyer and closed. |
ShipmentStatus
The current status of the shipment.
Type : enum
| Value | Description |
|---|---|
| Shipped | The package has been shipped. |
DeliveryStatus
The current delivery status of the shipment.
Type : enum
| Value | Description |
|---|---|
| DELIVERED | The package has been delivered. |
| NOT DELIVERED | The package hasn't been delivered. |
| NOT AVAILABLE | The package has no delivery information. |
Updated 2 months ago
Did this page help you?