Setting delivery preferences

The Ordering API lets you specify your customer's preferred shipping option at the order level when placing orders through the Amazon Business API. By including the DeliveryPreference attribute in your order request, you can indicate whether your customer prefers the fastest free shipping, consolidated shipments, or expedited paid delivery.

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.

Prepare your order request with delivery preference

To specify your customer's shipping preference, include the DeliveryPreference attribute in the attributes array of your order request at the order level alongside other order attributes.

❗️

For more information on setting up an Ordering API request, see Order information.

Each shipPreference values corresponds to the following Ordering API selection logic. For more information on how Ordering API selects delivery preferences, see the Appendix.

POST https://na.business-api.amazon.com/ordering/2022-10-30/orders

{
  "externalId": "ORDER-12345",
  "attributes": [
    {
      "attributeType": "DeliveryPreference",
      "shipPreference": "FAST_FREE"
    },
    {
      "attributeType": "Region",
      "region": "EU"
    }
  ],
  "expectations": [],
  "lineItems": [
    {
      "externalId": "1",
      "quantity": 2,
      "attributes": [
        {
          "attributeType": "SelectedProductReference",
          "productReference": {
            "productReferenceType": "ProductIdentifier",
            "id": "B08N5WRWNW"
          }
        }
      ],
      "expectations": []
    }
  ]
}

After a successful request, the Ordering API uses the shipPreference value to select a shipping option for the order. If the preferred shipping option is unavailable, the Ordering API selects the next best available option.

{
  "lineItems": [
    {
      "externalId": "1",
      "acceptedItems": [
        {
          "acceptedItemType": "SingleAcceptedItem",
          "quantity": 2,
          "artifacts": [
            {
              "acceptanceArtifactType": "LineItemIdentifier",
              "identifier": "12345678901234"
            },
            {
              "acceptanceArtifactType": "DeliveryTimeRange",
              "lowerBoundary": {
                "date": "2024-12-08T00:00:00.000Z"
              },
              "upperBoundary": {
                "date": "2024-12-10T00:00:00.000Z"
              }
            }
          ]
        }
      ],
      "rejectedItems": []
    }
  ],
  "acceptanceArtifacts": [
    {
      "acceptanceArtifactType": "OrderIdentifier",
      "identifier": "112-1234567-1234567"
    },
    {
      "acceptanceArtifactType": "Signed"
    }
  ],
  "rejectionArtifacts": []
}

Error handling

If your request is not successful, the API returns an errors object that provides information about what went wrong. For more information, see Error responses and schemas.

If the API input is valid but the order cannot be fulfilled due to service issues or business logic reasons, then the API returns an HTTP 200 status code with a rejection code in the API response body. For more information, see Ordering API rejection codes.

Appendix: Delivery preference logic

Each delivery preference option applies different logic when the Ordering API selects from available shipping options.

FAST_FREE

When you set shipPreference to FAST_FREE, the Ordering API applies the following logic:

1. Filters for free shipping options only.
2. Picks the fastest option from the remaining list.
3. Sorts alphabetically when multiple options share the same speed.

For example, consider an order with the following shipping options:

Filter by cost: The Ordering API removes paid options:

Filter by speed: The Ordering API picks the fastest options from the remaining list:

Filter by name: The Ordering API sorts alphabetically and selects the first option:

❗️

The selected option is Option F.

EXPEDITED_PAID

When you set shippreference to EXPEDITED_PAID, the Ordering API applies the following logic:

1. Picks the fastest shipping options regardless of cost.
2. Chooses the cheapest option from the remaining list.
3. Sorts alphabetically when multiple options share the same speed and cost.

For example, consider an order with the following shipping options:

Filter by speed: The Ordering API picks the fastest shipping options:

Filter by cost: The Ordering API chooses the cheapest options from the remaining list:

Filter by name: The Ordering API sorts alphabetically and selects the first option:

❗️

The selected option is Option E.

CONSOLIDATED

When you set shipPreference to CONSOLIDATED, the Ordering API selects the best available consolidated delivery option to group multiple items into fewer shipments.

❗️

The CONSOLIDATED preference groups multiple items into fewer shipments when possible. Delivery timelines may be extended to allow consolidation. If consolidation is not possible, the Ordering API selects the next best available shipping option.