Buy with Prime | Developer Documentation
Documentation

Change the State of a Return 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 updateOrderReturns to move a return package through various states to publish events without making real-world changes. For example, you can test how your application handles a RETURN_PACKAGE_DELIVERED event without actually delivering and then returning a package by setting the return package state to DELIVERED.

The response to updateOrderReturns contains the current order. You must wait for the state change to happen, and then you can query the order for the updated details. T

Reference: updateOrderReturns

In the sandbox environment, you can make the following state transitions to returns by calling updateOrderReturns with ReturnDetailsStateInputv20240101.

Input argumentCurrent stateNext stateExpected eventsExpected wait
ReturnDeliveryDetailsCREATEDCOMPLETEDRETURN_DELIVERY_COMPLETED, REFUND_REQUESTED2 minutes
ReturnDeliveryDetailsCOMPLETEDNone, this is a terminal state

Query the order

Use the following query to get relevant ReturnDetails from the order.

Request 
query order($orderIdentifier: OrderIdentifierInput!) {
  order(orderIdentifier: $orderIdentifier) {
    id
    returns {
      details {
        id
        state
        returnFor {
          orderLineItems {
            lineItem {
              id
            }
            returnedQuantity {
              amount
              unit
            }
          }
        }
      }
    }
  }
}

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

Prerequisites

  1. Create a Buy with Prime Order.
  2. Trigger fulfillment by doing one of the following:
  3. Update all of the packages in the order to DELIVERED. For details, see Update multiple packages as DELIVERED.
  4. Using the Merchant Online Return Center, create a return for all or some of the items. For details, see Create returns on behalf of customer.

Examples

Update a return package as COMPLETED

Events published: RETURN_COMPLETED

The following example shows how to mark a return completed.

Request 
mutation updateOrderReturns($input: UpdateOrderReturnsInput!) {
  updateOrderReturns(input: $input) {
    order {
      id
    }
  }
}

//Mutation Variables
{
  "input": {
    "details": [
      {
        "id": "example-return-details-id",
        "state": "COMPLETED"
      }
    ],
    "orderId": "example-order-id"
  }
}
Response 
{
  "data": {
    "updateOrderReturns": {
      "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",
      "returns": {
        "details": [
          {
            "id": "example-return-details-id",
            "state": "COMPLETED",
            "returnFor": {
              "orderLineItems": [
                {
                  "lineItem": {
                    "id": "example-line-item-id"
                  },
                  "returnedQuantity": {
                    "amount": 1,
                    "unit": "ONE"
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Updated 7 days ago