HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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 (PO) numbers on shipping labels. Shipping labels that you retrieve through Seller Central or the Selling Partner API (SP-API) automatically include the PO number.

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

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

What is an Amazon Business PO number?

An Amazon Business 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 PO number by using the Orders API

The following tutorial shows how to retrieve a PO 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:

Step 1. Call the getOrder operation

📘

Note

This is a restricted operation and requires a Restricted Data Token (RDT) for authorization. Some operations require restrictions because they contain customer PII data. These operations require passing an additional security review. For more information on RDT, refer to the Tokens API guide.

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 PO 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 PO number

The PO 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 PO number by using the Reports API

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

Step 1. Call the createReport operation

Call the createReport operation. Specify an order report type.

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

📘

Note

  • The getReportDocument operation is considered a restricted operation only when a restricted report type is specified.
  • When calling the createRestrictedDataToken operation to get an RDT for the getReportDocument operation, the specified restricted resource can contain only a specific path, not a generic path.
  • When using RDT to access the getReportDocument operation, make sure your application has the correct right roles to access the report. Refer to Roles in the Selling Partner API for roles to reports mapping.

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 PO 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 PO number

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

Tutorial: Pass a PO number to UPS

🚧

Important

The following tutorial relates to third-party API usage. Amazon does not endorse or control any of these third-party APIs. Engage with these third-party APIs at your own discretion.

The following tutorial shows you how to pass the PO 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 PO 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 PO number to FedEx

🚧

Important

The following tutorial relates to third-party API usage. Amazon does not endorse or control any of these third-party APIs. Engage with these third-party APIs at your own discretion.

The following tutorial shows you how to pass the PO 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 PO 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 PO number to USPS

🚧

Important

The following tutorial relates to third-party API usage. Amazon does not endorse or control any of these third-party APIs. Engage with these third-party APIs at your own discretion.

The following tutorial shows you how to pass the PO 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 PO 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 PO number to Auctane

🚧

Important

The following tutorial relates to third-party API usage. Amazon does not endorse or control any of these third-party APIs. Engage with these third-party APIs at your own discretion.

The following tutorial shows you how to pass the PO 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 PO 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 PO number with EasyPost

🚧

Important

The following tutorial relates to third-party API usage. Amazon does not endorse or control any of these third-party APIs. Engage with these third-party APIs at your own discretion.

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

Call the EasyPost Shipments operation

Call the EasyPost Shipments operation. Set the print_custom_1 field to the PO 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 15 days ago