Validating an order with trial mode

Ordering API offers a trial mode that you can use to test your order requests. When you submit an Ordering API request in trial mode, Amazon Business will complete all the steps required to process an order but an actual order will not be placed. This feature allows you to test your API calls without submitting a real order. Using trial mode to validate orders increases the probability of your orders being successfully fulfilled by identifying errors before submitting a real order. Sending trial orders also allows you to retrieve accurate tax and shipping charges for the order.

📘
For instructions to submit a successful order request with Ordering API, see Placing an order.

Prerequisites

Before starting this tutorial, complete these steps:

Complete the Ordering API partner and customer onboarding process. For more information, see Getting started with Ordering API.
Gain access to the Amazon Business Order Placement role. For more information, see Amazon Business API roles.

📘
Orders placed using Amazon Business purchasing groups in “test mode” are automatically set to trial mode. Once the group is active, you can place a trial order by adding the TrialMode attribute.

Step 1. Place an Amazon Business order in trial mode

To place an order in trial mode, call the placeOrder operation. In addition to the required attributes and expectations, provide a trialMode attribute in the request:

Attribute	Description	Required at
`TrialMode`	Indicates that an order is a trial order. The steps to place an order will be completed, but no actual order will be created.	Order level

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

{
  "externalId": "external-order-id-12345",
  "lineItems": [
    {
      "externalId": "line-item-1",
      "quantity": 1,
      "attributes": [
        {
          "attributeType": "SelectedProductReference",
          "productReference": {
            "productReferenceType": "ProductIdentifier",
            "id": "[ASIN]"
          }
        }
      ],
      "expectations": [
        {
          "expectationType": "ExpectedUnitPrice",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          }
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          },
          "source": "SUBTOTAL"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 0.50
          },
          "source": "TAX"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 5.00
          },
          "source": "SHIPPING"
        }
      ]
    }
  ],
  "attributes": [
    {
      "attributeType": "PurchaseOrderNumber",
      "purchaseOrderNumber": "ExamplePurchaseOrderNumber"
    },
    {
      "attributeType": "BuyerReference",
      "userReference": {
        "userReferenceType": "UserEmail",
        "emailAddress": "[email protected]"
      }
    },
    {
      "attributeType": "BuyingGroupReference",
      "groupReference": {
        "groupReferenceType": "GroupIdentity",
        "identifier": "ExampleGroup"
      }
    },
    {
      "attributeType": "Region",
      "region": "US"
    },
    {
      "attributeType": "SelectedPaymentMethodReference",
      "paymentMethodReference": {
        "paymentMethodReferenceType": "StoredPaymentMethod"
      }
    },
    {
      "attributeType": "ShippingAddress",
      "address": {
        "addressType": "PhysicalAddress",
        "fullName": "Example User",
        "phoneNumber": "1234567890",
        "companyName": "Example Company",
        "addressLine1": "123 Example St.",
        "addressLine2": "456",
        "city": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98109",
        "countryCode": "US"
      }
    },
    {
      "attributeType": "TrialMode"
    }
  ],
  "expectations": []
}

import requests

url = "https://na.business-api.amazon.com/ordering/2022-10-30/orders"

payload = {
{
  "externalId": "external-order-id-12345",
  "lineItems": [
{
      "externalId": "line-item-1",
      "quantity": 1,
      "attributes": [
        {
          "attributeType": "SelectedProductReference",
          "productReference": {
            "productReferenceType": "ProductIdentifier",
            "id": "[ASIN]"
          }
        }
      ],
      "expectations": [
        {
          "expectationType": "ExpectedUnitPrice",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          }
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          },
          "source": "SUBTOTAL"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 0.50
          },
          "source": "TAX"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 5.00
          },
          "source": "SHIPPING"
        }
      ]
    }
  ],
  "attributes": [
    {
      "attributeType": "PurchaseOrderNumber",
      "purchaseOrderNumber": "ExamplePurchaseOrderNumber"
    },
    {
      "attributeType": "BuyerReference",
      "userReference": {
        "userReferenceType": "UserEmail",
        "emailAddress": [email protected]
      }
    },
    {
      "attributeType": "BuyingGroupReference",
      "groupReference": {
        "groupReferenceType": "GroupIdentity",
        "identifier": "ExampleGroup"
      }
    },
    {
      "attributeType": "Region",
      "region": "US"
    },
    {
      "attributeType": "SelectedPaymentMethodReference",
      "paymentMethodReference": {
      "paymentMethodReferenceType": "StoredPaymentMethod"
      }
    },
    {
      "attributeType": "ShippingAddress",
      "address": {
        "addressType": "PhysicalAddress",
        "fullName": "Example User",
        "phoneNumber": "1234567890",
        "companyName": "Example Company",
        "addressLine1": "123 Example St.",
        "addressLine2": "456",
        "city": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98109",
        "countryCode": "US"
      }
    },
    {
      "attributeType": "TrialMode"
    }
  ],
  "expectations": []
}
}

headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Just as with a live order, Ordering API processes the line items in the trial mode order to see if they can be successfully fulfilled given the attributes and expectations defined in the request. The resulting response includes the line items from the request, broken down into accepted and rejected items.

A successful request returns the following fields:

Name	Description	Schema
`lineItems`	Order results for specific line items.	< ResultLineItem > array
`acceptanceArtifacts`	Results of a successful order.	< AcceptanceArtifact > array
`rejectionArtifacts`	Reasons the order was rejected.	< RejectionArtifact > array

{
  "lineItems": [
    {
      "externalId": "external-order-id-12345",
      "acceptedItems": [
        {
          "quantity": 1,
          "artifacts": [
            {
              "acceptanceArtifactType": "DeliveryTimeRange",
              "lowerBoundary": "2023-01-01T08:00:00Z",
              "upperBoundary": "2023-01-02T07:59:59Z"
            },
            {
              "acceptanceArtifactType": "UnitPrice",
              "amount": {
                "currencyCode": "USD",
                "amount": 9.99
              }
            },
            {
              "acceptanceArtifactType": "Charge",
              "amount": {
                "currencyCode": "USD",
                "amount": 4.99
              },
              "category": "SHIPPING",
              "type": "PRINCIPAL"
            },
            {
              "acceptanceArtifactType": "Charge",
              "amount": {
                "currencyCode": "USD",
                "amount": 9.99
              },
              "category": "SUBTOTAL",
              "type": "PRINCIPAL"
            },
            {
              "acceptanceArtifactType": "OrderIdentifier",
              "identifier": "000-1111111-2222222"
            }
          ]
        }
      ],
      "rejectedItems": []
    }
  ],
  "acceptanceArtifacts": [
    {
      "acceptanceArtifactType": "Charge",
      "amount": {
        "currencyCode": "USD",
        "amount": 4.99
      },
      "category": "SHIPPING",
      "type": "PRINCIPAL"
    },
    {
      "acceptanceArtifactType": "Charge",
      "amount": {
        "currencyCode": "USD",
        "amount": 9.99
      },
      "category": "SUBTOTAL",
      "type": "PRINCIPAL"
    }
  ],
  "rejectionArtifacts": []
}

🚧
A successful response returns an order identifier. However, this is not a real order identifier, and the order will not be displayed in your Amazon Business account.

Step 2. Validate order results

Review the response of the Ordering API request you sent in Step 1 and confirm if the order is fulfilled according to your expectations.

👍
Trial mode orders do not return "acceptanceArtifactType": "Signed". You can use this field to identify whether an order is a live or trial request.

If the order could be completed as expected, you can submit a live order by removing the trialMode attribute and resending the request.
If the order is not processed as expected, modify the fields in your request based on the error message in the response. Continue sending orders in trial mode until you receive an expected result.

❗️
Sending a trial mode order does not lock the price or quantity of items in the order. If you send a trial request and later resend the same request in either trial mode or production, the response can be different. This variation is because prices and inventories can change over time. To ensure your order is successfully processed, send a live order request immediately after a successful trial call.

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.