Change the State of an Outbound Package 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 updateOrderPackageInformation 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 updateOrderPackageInformation to update both PackageInformationDetails and PackageTracker. When a PackageTracker state associated changes to a terminal state such DELIVERED, then the PackageInformationDetails state is also updated to DELIVERED.
updateOrderPackageInformationmutation 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: updateOrderPackageInformation
updateOrderPackageInformationIn the sandbox environment, you can make the following state transitions to packages by calling updateOrderPackageInformation with PackageInformationDetails.
PackageInformationDetailscurrent state | Next state | Expected events | Expected wait |
|---|---|---|---|
PENDING | CANCELLED, reason UNFULFILLABLE or CUSTOMER_REQUESTED | PACKAGE_DELIVERY_CANCELLED,REFUND_REQUESTED | 8 minutes |
PENDING | IN_TRANSIT | PACKAGE_DELIVERY_IN_TRANSIT | 8 minutes |
IN_TRANSIT | CANCELLED, reason UNDELIVERABLE | PACKAGE_DELIVERY_CANCELLED,REFUND_REQUESTED | 2 minutes |
IN_TRANSIT | DELIVERED | PACKAGE_DELIVERED, | 2 minutes |
CANCELLED,DELIVERED | None, this is a terminal state. | N/A | N/A |
In the sandbox environment, you can make the following state transitions to packages by calling updateOrderPackageInformation with PackageTracker. When you change the PackageTracker state, the PackageInformationDetails state is also updated.
PackageTrackercurrent state | Next state | Expected events | Expected wait | PackageInformationDetails |
|---|---|---|---|---|
PENDING | INFO_RECEIVED,IN_TRANSIT,DELAYED,OUT_FOR_DELIVERY,AVAILABLE_FOR_PICKUP,DELIVERY_ATTEMPTED,CUSTOMER_ACTION,UNDELIVERABLE,EXCEPTION | 2 minutes | IN_TRANSIT | |
INFO_RECEIVED,IN_TRANSIT,DELAYED,OUT_FOR_DELIVERY,AVAILABLE_FOR_PICKUP,DELIVERY_ATTEMPTED,CUSTOMER_ACTION,UNDELIVERABLE,EXCEPTION | Any other state in the current column. | 2 minutes | IN_TRANSIT | |
PENDING,INFO_RECEIVED,IN_TRANSIT,DELAYED,OUT_FOR_DELIVERY,AVAILABLE_FOR_PICKUP,DELIVERY_ATTEMPTED,CUSTOMER_ACTION,UNDELIVERABLE,EXCEPTION | RETURN_TO_SENDER,LOST | 2 minutes | CANCELLED, reason: UNDELIVERABLE | |
PENDING,INFO_RECEIVED,IN_TRANSIT,DELAYED,OUT_FOR_DELIVERY,AVAILABLE_FOR_PICKUP,DELIVERY_ATTEMPTED,CUSTOMER_ACTION,UNDELIVERABLE,EXCEPTION | DELIVERED | 2 minutes | DELIVERED | |
RETURN_TO_SENDER,LOST | None, this is a terminal state. | N/A | N/A | N/A |
DELIVERED | None, this is a terminal state. | N/A | N/A | N/A |
Query the order
Use the following query to get relevant PackageInformationDetails from an order.
Request
query order($orderIdentifier: OrderIdentifierInput!) {
order(orderIdentifier: $orderIdentifier) {
packageInformation {
details {
id
state
reason
packageInformationDetailsFor {
orderLineItems {
lineItem {
id
}
amount {
unit
value
}
}
}
packageTracker {
packageTrackerIdentifier {
trackingNumber
carrierCode
}
latestMilestone {
status {
code
}
}
}
}
}
}
}
//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:
- Create a Buy with Prime Order.
- Trigger fulfillment by doing one of the following:
- In the
createOrdercall, setdesiredExecutionStatetoSTARTED. - Trigger fulfillment for an existing order.
- In the
Examples
Update all items to be IN_TRANSIT in a single package
IN_TRANSIT in a single packageEvents published: PACKAGE_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 PackageInformationDetails. Then you can use the following request to update all the items in the package as IN_TRANSIT.
Request
mutation updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id",
"packageState": {
"packageInformationState": {
"state": "IN_TRANSIT"
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query response
{
"data": {
"order": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id",
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "PENDING"
}
}
}
}
]
}
}
}
}
Update all items to be IN_TRANSIT in multiple packages
IN_TRANSIT in multiple packagesEvents published: PACKAGE_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 PackageInformationDetails 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 updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-id",
"packageState": {
"packageInformationState": {
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItemAmounts": [
{
"lineItemId": {
"lineItemId": "example-line-item-id-1"
},
"amount": {
"value": 1
}
}
]
}
}
}
},
{
"id": "example-package-information-id",
"packageState": {
"packageInformationState": {
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItemAmounts": [
{
"lineItemId": {
"lineItemId": "example-line-item-id-2"
},
"amount": {
"value": 1
}
}
]
}
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"packageInformation": {
"summary": {
"state": "IN_TRANSIT"
},
"details": [
{
"id": "example-package-information-details-id-1",
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id-1"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number-1",
"carrierCode": "example-carrier-code-1"
},
"latestMilestone": {
"status": {
"code": "PENDING"
}
}
}
},
{
"id": "example-package-information-details-id-2",
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id-2"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number-2",
"carrierCode": "example-carrier-code-2"
},
"latestMilestone": {
"status": {
"code": "PENDING"
}
}
}
}
]
}
}
}
}
Update an IN_TRANSIT package’s tracking status code to OUT_FOR_DELIVERY
IN_TRANSIT package’s tracking status code to OUT_FOR_DELIVERYEvents published: PACKAGE_TRACKER_MILESTONE_CHANGED
You use the package tracker to set granular tracking status codes and publish PACKAGE_TRACKER_MILESTONE_CHANGED events. You don't need to update the PackageTracker status code to test the lifecycle of a package.
After a package is IN_TRANSIT, you can find tracking information in the PackageTracker in PackageInformationDetails. The following request shows how to use the UpdatePackageTrackerStateInput to set a tracking status code for the package.
Request
mutation updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id",
"packageState": {
"packageTrackerState": {
"packageTrackerIdentifier": {
"trackingNumber": "example-package-tracker-tracking-number",
"carrierCode": "example-package-tracker-carrier-code"
},
"latestMilestone": {
"status": {
"code": "OUT_FOR_DELIVERY"
}
}
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"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": {
"packageInformation": {
"summary": {
"state": "IN_TRANSIT"
},
"details": [
{
"id": "example-package-information-details-id",
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "OUT_FOR_DELIVERY"
}
}
}
}
]
}
}
}
}
Update all line items in the package CANCELLED due to CUSTOMER_REQUEST
CANCELLED due to CUSTOMER_REQUESTEvents published: PACKAGE_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 PackageInformationDetails and lineItems[].
The following request shows how to update all items as cancelled due to a customer request.
Request
mutation updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id",
"packageState": {
"packageInformationState": {
"state": "CANCELLED",
"reason" : "CUSTOMER_REQUESTED"
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"packageInformation": {
"summary": {
"state": "CANCELLED"
},
"details": [
{
"id": "example-package-information-details-id",
"state": "CANCELLED",
"reason": "CUSTOMER_REQUESTED",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
}
]
}
}
}
}
Update partial quantities of the same line item to be CANCELLED (UNFULFILLABLE), while the others as IN_TRANSIT
CANCELLED (UNFULFILLABLE), while the others as IN_TRANSITEvents published: PACKAGE_DELIVERY_IN_TRANSIT, PACKAGE_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 PackageInformationDetails 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 updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-id",
"packageState": {
"packageInformationState": {
"state": "CANCELLED",
"reason": "UNFULFILLABLE",
"packageInformationDetailsFor": {
"orderLineItemAmounts": [
{
"lineItemId": {
"lineItemId": "example-line-item-id"
},
"amount": {
"value": 1
}
}
]
}
}
}
},
{
"id": "example-package-information-id",
"packageState": {
"packageInformationState": {
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItemAmounts": [
{
"lineItemId": {
"lineItemId": "example-line-item-id"
},
"amount": {
"value": 1
}
}
]
}
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"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": {
"packageInformation": {
"summary": {
"state": "IN_TRANSIT"
},
"details": [
{
"id": "example-package-information-details-id-1",
"state": "CANCELLED",
"reason": "UNFULFILLABLE",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
}
},
{
"id": "example-package-information-details-id-2",
"state": "IN_TRANSIT",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "PENDING"
}
}
}
}
]
}
}
}
}
Update multiple packages as DELIVERED
DELIVEREDEvents published: PACKAGE_DELIVERED, PACKAGE_TRACKER_MILESTONE_CHANGED
The following example shows how to update two packages in the IN_TRANSIT state to the DELIVERED state.
Request
mutation updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id-1",
"packageState": {
"packageInformationState": {
"state": "DELIVERED"
}
}
},
{
"id": "example-package-information-details-id-2",
"packageState": {
"packageInformationState": {
"state": "DELIVERED"
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"order": {
"id": "example-order-id"
}
}
}
}
After you see the expected event, Query the order to view the updated details.
Query order response
{
"data": {
"order": {
"packageInformation": {
"summary": {
"state": "DELIVERED"
},
"details": [
{
"id": "example-package-information-details-id-1",
"state": "DELIVERED",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id-1"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "DELIVERED"
}
}
}
},
{
"id": "example-package-information-details-id-2",
"state": "DELIVERED",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id-2"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "DELIVERED"
}
}
}
}
]
}
}
}
}
Update a package as CANCELLED due to being UNDELIVERABLE
CANCELLED due to being UNDELIVERABLEEvents published: PACKAGE_DELIVERY_CANCELLED, PACKAGE_TRACKER_MILESTONE_CHANGED, 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 updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id",
"packageState": {
"packageInformationState": {
"state": "CANCELLED",
"reason": "UNDELIVERABLE"
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"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": {
"packageInformation": {
"summary": {
"state": "DELIVERED"
},
"details": [
{
"id": "example-package-information-details-id",
"state": "CANCELLED",
"resaon": "UNDELIVERABLE",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "LOST"
}
}
}
}
]
}
}
}
}
Update a package as DELIVERED
DELIVEREDEvents published: PACKAGE_DELIVERED, PACKAGE_TRACKER_MILESTONE_CHANGED
The following example shows how to update a package that is in IN_TRANSIT to DELIVERED by updating the package information state.
Request
mutation updateOrderPackageInformation($orderIdentifier: OrderIdentifierInput!, $input: UpdateOrderPackageInformationInput!) {
updateOrderPackageInformation(orderIdentifier: $orderIdentifier, input: $input) {
order {
id
}
}
}
//Mutation Variables
{
"orderIdentifier": {
"orderId": "example-order-id"
},
"input": {
"packageInformation": {
"details": [
{
"id": "example-package-information-details-id",
"packageState": {
"packageTrackerState": {
"packageTrackerIdentifier": {
"trackingNumber": "example-package-tracker-tracking-number",
"carrierCode": "example-package-tracker-carrier-code"
},
"latestMilestone": {
"status": {
"code": "DELIVERED"
}
}
}
}
}
]
}
}
}
Response
{
"data": {
"updateOrderPackageInformation": {
"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": {
"packageInformation": {
"summary": {
"state": "DELIVERED"
},
"details": [
{
"id": "example-package-information-details-id",
"state": "DELIVERED",
"packageInformationDetailsFor": {
"orderLineItems": [
{
"lineItem": {
"id": "example-line-item-id"
},
"amount": {
"unit": "ONE",
"value": 1
}
}
]
},
"packageTracker": {
"packageTrackerIdentifier": {
"trackingNumber": "example-tracking-number",
"carrierCode": "example-carrier-code"
},
"latestMilestone": {
"status": {
"code": "DELIVERED"
}
}
}
}
]
}
}
}
}
Updated 4 days ago