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/Amazon Business) orders typically include purchase order numbers on shipping labels. Shipping labels that you retrieve through Seller Central or 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.

What is an Amazon Business purchase order number?

An Amazon Business purchase order number (PO number) is a unique identifier that a business customer assigns to the orders that they place on Amazon Business. The business customer enters the PO number at checkout.

Businesses can use the PO number for the following purposes:

Tracking and reference: The PO number allows businesses to track and reference specific orders within their own procurement systems.
Billing and accounting: The PO number helps associate purchases with the correct cost centers, departments, or projects.
Internal management: Businesses can use the PO number to enforce internal purchasing policies, manage budgets, and ensure that orders comply with internal procurement procedures.
Communication: Businesses can use the PO number in communications to Amazon Business or suppliers to reference and resolve order issues.

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.

Prerequisites

To successfully complete this tutorial, you must have the following:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
The Direct to Consumer Shipping (Restricted) role assigned to your developer profile.
The Direct to Consumer Shipping (Restricted) role selected in the App registration page for your application.

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_CONVERGED_FLAT_FILE_ACTIONABLE_ORDER_DATA
GET_FLAT_FILE_ACTIONABLE_ORDER_DATA
GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL
GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE
GET_FLAT_FILE_ORDER_REPORT_DATA
GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING
GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING
GET_FLAT_FILE_ORDER_REPORT_DATA_TAX
GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA
GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_INVOICING
GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_SHIPPING
GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_TAX
GET_ORDER_REPORT_DATA
GET_ORDER_REPORT_DATA_ALL
GET_ORDER_REPORT_DATA_INVOICING
GET_ORDER_REPORT_DATA_SHIPPING
GET_ORDER_REPORT_DATA_TAX
GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE
GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE_ALL
GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL
GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE
GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL

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 UPS

The following tutorial shows you how to pass the purchase order number to UPS with the UPS Shipment operation.

Call the UPS `Shipment` operation

Call the UPS Shipment operation. In the ReferenceNumber array, set Code to PO and Value 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.

The following request example contains the payload for the Shipment operation:

{
  "ShipmentRequest": {
    "Shipment": {
      "Package": [
        {
          "ReferenceNumber": [
            {
              "Code": "PO",
              "Value": "CustomerPONum"
            }
          ]
        }
      ],
    }
  }
}

For more information, refer to the following:

Tutorial: Pass a purchase order number to FedEx

The following tutorial shows you how to pass the purchase order number to FedEx with the FedEx CreateShipment operation.

Call the FedEx `CreateShipment` operation

Call the FedEx CreateShipment operation. In the requestedShipment object, in the requestedPackageLineItems.customerReferences element, set customerReferenceType to P_O_NUMBER and value to the purchase order number. For a list of customer reference types, refer to Customer Reference Types.

The following request example contains the payload for the CreateShipment operation:

{
  "mergeLabelDocOption": "LABELS_AND_DOCS",
  "labelResponseOptions": "LABEL",
  "requestedShipment": {
    "shipDatestamp": "2019-10-14",
    "totalDeclaredValue": {},
    "shipper": {},
    "soldTo": {},
    "recipients": [],
    "recipientLocationNumber": "1234567",
    "pickupType": "USE_SCHEDULED_PICKUP",
    "serviceType": "PRIORITY_OVERNIGHT",
    "packagingType": "YOUR_PACKAGING",
    "totalWeight": 20.6,
    "origin": {},
    "shippingChargesPayment": {},
    "shipmentSpecialServices": {},
    "emailNotificationDetail": {},
    "expressFreightDetail": {},
    "variableHandlingChargeDetail": {},
    "customsClearanceDetail": {},
    "smartPostInfoDetail": {},
    "blockInsightVisibility": true,
    "labelSpecification": {},
    "shippingDocumentSpecification": {},
    "rateRequestType": [],
    "preferredCurrency": "USD",
    "totalPackageCount": 25,
    "masterTrackingId": {},
    "requestedPackageLineItems": [
      {
        "sequenceNumber": "1",
        "subPackagingType": "BUCKET",
        "customerReferences": [
          {
            "customerReferenceType": "P_O_NUMBER",
            "value": "23456764"
          }
        ]
      }
    ]
  }
}

For more information, refer to the following:

Tutorial: Pass a purchase order number to USPS

The following tutorial shows you how to pass the purchase order number to USPS with the USPS eVS Label API.

Call the USPS `eVS Label` API

Call the USPS eVS Label API. Set the CustomerRefNo field or the CustomerRefNo2 field to the purchase order number. To print the PO number on the label, set the PrintCustomerRefNo field to true.

The following request example uses the CustomerRefNo and PrintCustomerRefNo fields:

 <eVSRequest USERID="XXXXXX" PASSWORD="XXXXXX">
    <CustomerRefNo>PO: CustomerPONum</CustomerRefNo>
    <PrintCustomerRefNo>true</PrintCustomerRefNo>
</eVSRequest>

For more information, refer to the USPS eVS Label Documentation.

Tutorial: Pass a purchase order number to Auctane

The following tutorial shows you how to pass the purchase order number to Auctane with the Stamps.com CreateIndicium operation.

Call the Stamps.com `CreateIndicium` operation

Call the Stamps.com CreateIndicium operation. Set the memo field to the purchase order number.

<CreateIndicium xmlns="http://stamps.com/xml/namespace/2023/07/swsim/SwsimV135">
<memo>PO: CustomerPONum</memo>
</CreateIndicium>

For more information, refer to the Stamps.com CreateIndicium Documentation.

Tutorial: Pass a purchase order number with EasyPost

The following tutorial shows you how to pass the purchase order number with the EasyPost Shipments operation.

Call the EasyPost `Shipments` operation

Call the EasyPost Shipments operation. Set the print_custom_1 field to the purchase order number. Set the print_custom_1_code field to the value PO.

"options": { 
  "print_custom_1": "Custom label message",
  "print_custom_1_code": "PO"
  }

For more information, refer to the EasyPost Create a Shipment Documentation.

Updated 4 days ago