Tutorial: Retrieve and Pass a Purchase Order Number to a Carrier

Use the Selling Partner API to retrieve and pass a purchase order number to UPS, FedEx, or USPS.

Business-to-business (B2B) orders typically include purchase order numbers on shipping labels. Shipping labels that you retrieve through Seller Central or by using the Selling Partner API automatically include the purchase order number.

If you get shipping labels from a source outside of Amazon, the shipping labels might not include the purchase order number. For these cases, you can get the purchase order number by using the Orders API or the Reports API of the Selling Partner API. You then pass the purchase order number to the carrier when you use the carrier's API.

These tutorials show how to get the purchase order number and then pass the purchase order number to UPS, FedEx, and USPS.

Tutorial: Retrieve a purchase order number by using the Orders API

The following tutorial shows how to retrieve a purchase order number by using the Orders API. For this method to work, the isBusinessOrder field of the order must be true.

Step 1. Call the `getOrder` operation

Call the getOrder operation. Include the orderId in the path.

Step 2. Check the `IsBusinessOrder` field

In the response, check if the IsBusinessOrder field is true. If the IsBusinessOrder field is false or is absent, the response doesn't include the purchase order number.

The following example shows a response payload that contains the IsBusinessOrder field set to true.

"payload": {
  "AmazonOrderId": "902-3159896-1390916",
  "PurchaseDate": "2017-01-20T19:49:35Z",
  "LastUpdateDate": "2017-01-20T19:49:35Z",
  "OrderStatus": "Pending",
  "FulfillmentChannel": "SellerFulfilled",
  "NumberOfItemsShipped": 0,
  "NumberOfItemsUnshipped": 0,
  "PaymentMethod": "Other",
  "PaymentMethodDetails": [
    "CreditCard"
  ],
  "MarketplaceId": "ATVPDKIKX0DER",
  "ShipmentServiceLevelCategory": "Standard",
  "OrderType": "StandardOrder",
  "EarliestShipDate": "2017-01-20T19:51:16Z",
  "LatestShipDate": "2017-01-25T19:49:35Z",
  "IsBusinessOrder": true,
  "IsPrime": false,
  "IsGlobalExpressEnabled": false,
  "IsPremiumOrder": false,
  "IsSoldByAB": false,
  "IsIBA": false,
  "DefaultShipFromLocationAddress": {
    "Name": "TestMerchant",
    "AddressLine1": "2201 WESTLAKE AVE",
    "City": "SEATTLE",
    "StateOrRegion": "WA",
    "PostalCode": "98121-2778",
    "CountryCode": "US",
    "Phone": "+1 234-567-8910",
    "AddressType": "Commercial"
  },
  "FulfillmentInstruction": {
    "FulfillmentSupplySourceId": "sampleSupplySourceId"
  },
  "IsISPU": false,
  "IsAccessPointOrder": false,
  "ShippingAddress": {
    "Name": "Michigan address",
    "AddressLine1": "1 Main Street",
    "City": "Canton",
    "StateOrRegion": "MI",
    "PostalCode": "48817",
    "CountryCode": "US"
  },
  "BuyerInfo": {
    "BuyerEmail": "[email protected]",
    "BuyerName": "John Doe",
    "BuyerTaxInfo": {
      "CompanyLegalName": "A Company Name"
    },
    "PurchaseOrderNumber": "1234567890123"
  },
  "AutomatedShippingSettings": {
    "HasAutomatedShippingSettings": false
  }
}

Step 3. Get the purchase order number

The purchase order number is in the PurchaseOrderNumber field in the BuyerInfo object in the response. Refer to the previous step for an example response payload.

Tutorial: Retrieve a purchase order number by using the Reports API

The following tutorial shows how to retrieve a purchase order number by using the Reports API.

Step 1. Call the `createReport` operation

Call the createReport operation. Specify one of the following report types:

GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING
GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_SHIPPING
GET_ORDER_REPORT_DATA_SHIPPING

Step 2. Check whether the report is finished

Periodically poll the Amazon SQS queue for the REPORT_PROCESSING_FINISHED event, which provides information when the report processing is CANCELLED, DONE, or FATAL. If report data is available, the event includes a value for the reportDocumentId field.

For details, refer to Verify that Report Processing is Complete.

Step 3. Get the report

Call the getReportDocument operation. Pass in the reportDocumentId value from the previous step.

A successful response includes a url that you can use to download the report. For details, refer to Retrieve a Report.

Step 4. Download the report

Download the report from the url that you found in the previous step.

Step 5. Check the `IsBusinessOrder` field

In the report, check if the IsBusinessOrder field is true. If the IsBusinessOrder field is false or is absent, the report doesn't include the purchase order number.

The following example shows a report that contains the IsBusinessOrder field set to true.

<?xml version="1.0" encoding="UTF-8"?>
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
      <MerchantIdentifier>A3912FIWOIVW91</MerchantIdentifier>
  </Header>
  <MessageType>OrderReport</MessageType>
<Message>
    <MessageID>1</MessageID>
    <OrderReport>
        <AmazonOrderID>123-4567-8910</AmazonOrderID>
        <AmazonSessionID>12-13141516-171819</AmazonSessionID>
        <OrderDate>2024-03-18T16:59:49-07:00</OrderDate>
        <OrderPostedDate>2024-03-18T16:59:49-07:00</OrderPostedDate>
        <BillingData>
            <BuyerEmailAddress>[email protected]</BuyerEmailAddress>
            <BuyerName>John Doe</BuyerName>
            <BuyerPhoneNumber>123-456-7891</BuyerPhoneNumber>
        </BillingData>
        <FulfillmentData>
            <FulfillmentMethod>Ship</FulfillmentMethod>
            <FulfillmentServiceLevel>Standard</FulfillmentServiceLevel>
            <Address>
                <Name>Denise Park</Name>
                <AddressFieldOne>1 Main Street</AddressFieldOne>
                <City>Bellevue</City>
                <StateOrRegion>WI</StateOrRegion>
                <PostalCode>53189-6553</PostalCode>
                <CountryCode>US</CountryCode>
                <PhoneNumber>+1 123-456-7891</PhoneNumber>
            </Address>
        </FulfillmentData>
        <IsBusinessOrder>true</IsBusinessOrder>
        <PurchaseOrderNumber>PO12345</PurchaseOrderNumber>
        <Item>
            <AmazonOrderItemCode>123456789</AmazonOrderItemCode>
            <SKU>12-3456-789</SKU>
            <Title>Marshmallows</Title>
            <Quantity>2</Quantity>
            <ProductTaxCode>A1_FB_CANDY17</ProductTaxCode>
            <ItemPrice>
               <Component>
                  <Type>Principal</Type>
                  <Amount currency="USD">20.90</Amount>
               </Component>
               <Component>
                  <Type>Shipping</Type>
                  <Amount currency="USD">0.00</Amount>
               </Component>
               <Component>
                  <Type>Tax</Type>
                  <Amount currency="USD">1.04</Amount>
               </Component>
               <Component>
                  <Type>ShippingTax</Type>
                  <Amount currency="USD">0.00</Amount>
               </Component>
            </ItemPrice>
            <ItemFees>
               <Fee>
                  <Type>Commission</Type>
                  <Amount currency="USD">-1.68</Amount>
               </Fee>
            </ItemFees>
            <SignatureConfirmationRecommended>false</SignatureConfirmationRecommended>
         </Item>
    </OrderReport>
</Message>

Step 6. Get the purchase order number

In the report, the purchase order number is in the PurchaseOrderNumber field. Refer to the previous step for an example response payload.

Tutorial: Pass a purchase order number to a carrier

The following tutorial shows how to pass the purchase order number to UPS, FedEx, and USPS.

UPS: Call the UPS Shipment operation. In the ReferenceNumber array, include an element with Code equal to "PO" and Value equal to the purchase order number.

There's a maximum of five package-level reference numbers allowed per shipment and only the first two reference numbers are printed on the label.
FedEx: Call the FedEx CreateShipment operation. In the requestedShipment object, in the requestedPackageLineItems.customerReferences array, include an element with customerReferenceType equal to "P_O_NUMBER" and value equal to the purchase order number. For a list of customer reference types, refer to Customer Reference Types.
USPS: Call the USPS eVS Label API. Use the CustomerRefNo field or the CustomerRefNo2 field to pass the purchase order number. Set the PrintCustomerRefNo field to true.

Updated 2 days ago