Amazon Business Orders Use Case Guide

API Version: v0

What is an Amazon Business order?

An Amazon Business order is an order where the buyer is a verified business buyer. You can use the isBusinessOrder attribute in the order object to distinguish between business and non-business orders. An Amazon business order will have the isBusinessOrder attribute set to true.

The Orders API is used to retrieve orders created for the selling partner for whom the calls are being made. You can use the getOrders operation to get all the orders for the selling partner, then get all business orders by filtering with the isBusinessOrder attribute. You can use getOrderAddress to retrieve the shipping address and associated delivery preferences.

Prerequisites

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

Authorization from the selling partner for whom you are making calls. Refer to the Selling Partner API Developer Guide 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.

Tutorial : How to get all Amazon business orders

This tutorial shows you how to get all your Amazon business orders and identify them.

Prerequisites

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

Authorization from the selling partner for whom you are making calls. Refer to the Selling Partner API Developer Guide 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.

Fetch orders for a selling partner and identify Amazon business orders

Request

Call the getOrders operation, passing the parameters you want to filter the result. This is a paginated API. Please use the NextToken attribute in subsequent calls to get the next batch of orders.

Request example

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER&CreatedAfter=2022-12-25

Response

A successful response includes a payload object, which contains an Orders array of one or more orders, and optionally additional properties. Refer to OrderList for information about the additional properties. An Amazon business order will have the isBusinessOrder attribute set to true.

Refer to Order in the API reference for details about the possible objects and properties in an order.

Response example

{
  "payload": {
    "Orders": [
      {
        "BuyerInfo": {},
        "AmazonOrderId": "902-5663548-0163068",
        "EarliestShipDate": "2023-01-02T08:00:00Z",
        "SalesChannel": "Amazon.com",
        "AutomatedShippingSettings": {
          "HasAutomatedShippingSettings": false
        },
        "OrderStatus": "Pending",
        "NumberOfItemsShipped": 0,
        "OrderType": "StandardOrder",
        "IsPremiumOrder": false,
        "IsPrime": false,
        "FulfillmentChannel": "MFN",
        "NumberOfItemsUnshipped": 1,
        "HasRegulatedItems": false,
        "IsReplacementOrder": "false",
        "IsSoldByAB": false,
        "LatestShipDate": "2023-01-03T07:59:59Z",
        "ShipServiceLevel": "Std US D2D Dom",
        "IsISPU": false,
        "MarketplaceId": "ATVPDKIKX0DER",
        "PurchaseDate": "2022-12-30T20:01:07Z",
        "IsAccessPointOrder": false,
        "IsBusinessOrder": true,
        "PaymentMethodDetails": [
          "Standard"
        ],
        "IsGlobalExpressEnabled": false,
        "LastUpdateDate": "2023-01-04T19:57:49Z",
        "ShipmentServiceLevelCategory": "Standard"
      },
      {
        "BuyerInfo": {},
        "AmazonOrderId": "902-3282686-9052650",
        "EarliestShipDate": "2022-10-14T07:00:00Z",
        "SalesChannel": "Amazon.com",
        "AutomatedShippingSettings": {
          "HasAutomatedShippingSettings": false
        },
        "OrderStatus": "Canceled",
        "NumberOfItemsShipped": 0,
        "OrderType": "StandardOrder",
        "IsPremiumOrder": false,
        "IsPrime": false,
        "FulfillmentChannel": "MFN",
        "NumberOfItemsUnshipped": 0,
        "HasRegulatedItems": false,
        "IsReplacementOrder": "false",
        "IsSoldByAB": false,
        "LatestShipDate": "2022-10-15T06:59:59Z",
        "ShipServiceLevel": "Std US D2D Dom",
        "IsISPU": false,
        "MarketplaceId": "ATVPDKIKX0DER",
        "PurchaseDate": "2022-10-13T08:53:57Z",
        "IsAccessPointOrder": false,
        "IsBusinessOrder": false,
        "OrderTotal": {
          "CurrencyCode": "USD",
          "Amount": "12.13"
        },
        "PaymentMethodDetails": [
          "Standard"
        ],
        "IsGlobalExpressEnabled": false,
        "LastUpdateDate": "2022-10-25T07:31:21Z",
        "ShipmentServiceLevelCategory": "Standard"
      }
    ],
    "NextToken": "9A+grgyHbZ6aJqJYLDm0ZAmQazDrhw3CjfZLM4uXhchUojdU4H46tsNI3HOI22PIxqXyQLkGMBs8VhF73Xgy+yXWMVizzhiaOZR31XSS2A6ihtsveF3jYQF2C+OrWLWlInTAy+XKVmRZBY+oaVuycxWu4fsY7GTeCx7ShGY9OykghJ+2Ki9vXqfQmOEx4uZaf2GLmUGyr9UGnxD0RJmrryegoU0IPZxXhi1SP6zE/wLAVWPoD6wzg73j3O8ab4IoMBO/reDY2s8hGWNNu3VwFU0hrIUQcumU7YYXwRo+g8JiIXlRXylzxduZ3sLNMwtcdxoH3Y2nWfyVkzb2pTkxaavNDfG6UytaVlcQwn/OKRi5RanugZwxmUYrj/A7uEu6kY1qVoni2ChKw4h6m/JgREdtrcnli9iATruOKKI89oh4YcsIg8cwXw==",
    "CreatedBefore": "2023-01-20T19:47:27Z"
  }
}

In this example, the first order in the Orders array has isBusinesssOrder set to true, and the second order in the Orders array has the attribute set to false.

Tutorial: How to get order details for an Amazon business order

This tutorial shows you how to get order details for a specific order.

Prerequisites

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

Authorization from the selling partner for whom you are making calls. Refer to the Selling Partner API Developer Guide 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.
A Restricted Data Token (RDT) that authorizes you to call the getOrder operation, which return restricted data.

Get order details for an order ID

Call the getOrder operation with an order ID to get all the order details associated with an order.

Request

Call the getOrder operation, passing the following query parameter:

Parameter	Description	Required
`orderId`	An Amazon-defined order identifier, in 3-7-7 format. Type: string	Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/903-5843655-6160617

Response

A successful response includes the payload object, which contains the information for an order. The payload includes an IsBusinessOrder Boolean property. When true, the order is a business order. Otherwise, the attribute is set to false.

Refer to Order in the API reference for details about the possible objects and properties in an order.

Response example

{
  "payload": {
    "BuyerInfo": {
    "PurchaseOrderNumber": "R17435-5638"
    },
    "AmazonOrderId": "903-5843655-6160617",
    "EarliestDeliveryDate": "2023-01-25T08:00:00Z",
    "EarliestShipDate": "2023-01-23T08:00:00Z",
    "SalesChannel": "Amazon.com",
    "AutomatedShippingSettings": {
      "HasAutomatedShippingSettings": false
    },
    "OrderStatus": "Unshipped",
    "NumberOfItemsShipped": 0,
    "OrderType": "StandardOrder",
    "IsPremiumOrder": false,
    "IsPrime": false,
    "FulfillmentChannel": "MFN",
    "NumberOfItemsUnshipped": 4,
    "HasRegulatedItems": false,
    "IsReplacementOrder": false,
    "IsSoldByAB": false,
    "LatestShipDate": "2023-01-24T07:59:59Z",
    "ShipServiceLevel": "Std US D2D Dom",
    "DefaultShipFromLocationAddress": {
      "StateOrRegion": "WA",
      "AddressLine1": "123 Any Street",
      "PostalCode": "98109-4304",
      "City": "Any Town",
      "CountryCode": "US",
      "Name": "Domestic"
    },
    "IsISPU": false,
    "MarketplaceId": "ATVPDKIKX0DER",
    "LatestDeliveryDate": "2023-01-27T07:59:59Z",
    "PurchaseDate": "2023-01-21T01:16:38Z",
    "ShippingAddress": {
      "AddressLine1": "100 Main Street",
      "AddressType": "Commercial",
      "StateOrRegion": "WA",
      "PostalCode": "98109",
      "City": "Any Town",
      "CountryCode": "US",
      "CompanyName": "Company Name",
      "Name": "Business",
      "Phone": "+1 480-386-0930 ext. 29298"
    },
    "IsAccessPointOrder": false,
    "PaymentMethod": "Other",
    "IsBusinessOrder": true,
    "OrderTotal": {
      "CurrencyCode": "USD",
      "Amount": "44.04"
    },
    "PaymentMethodDetails": [
      "Standard"
    ],
    "IsGlobalExpressEnabled": false,
    "LastUpdateDate": "2023-01-21T01:48:13Z",
    "ShipmentServiceLevelCategory": "Standard"
  }
}

Tutorial: Get delivery preferences for an Amazon business order

This tutorial shows you how to get delivery preferences for Amazon business orders.

Step 1. Get the order IDs for Amazon business orders

In order to get delivery preferences for an order, we need the order ID. Order IDs can be fetched from the GetOrders API as described in the Tutorial: How to get all Amazon business orders. Any order ID returned with isBusinessOrder = true is an Amazon business order.

Step 2. Get order address details for an Amazon business order

The delivery preferences are associated with the shipping address. Call the getOrderAddress operation with an order ID to get all delivery preferences specified by the user for the shipping address. If no delivery preferences are specified by the customer for the address, the default business hours for the region are returned. Make sure of the following:

The order ID belongs to an Amazon business order
The order was created after 02/08/2023

Request

Call the getOrderAddress operation, passing the following query parameter:

Parameter	Description	Required
`orderId`	An Amazon-defined order identifier, in 3-7-7 format. Type: string	Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/903-5843655-6160617/address

Response

A successful response includes a payload object with all parameters from the OrderAddress object in the API doc. Please note that the ShippingAddress is not returned for pending and cancelled orders today, and DeliveryPreferences are only available for Amazon business orders.

Response example

{
  "payload": {
    "DeliveryPreferences": {
      "AddressInstructions": "\"//Additional info Business- delivery at south gate reception\"",
      "PreferredDeliveryTime": {
        "ExceptionDates": [],
        "BusinessHours": [
          {
            "DayOfWeek": "THU",
            "OpenIntervals": [
              {
                "EndTime": {
                  "Minute": 0,
                  "Hour": 15
                },
                "StartTime": {
                  "Minute": 0,
                  "Hour": 7
                }
              }
            ]
          },
          {
            "DayOfWeek": "TUE",
            "OpenIntervals": [
              {
                "EndTime": {
                  "Minute": 0,
                  "Hour": 16
                },
                "StartTime": {
                  "Minute": 0,
                  "Hour": 8
                }
              }
            ]
          },
          {
            "DayOfWeek": "WED",
            "OpenIntervals": [
              {
                "EndTime": {
                  "Minute": 30,
                  "Hour": 15
                },
                "StartTime": {
                  "Minute": 30,
                  "Hour": 9
                }
              }
            ]
          },
          {
            "DayOfWeek": "FRI",
            "OpenIntervals": [
              {
                "EndTime": {
                  "Minute": 0,
                  "Hour": 17
                },
                "StartTime": {
                  "Minute": 0,
                  "Hour": 9
                }
              }
            ]
          }
        ]
      },
      "OtherAttributes": [
        "PALLET_ENABLED"
      ],
      "DropOffLocation": "PROPERTYSTAFF_MAILROOM"
    },
    "AmazonOrderId": "903-5843655-6160617",
    "ShippingAddress": {
      "AddressLine1": "123 Any Street,",
      "AddressType": "Commercial",
      "StateOrRegion": "WA",
      "PostalCode": "98109",
      "City": "Any Town",
      "CountryCode": "US",
      "CompanyName": "Company Name", 
      "Name": "Business",
      "Phone": "+1 480-386-0930 ext. 29298"
    },
    "BuyerCompanyName": "AB Devo Organization"
  }
}