Change the State of an Order Delivery in the Sandbox

📘
Important
The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.

In the sandbox environment, you call the mutation updateOrderDeliveryInformation to move a package through various states to publish events without making real-world changes. For example, you can test how your application handles a PACKAGE_DELIVERED event without actually delivering a package by setting the package state to DELIVERED.

You can use updateOrderDeliveryInformation to update both DeliveryInformationDetails and PackageTracker. When a PackageTracker state associated changes to a terminal state such DELIVERED, then the DeliveryInformationDetails state is also updated to DELIVERED.

updateOrderDeliveryInformation is asynchronous, so the response contains the current order. You must wait for the state change to happen, and then you can query the order for the updated details.

Reference: `updateOrderDeliveryInformation`

In the sandbox environment, you can make the following state transitions to packages by calling updateOrderDeliveryInformation with DeliveryInformationStateInput.

`DeliveryInformationDetails` current state	Next state	Expected events	Expected wait
`PENDING`	`CANCELLED`, reason `UNFULFILLABLE` or `CUSTOMER_REQUESTED`	`DELIVERY_CANCELLED`, `REFUND_REQUESTED`	8 minutes
`PENDING`	`IN_TRANSIT`	`DELIVERY_IN_TRANSIT`	8 minutes
`IN_TRANSIT`	`CANCELLED`, reason `UNDELIVERABLE`	`DELIVERY_CANCELLED`, `REFUND_REQUESTED`	2 minutes
`IN_TRANSIT`	`DELIVERED`	`DELIVERY_COMPLETED`	2 minutes
`CANCELLED`, `DELIVERED`	None, this is a terminal state.	N/A	N/A

Query the order

Use the following query to get relevant DeliveryInformationDetails from an order.

Request

query order($orderIdentifier: OrderIdentifierInput!) {
  order(orderIdentifier: $orderIdentifier) {
    id
    lineItems {
      id
      deliveryInformation {
        details {
          id
          state
          reason
          deliveryInformationDetailsFor {
            orderLineItems {
              amount {
                unit
                value
              }
              lineItem {
                id
              }
            }
          }
          trackingDetails {
            carrierCode
            trackingId
          }
        }
      }
    }
  }
}

//Query variables
{
    "orderIdentifier": {
        "orderId": "example-order-id"
    }
}

Prerequisites for updating order package information

The order needs to be placed and fulfilled before you can begin. Do the following:

Set up inventory in the sandbox with the help of your Buy with Prime solutions architect.
Create a Buy with Prime Order.
Trigger fulfillment by doing one of the following:
- In the createOrder call, set desiredExecutionState to STARTED.
- Trigger fulfillment for an existing order.

Examples

Update all items to be `IN_TRANSIT` in a single package

Events published: DELIVERY_IN_TRANSIT

After an order is created with the desiredExecutionState set to STARTED, you can Query the order to get the id from the DeliveryInformationDetails. Then you can use the following request to update all the items in the package as IN_TRANSIT.

Request

mutation updateOrderDeliveryInformation(
  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "details": [
      {
        "deliveryInformationState": {
          "state": "IN_TRANSIT"
        },
        "id": "example-delivery-information-details-id"
      }
    ],
    "orderId": "example-order-id"
  }
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected event, Query the order to view the updated details.

Query response

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id",
                "state": "IN_TRANSIT",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Update all items to be `IN_TRANSIT` in multiple packages

Events published: DELIVERY_IN_TRANSIT

After an order is created with the desiredExecutionState set to STARTED, you can Query the order to get the id from the DeliveryInformationDetails and lineItems[].

In this example, there are two line items that have one unit each. Initially, the line items are in the same package, so there is one package with ID example-package-information-id. The example shows how to use the ID in UpdatePackageInformationDetailsInputs to separate them into two packages.

Request

mutation updateOrderDeliveryInformation(
  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "orderId": "example-order-id",
    "details": [
      {
        "id": "example-delivery-information-details-id",
        "deliveryInformationState": {
          "state": "IN_TRANSIT"
        },
        "deliveryInformationDetailsFor": {
          "orderLineItems": [
            {
              "amount": {
                "unit": "ONE",
                "value": 1
              },
              "lineItemId": {
                "lineItemId": "example-line-item-id-1"
              }
            }
          ]
        }
      },
      {
        "id": "example-delivery-information-details-id",
        "deliveryInformationState": {
          "state": "IN_TRANSIT"
        },
        "deliveryInformationDetailsFor": {
          "orderLineItems": [
            {
              "amount": {
                "unit": "ONE",
                "value": 1
              },
              "lineItemId": {
                "lineItemId": "example-line-item-id-2"
              }
            }
          ]
        }
      }
    ]
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected event, Query the order to view the updated details.

Query order response

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id-1",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id-1",
                "state": "IN_TRANSIT",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id-1"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              }
            ]
          }
        },
        {
          "id": "example-line-item-id-2",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id-2",
                "state": "IN_TRANSIT",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id-2"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Update all line items in the package `CANCELLED` due to `CUSTOMER_REQUEST`

Events published: DELIVERY_CANCELLED, REFUND_REQUESTED

After an order is created with the desiredExecutionState set to STARTED, you can Query the order to get the id from the DeliveryInformationDetails and lineItems[].

The following request shows how to update all items as cancelled due to a customer request.

Request

mutation updateOrderDeliveryInformation(
  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "details": [
      {
        "deliveryInformationState": {
          "reason": "CUSTOMER_REQUESTED",
          "state": "CANCELLED"
        },
        "id": "example-delivery-information-details-id"
      }
    ],
    "orderId": "example-order-id"
  }
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected event, Query the order to view the updated details.

Query order response

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id",
                "state": "CANCELLED",
                "reason": "CUSTOMER_REQUESTED",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id"
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Update partial quantities of the same line item to be `CANCELLED (UNFULFILLABLE)`, while the others as `IN_TRANSIT`

Events published: DELIVERY_IN_TRANSIT, DELIVERY_CANCELLED, REFUND_REQUESTED

After an order is created with the desiredExecutionState set to STARTED, you can Query the order to get the id from the DeliveryInformationDetails and lineItems[].

In this example, there is one line item with two units in a PENDING package. Initially, the two units are in the same package with ID example-package-information-id.

You can use the the ID in the following request to update one unit as CANCELLED with reason UNFULFILLABLE, and the other unit as IN_TRANSIT.

Request

mutation updateOrderDeliveryInformation(
  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "details": [
      {
        "id": "example-delivery-information-details-id",
        "deliveryInformationState": {
          "state": "IN_TRANSIT"
        },
        "deliveryInformationDetailsFor": {
          "orderLineItems": [
            {
              "amount": {
                "unit": "ONE",
                "value": 1
              },
              "lineItemId": {
                "lineItemId": "example-line-item-id"
              }
            }
          ]
        }
      },
      {
        "id": "example-delivery-information-details-id",
        "deliveryInformationState": {
          "state": "CANCELLED",
          "reason": "UNFULFILLABLE"
        },
        "deliveryInformationDetailsFor": {
          "orderLineItems": [
            {
              "amount": {
                "unit": "ONE",
                "value": 1
              },
              "lineItemId": {
                "lineItemId": "example-line-item-id"
              }
            }
          ]
        }
      }
    ],
    "orderId": "example-order-id"
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected event, Query the order to view the updated details.

Query order response

Use the request from Query PackageInformationDetails from the Order to query the order.

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id-1",
                "state": "IN_TRANSIT",
                "reason": null,
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              },
              {
                "id": "example-delivery-information-details-id-2",
                "state": "CANCELLED",
                "reason": "UNFULFILLABLE",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id"
                      }
                    }
                  ]
                },
                "trackingDetails": null
              }
            ]
          }
        }
      ]
    }
  }
}

Update a package as `DELIVERED`

Events published: DELIVERY_COMPLETED

The following example shows how to update a package in the IN_TRANSIT state to the DELIVERED state.

Request

mutation updateOrderDeliveryInformation(
  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "details": [
      {
        "deliveryInformationState": {
          "state": "DELIVERED"
        },
        "id": "example-delivery-information-details-id"
      }
    ],
    "orderId": "example-order-id"
  }
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected event, Query the order to view the updated details.

Query order response

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id",
                "state": "DELIVERED",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Update multiple packages as `DELIVERED`

Events published: DELIVERY_COMPLETED

The following example shows how to update two packages in the IN_TRANSIT state to the DELIVERED state.

Request

  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables

{
  "input": {
    "orderId": "example-order-id",
    "details": [
      {
        "id": "example-delivery-information-details-id",
        "deliveryInformationState": {
          "state": "DELIVERED"
        },
        "deliveryInformationDetailsFor": {
          "orderLineItems": [
            {
              "amount": {
                "unit": "ONE",
                "value": 1
              },
              "lineItemId": {
                "lineItemId": "example-line-item-id-1"
              }
            }
          ]
        }
      },
      {
        "id": "example-delivery-information-details-id",
        "deliveryInformationState": {
          "state": "DELIVERED"
        },
        "deliveryInformationDetailsFor": {
          "orderLineItems": [
            {
              "amount": {
                "unit": "ONE",
                "value": 1
              },
              "lineItemId": {
                "lineItemId": "example-line-item-id-2"
              }
            }
          ]
        }
      }
    ]
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected event, Query the order to view the updated details.

Query order response

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id-1",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id-1",
                "state": "DELIVERED",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id-1"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              }
            ]
          }
        },
        {
          "id": "example-line-item-id-2",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id-2",
                "state": "DELIVERED",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id-2"
                      }
                    }
                  ]
                },
                "trackingDetails": {
                  "carrierCode": "example-carrier-code",
                  "trackingId": "example-tracking-id"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Update a package as `CANCELLED` due to being `UNDELIVERABLE`

Events published: DELIVERY_CANCELLED, REFUND_REQUESTED

The following example shows how to update a package that is in IN_TRANSIT to be CANCELLED due to reason UNDELIVERABLE. The update applies at the package level and includes all line items.

Request

mutation updateOrderDeliveryInformation(
  $input: UpdateOrderDeliveryInformationInput!
) {
  updateOrderDeliveryInformation(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "details": [
      {
        "deliveryInformationState": {
          "reason": "UNDELIVERABLE",
          "state": "CANCELLED"
        },
        "id": "example-delivery-information-details-id"
      }
    ],
    "orderId": "example-order-id"
  }
}

Response

{
  "data": {
    "updateOrderDeliveryInformation": {
      "order": {
        "id": "example-order-id"
      }
    }
  }
}

After you see the expected events, Query the order to view the updated details.

Query order response

Use the request from Query PackageInformationDetails from the Order to query the order.

{
  "data": {
    "order": {
      "id": "example-order-id",
      "lineItems": [
        {
          "id": "example-line-item-id",
          "deliveryInformation": {
            "details": [
              {
                "id": "example-delivery-information-details-id",
                "state": "CANCELLED",
                "reason": "UNDELIVERABLE",
                "deliveryInformationDetailsFor": {
                  "orderLineItems": [
                    {
                      "amount": {
                        "unit": "ONE",
                        "value": 1
                      },
                      "lineItem": {
                        "id": "example-line-item-id"
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Updated 7 days ago

Did this page help you?

📘Important

Reference: updateOrderDeliveryInformation

Query the order

Prerequisites for updating order package information

Examples

Update all items to be IN_TRANSIT in a single package

Update all items to be IN_TRANSIT in multiple packages

Update all line items in the package CANCELLED due to CUSTOMER_REQUEST

Update partial quantities of the same line item to be CANCELLED (UNFULFILLABLE), while the others as IN_TRANSIT

Update a package as DELIVERED

Update multiple packages as DELIVERED

Update a package as CANCELLED due to being UNDELIVERABLE

📘
Important

Reference: `updateOrderDeliveryInformation`

Update all items to be `IN_TRANSIT` in a single package

Update all items to be `IN_TRANSIT` in multiple packages

Update all line items in the package `CANCELLED` due to `CUSTOMER_REQUEST`

Update partial quantities of the same line item to be `CANCELLED (UNFULFILLABLE)`, while the others as `IN_TRANSIT`

Update a package as `DELIVERED`

Update multiple packages as `DELIVERED`

Update a package as `CANCELLED` due to being `UNDELIVERABLE`