Buy with Prime | Developer Documentation
Documentation

Update Refund Details

📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

As you process Buy with Prime refunds, you must update the associated Buy with Prime order with the latest information. For a given refund, you typically call the Buy with Prime updateOrder mutation multiple times. For details, see Steps to Process Refunds.

You can associate each refund with one or more identifiers called aliases, which are in the refunds.details.aliases field of the order. If you use aliases for a refund, it is crucial to ensure that the aliases that you provide for the refund are unique and aren't already associated with other refunds in the order.

Each alias has an aliasId and an aliasType. We strongly recommend that you provide a unique aliasId that you can use when you call the updateOrder mutation to add or update refund details.

You can add and update refund aliases related to the order by calling the updateOrder mutation in the following way:

  • Updating an alias: Aliases of the same type overwrite each other. Therefore, to update an alias, call the updateOrder mutation and provide an aliasType that is already present for the refund. The existing aliasId with that aliasType will be overwritten with the aliasId that you provide in the updateOrder request. For example, consider an order with a refund aliasType of EXTERNAL-REFUND-ID and an aliasId of external-refund-id-1. If you call the updateOrder mutation and specify an aliasType of EXTERNAL-REFUND-ID and an aliasId of external-refund-id-2, the aliasId for the EXTERNAL-REFUND-ID is overwritten with the new value, external-refund-id-2.
  • Adding aliases: To add an alias, call the updateOrder mutation and provide an alias with a new aliasType.

📘

Note

You can't delete existing aliases.

The following table shows the refund state values that you can set on your next call to updateOrder given the current refund state. For details about processing refunds, see Steps to Process Refunds.

Current refund stateAllowable states you can use when you update a Buy with Prime refund
PENDINGPENDING, PARTIAL, FAILURE, SUCCESS
FAILUREPARTIAL, FAILURE, SUCCESS
PARTIALPARTIAL, SUCCESS
SUCCESSSUCCESS

The following examples show how to update the refund details of an order.

Update refund details and set the refund state to PARTIAL

After you initiate a refund payment in your order management system, you must update the Buy with Prime order with the amount that was refunded to the customer. The following example request indicates that $4 of a requested $10 refund has been initiated. For details, see Steps to Process Refunds.

Request 
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
  order {
    id  
  }
}

// Mutation Variables
{
  "orderIdentifier": {
    "orderId": "example-order-id"
  },
  "input": {
    "refunds": {
      "details": [
        {
          "id": "refund-123",
          "aliases": [
            {
              "aliasType": "EXTERNAL_REFUND_ID",
              "aliasId": "your-oms-refund-id"
            }
          ],
          "refundTotal": {
            "totalAmount": {
              "amount": 4,
              "currencyCode": "USD"
            }
          },
          "state": "PARTIAL",
          "refundFor": {
            "orderLineItems": [
              {
                "lineItemId": {
                  "lineItemId": "example-line-item-id"
                }
              }
            ]
          },
          "paymentDetails": [
            {
              "id": "example-payment-transfer-id-1",
              "amount": {
                "amount": 4,
                "currencyCode": "USD"
              },
              "paymentMethod": {
                "displayString": "Visa ending in 1234",
                "type": "AMAZON_PAY"
              },
              "state": "SUCCESS"
            }
          ]
        }
      ]
    }
  }
}
Response 
{
  "data": {
    "updateOrder": {
      "id": "example-order-id"
    }
  }
}

Update refund details and set the refund state to SUCCESS

The following sample request updates a refund that was previously $4 with another $6. The request sets the refund state to SUCCESS because the total refund amount ($10) is complete.

Request 
// GraphQL mutation
mutation updateOrder($orderIdentifier: OrderIdentifier!, $input: UpdateOrderInput!) {
  order {
    id  
  }
}

// Mutation Variables
{
  "orderIdentifier": {
    "orderId": "example-order-id"
  },
  "input": {
    "refunds": {
      "details": [
        {
          "id": "refund-123",
          "aliases": [
            {
              "aliasType": "EXTERNAL_REFUND_ID",
              "aliasId": "your-oms-refund-id"
            }
          ],
          "refundTotal": {
            "totalAmount": {
              "amount": 10,
              "currencyCode": "USD"
            }
          },
          "state": "SUCCESS",
          "refundFor": {
            "orderLineItems": [
              {
                "lineItemId": {
                  "lineItemId": "example-line-item-id"
                }
              }
            ]
          },
          "paymentDetails": [
            {
              "id": "example-payment-transfer-id-2",
              "amount": {
                "amount": 6,
                "currencyCode": "USD"
              },
              "paymentMethod": {
                "displayString": "Visa ending in 1234",
                "type": "AMAZON_PAY"
              },
              "state": "SUCCESS"
            }
          ]
        }
      ]
    }
  }
}
Response 
{
  "data": {
    "updateOrder": {
      "id": "example-order-id"
    }
  }
}

Related topics

Updated 7 days ago