Enabling e-Invoicing for Ordering API
After Amazon Business receives an order where the customer selected Pay By Invoice as their mode of payment, an invoice will be generated for the cost of goods for the customer to pay back. Amazon Business supports two types of invoices: PDF invoice and e-Invoice, or electronic invoice. An e-Invoice is a digital invoice sent and received electronically. When e-Invoicing is enabled for your Ordering API group, Amazon Business can generate e-Invoices for API-based orders, allowing you to simplify your end-to-end payments and reconciliation process.
e-Invoicing for Ordering API is available both for commerce eXtensible Markup Language (cXML) and Electronic Data Interchange (EDI) customers. If you are an EDIFACT customer, reach out to your Amazon Business Account executive to confirm eligibility for Ordering API e-Invoicing.
Prerequisites
Before starting this tutorial, complete these steps:
- Complete the API onboarding process to register as a developer, create an app client, and retrieve API access and refresh tokens. For more information, see Onboarding overview.
- Gain access to the Amazon Business Order Placement role. For more information, see Amazon Business API roles.
If your reconciliation system needs a cXML Advanced Ship Notification (ASN) to accept e-Invoices, suppress this setting. In Ordering API, the ASN is sent as an API response. For more information about enabling shipping notifications with ordering API, see Order information.
Step 1. Request e-Invoice enablement
If you are interested in enabling e-Invoicing for your group, reach out to your Amazon Business Account Executive for more information.
If you are already enabled for e-Invoicing via cXML ordering, skip to Step 2.
Step 2. Include e-Invoicing fields in Ordering API request
Call the placeOrder operation and include the following fields in the request:
| Name | Description | Schema | Required |
|---|---|---|---|
externalId | A customer-specified identifier that is unique for each order. | string | Yes |
lineItems | Items in the order. | < RequestLineItem > array | Yes |
attributes | Customer-determined order properties. | < Attribute > array | Yes |
expectations | Customer expectations about aspects of an order they do not directly control. | < Expectation > array | Yes |
The
externalIdfor each line item in the order must be numeric only. This value corresponds to the purchase order line number on an invoice. Sending alphanumeric line item numbers in these fields can result in e-Invoice errors. Spaces and empty strings are also considered alphanumeric.
In addition to the required fields listed above, you can include the following attributes in your Ordering API request to capture additional data that may be required for your e-Invoices:
| Name | Description |
|---|---|
Auxiliary | Additional fields used to pass data from the purchase order to the e-Invoice. This attribute contains key/value pairs that can be used to provide any additional detail you require for reconciliation, such as category and subcategory. |
Distribution | Accounting information generated by the buying organization. These details are used to divide the cost of an item among multiple parties. |
ExternalAddress | The combination of an external address ID, such as the identifier for your shipping address in your eProcurement system, and an attribute containing detailed address information. |
For full mapping between cXML and API-based ordering and e-Invoice generation, see Appendix 1.
POST https://na.business-api.amazon.com/ordering/2022-10-30/orders
{
"lineItems": [
{
"quantity": 1,
"externalId": "12345,
"attributes": [
{
"attributeType": "SelectedProductReference",
"productReference": {
"id": "B01GGKYS6E",
"productReferenceType": "ProductIdentifier"
}
},
{
"attributeType": "Auxiliary",
"values": {
"subCategory": {
"value": "GENERAL_OFFICE_SUPPLIES"
},
"category": {
"value": "OFFICE_PRODUCTS"
}
}
},
{
"charge": {
"amount": {
"amount": 109.99,
"currencyCode": "USD"
}
},
"attributeType": "Distribution",
"accounting": {
"name": "XYZ Corporation",
"segments": [
{
"description": "DeptId",
"id": "001",
"type": "DeptId"
},
{
"description": "OpUnit",
"id": "002",
"type": "OpUnit"
}
]
}
}
],
"expectations": [
{
"amount": {
"amount": 101,
"currencyCode": "USD"
},
"expectationType": "ExpectedUnitPrice"
},
{
"amount": {
"amount": 102,
"currencyCode": "USD"
},
"expectationType": "ExpectedCharge",
"source": "SUBTOTAL"
},
{
"requestedDeliveryDate": "2026-01-30T21:32:44.511301Z",
"expectationType": "ExpectedDeliveryDate"
}
]
}
],
"externalId": "",
"attributes": [
{
"attributeType": "PurchaseOrderNumber",
"purchaseOrderNumber": "US Order"
},
{
"attributeType": "BuyingGroupReference",
"groupReference": {
"identifier": "OrderingAPI1234567891",
"groupReferenceType": "GroupIdentity"
}
},
{
"attributeType": "BuyerReference",
"userReference": {
"emailAddress": "test@ amazon.com",
"userReferenceType": "UserEmail"
}
},
{
"attributeType": "Region",
"region": "US"
},
{
"address": {
"address": {
"stateOrRegion": "WA",
"phoneNumber": "",
"city": "Any Town",
"addressType": "PhysicalAddress",
"countryCode": "US",
"companyName": "AnyCompany",
"postalCode": "",
"fullName": "AnyCompany",
"addressLine1": "123 Any Street"
},
"addressType": "ExternalAddress",
"addressId": "EXTERNAL_ADDRESS_ID"
},
"attributeType": "ShippingAddress"
},
{
"address": {
"address": {
"stateOrRegion": "WA",
"phoneNumber": "",
"city": "Any Town",
"addressType": "PhysicalAddress",
"countryCode": "US",
"companyName": "AnyCompany",
"postalCode": "",
"fullName": "AnyCompany",
"addressLine1": "123 Any Street"
},
"addressType": "ExternalAddress",
"addressId": "EXTERNAL_ADDRESS_ID"
},
"attributeType": "BillingAddress"
},
{
"paymentMethodReference": {
"paymentMethodReferenceType": "StoredPaymentMethod"
},
"attributeType": "SelectedPaymentMethodReference"
}
],
"expectations": [
{
"amount": {
"amount": 103,
"currencyCode": "USD"
},
"expectationType": "ExpectedCharge",
"source": "TAX"
},
{
"amount": {
"amount": 104,
"currencyCode": "USD"
},
"expectationType": "ExpectedCharge",
"source": "SHIPPING"
},
{
"amount": {
"amount": 105,
"currencyCode": "USD"
},
"expectationType": "ExpectedCharge",
"source": "SUBTOTAL"
},
{
"requestedDeliveryDate": "2026-01-30T21:32:44.502457Z",
"expectationType": "ExpectedDeliveryDate"
}
]
}
Following a successful request, Amazon Business generates the following cXML e-Invoice and sends it to your reconciliation platform. For an example of a cXML invoice generated from the above request, see Appendix 2.
The Ordering API response includes the following details:
| Name | Description | Schema |
|---|---|---|
lineItems | Order results for specific line items. | < ResultLineItem > array |
acceptanceArtifacts | Results of a successful order. | < AcceptanceArtifact > array |
rejectionArtifacts | Reasons the order was rejected. | < RejectionArtifact > array |
{
"lineItems": [
{
"externalId": "12345",
"acceptedItems": [
{
"quantity": 1,
"artifacts": [
{
"acceptanceArtifactType": "DeliveryTimeRange",
"lowerBoundary": "2025-03-10T07:00:00Z",
"upperBoundary": "2025-03-11T06:59:59Z"
},
{
"acceptanceArtifactType": "UnitPrice",
"amount": {
"currencyCode": "USD",
"amount": 7.99
}
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 7.99
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 6.99
},
"category": "SHIPPING",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.42
},
"category": "SHIPPING",
"type": "TAX"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.48
},
"category": "SUBTOTAL",
"type": "TAX"
},
{
"acceptanceArtifactType": "OrderIdentifier",
"identifier": "113-1746647-0749053"
}
]
}
],
"rejectedItems": []
}
],
"acceptanceArtifacts": [
{
"acceptanceArtifactType": "Signed"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 7.99
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 6.99
},
"category": "SHIPPING",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.42
},
"category": "SHIPPING",
"type": "TAX"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.48
},
"category": "SUBTOTAL",
"type": "TAX"
}
],
"rejectionArtifacts": []
}
Appendices
Appendix 1: cXML and API field mapping
Review the following table to map the fields required for e-Invoice generation between cXML and API ordering.
- If you have not yet set up cXML e-Invoicing, review the “Corresponding Ordering API fields” column of the below table to identify the Ordering API fields you will need to pass in the request to enable e-Invoicing.
- If you have already set up cXML e-Invoicing, review the “cXML node” and “Corresponding Ordering API fields” columns of the below table. Accordingly, adjust your field mapping to Ordering API.
| Business Data | cXML node | Corresponding Ordering API field | Instructions for Ordering API |
|---|---|---|---|
| Request ID | First node | externalId | Provide a user-defined ID to identify the order. |
| Credentials | ./Header/*/Credential | BuyingGroupReference | Provide the ID of the Amazon Business group being used to place the order. |
| Order date | ./Request/OrderRequest./OrderRequestHeader | x-amz-date | Use the x-amz-date request header in the API request for a timestamp of the order date. |
| Purchase Order (PO) number | ./Request/OrderRequest./OrderRequestHeader | PurchaseOrderNumber | Provide the PO number associated with the order. |
| Line number | ./Request/OrderRequest/ItemOut | externalId (in requestLineItem) | Provide a user-defined ID to identify the line item. This field only accepts numeric format for e-Invoicing. |
| Category and subcategory | ./Request/OrderRequest/ItemOut./ItemDetail/Extrinsic | Auxiliary | Provide an Auxiliary attribute that contains two key/value pairs, with subCategory and category as the keys. |
| Accounting distribution | ./Request/OrderRequest/ItemOut./Distribution./Accounting | Distribution | Provide a Distribution attribute type that contains an accounting object, with the name set to the name of the entity placing the order, and an array of segments containing the relevant accounting codes for this purchase. |
| Billing and shipping addresses | ./Request/OrderRequest/ItemOut/ShipTo/Address | ShippingAddressBillingAddress | Provide the shipping and/or billing addresses associated with the order. |
| Address ID | /cXML/Request/OrderRequest/OrderRequestHeader/*/Address[@addressID] | AddressId | Provide an identifier for the shipping address in your eProcurement system. |
Appendix 2: Sample cXML e-Invoice
Here is a sample of a cXML e-Invoice that would be generated from the above API request and response samples.
For e-Invoice file specifications, see Amazon Business cXML e-Invoice specifications.
<cXML payloadID="[email protected]" timestamp="2025-03-12" xml:lang="en-US">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>AN01011737571</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkID">
<Identity>AN12345678901</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkID">
<Identity>test123identity</Identity>
<SharedSecret>test1</SharedSecret>
</Credential>
<UserAgent>Amazon eProcurement Application</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader invoiceID="1CW9RHVRKABC" purpose="standard" operation="new" invoiceDate="2025-03-12">
<InvoiceDetailHeaderIndicator/>
<InvoiceDetailLineIndicator isAccountingInLine="yes" isTaxInLine="no"/>
<InvoicePartner>
<Contact role="remitTo" addressID="123">
<Name xml:lang="en-US">Amazon Capital Services</Name>
<PostalAddress name="Amazon Capital Services">
<Street>123 Any Street</Street>
<City>Any Town</City>
<State>WA</State>
<PostalCode></PostalCode>
<Country isoCountryCode="US">US</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
<InvoicePartner>
<Contact role="billTo" addressID="A1OOV0IKUUS123">
<Name xml:lang="en-US">Any Company</Name>
<PostalAddress name="">
<Street>123 Any Street</Street>
<City>Any Town</City>
<State>WA</State>
<PostalCode></PostalCode>
<Country isoCountryCode="US">US</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
<InvoicePartner>
<Contact role="soldTo" addressID="A2GWF1USCDK1V">
<Name xml:lang="en-US">Any Company</Name>
<PostalAddress name="Any Company">
<Street>123 Any Street</Street>
<City>Any Town</City>
<State>WA</State>
<PostalCode></PostalCode>
<Country isoCountryCode="US">US</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
<InvoicePartner>
<Contact role="invoiceFrom" addressID="Default">
<Name xml:lang="en-US">Amazon Services LLC</Name>
<PostalAddress name="Amazon Services LLC">
<Street>410 Terry Avenue North</Street>
<City>Seattle</City>
<State>WA</State>
<PostalCode>98109</PostalCode>
<Country isoCountryCode="US">US</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
<InvoiceDetailShipping>
<Contact role="shipFrom" addressID="Default">
<Name xml:lang="en-US">Amazon Services LLC</Name>
<PostalAddress name="Amazon Services LLC">
<Street>410 Terry Avenue North</Street>
<City>Seattle</City>
<State>WA</State>
<PostalCode>98109</PostalCode>
<Country isoCountryCode="US">US</Country>
</PostalAddress>
</Contact>
<Contact role="shipTo" addressID="EXTERNAL_ADDRESS_ID">
<Name xml:lang="en-US">Exxon</Name>
<PostalAddress name="Any Company">
<Street>123 Any Street</Street>
<City>Any Town</City>
<State>WA</State>
<PostalCode></PostalCode>
<Country isoCountryCode="US">US</Country>
</PostalAddress>
</Contact>
</InvoiceDetailShipping>
<PaymentTerm payInNumberOfDays="net30"/>
<Extrinsic name="carrierName">Amazon Logistics</Extrinsic>
<Extrinsic name="carrierTrackingNumber">TBA319926702880</Extrinsic>
</InvoiceDetailRequestHeader>
<InvoiceDetailOrder>
<InvoiceDetailOrderInfo>
<OrderReference orderID="US Ariba Order" orderDate="2025-03-10">
<DocumentReference payloadID="264-348-7083"/>
</OrderReference>
<SupplierOrderInfo orderID="113-2968845-4452123"/>
</InvoiceDetailOrderInfo>
<InvoiceDetailItem invoiceLineNumber="1" quantity="1">
<UnitOfMeasure>EA</UnitOfMeasure>
<UnitPrice>
<Money currency="USD">7.99</Money>
</UnitPrice>
<InvoiceDetailItemReference lineNumber="li_1">
<ItemID>
<SupplierPartID>B01GGKYS6E</SupplierPartID>
</ItemID>
<Description xml:lang="en-US">
Amazon Basics USB-C to USB-A 3.1 Gen 2 Adapter Fast Charger Cable, 10Gbps High-Speed, USB-IF Certified, for Apple iPhone 16/15, iPad, Samsung Galaxy, Tablets, Laptops, 3 Foot, White
</Description>
<Classification domain="UNSPSC">43202222</Classification>
</InvoiceDetailItemReference>
<SubtotalAmount>
<Money currency="USD">7.99</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">0.90</Money>
<Description xml:lang="en-US">Cost of tax, including shipping tax</Description>
<TaxDetail purpose="tax" category="sales" percentageRate="6.01">
<TaxableAmount>
<Money currency="USD">7.99</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">0.48</Money>
</TaxAmount>
</TaxDetail>
<TaxDetail purpose="tax" category="other" percentageRate="6.01">
<TaxableAmount>
<Money currency="USD">6.99</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">0.42</Money>
</TaxAmount>
</TaxDetail>
</Tax>
<Comments/>
<Extrinsic name="soldBy">Amazon.com</Extrinsic>
<Extrinsic name="subCategory">GENERAL_OFFICE_SUPPLIES</Extrinsic>
<Extrinsic name="category">OFFICE_PRODUCTS</Extrinsic>
</InvoiceDetailItem>
</InvoiceDetailOrder>
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="USD">7.99</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">0.90</Money>
<Description xml:lang="en-US">Cost of tax, including shipping tax</Description>
<TaxDetail purpose="tax" category="sales" percentageRate="11.26">
<TaxableAmount>
<Money currency="USD">7.99</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">0.90</Money>
</TaxAmount>
</TaxDetail>
</Tax>
<SpecialHandlingAmount>
<Money currency="USD">0.00</Money>
<Description xml:lang="en-US">Other Charges</Description>
</SpecialHandlingAmount>
<ShippingAmount>
<Money currency="USD">6.99</Money>
</ShippingAmount>
<NetAmount>
<Money currency="USD">15.88</Money>
</NetAmount>
<DueAmount>
<Money currency="USD">15.88</Money>
</DueAmount>
</InvoiceDetailSummary>
</InvoiceDetailRequest>
</Request>
</cXML>
Updated about 2 months ago