Buy with Prime | Developer Documentation
Documentation
GraphQL Playground

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. 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 stateExpected events
PENDINGCANCELLED, reason UNFULFILLABLE or CUSTOMER_REQUESTEDDELIVERY_CANCELLED,
REFUND_REQUESTED
PENDINGIN_TRANSITDELIVERY_IN_TRANSIT
IN_TRANSITCANCELLED, reason UNDELIVERABLEDELIVERY_CANCELLED,
REFUND_REQUESTED
IN_TRANSITDELIVEREDDELIVERY_COMPLETED
CANCELLED,
DELIVERED		None, this is a terminal state.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:

  1. Set up inventory in the sandbox with the help of your Buy with Prime solutions architect.
  2. Create a Buy with Prime Order.
  3. Trigger fulfillment by doing one of the following:

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 canceled 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 5 months ago