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.

The following examples show how to update the refund details of 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.

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"
    }
  }
}

Update refund details and set the refund state to REJECTED

In some cases you might need to reject a refund as it might have been already processed or due to fraudulent return attempt. The following sample request rejects a refund. The request sets the refund state to REJECTED.

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": 0,
              "currencyCode": "USD"
            }
          },
          "state": "REJECTED"
        }
      ]
    }
  }
}
Response 
{
  "data": {
    "updateOrder": {
      "id": "example-order-id"
    }
  }
}

Update a refund reason

In some cases, you might need to update the refund request reason or the refund status reason after you submit the initial refund request. This can happen if new information becomes available or the situation changes.

To update the refund request reason or the refund status reason, include the updated values in a subsequent updateOrder mutation. The new values will override the previous values.

For example, assume that you initially submitted a refund request with the reason DELIVERED_NOT_RECEIVED, but the customer later contacts you and explains that the item was actually damaged. The following example shows how to update the refund request reason to DAMAGED_DEFECTIVE_ITEM.

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

// Mutation Variables
{
  "orderIdentifier": {
    "orderId": "example-order-id"
  },
  "input": {
    "refunds": {
      "details": [
        {
          "id": "refund-123",
          "refundRequestReason": "DAMAGED_DEFECTIVE_ITEM"
        }
      ]
    }
  }
}
Response 
{
  "data": {
    "updateOrder": {
      "id": "example-order-id"
    }
  }
}

Similarly, if the initial refund request was approved but then later needs to be rejected due to a fraudulent return attempt, you can update the refund state and status reason as the following example shows.

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

// Mutation Variables
{
  "orderIdentifier": {
    "orderId": "example-order-id"
  },
  "input": {
    "refunds": {
      "details": [
        {
          "id": "refund-123",
          "state": "REJECTED",
          "refundStatusReason": "FRAUDULENT_RETURN_ATTEMPT"
        }
      ]
    }
  }
}
Response 
{
  "data": {
    "updateOrder": {
      "id": "example-order-id"
    }
  }
}

Related topics

Updated about 23 hours ago