Buy with Prime | Developer Documentation
Documentation

Add an External Refund

📘

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

Refunds that are requested outside of Buy with Prime (such as when a shopper contacts you directly for a refund) are called external refunds.

Buy with Prime orders initially have no record of external refunds related to the order. Therefore, after you issue the refund to the customer, you can call the updateOrder mutation to add a refund to the Buy with Prime order. For details, see Steps to add an external refund.

The following examples show how to add an external refund to an order.

For an overview of refund terminology, see Synchronize Refunds. To learn how to call the Buy with Prime API, see Call the Buy with Prime API.

Add an external refund to a Buy with Prime order

After you have the unique identifier associated with an external refund, use the updateOrder mutation to add the refund to the Buy with Prime order.

In the request, include a refund alias of aliasType EXTERNAL-REFUND-ID and set the aliasId to a unique identifier for the refund.

📘

Important

For important information about how to call updateOrder to update or add aliases, see Refund alias.

The following example shows a request and response.

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": {
      "order": {
        "id": "example-order-id",
        "refunds": {
          "details": [
            {
              "id": "example-refund-id-from-buy-with-prime", 
              "updatedAt": "2024-06-25T07:37:24.907Z",
              "state": "PENDING",
              "aliases": [ 
                {
                  "aliasType": "EXTERNAL-REFUND-ID",
                  "aliasId": "example-external-refund-id"
                }
              ],
              "refundTotal": {
                "totalAmount": {
                "amount": 2.0
                }
              },
              "refundFor": {
                "orderLineItems": [
                  {
                    "lineItem": {
                      "id": "example-line-item-id"
                    },
                    "amount": {
                      "value": 1
                    }
                  }
                ]
               }
            }
          ]
        }
      }
    }
  }
}

Related topics

Updated about 23 hours ago