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, call the updateOrder mutation to add a refund to the Buy with Prime order. Use the id from the refunds.details field you received in a REFUND_REQUESTED event or from the order query. For a single call to updateOrder, the refund ID must be unique for each element in the refunds.details list.

For more details, see Steps to add an external refund.

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 21 days ago