Skip to content

Refund an order

Request

Refunds an order through its Shopify store. This is "Initiate refund" on the order page of the merchant portal: the refund is issued in Shopify, either to the original payment method or as a Shopify gift card, and recorded in Hive. When the order has a return, the refund settles that return.

Only orders imported from a Shopify store can be refunded, and only while the portal would offer the refund: the store is active and connected, the order is fully shipped and paid, the payment was processed less than 120 days ago, the order has at most one return, and it has not been refunded yet. An order can be refunded once; a second request is refused.

For a refund to the original payment method, shipping_amount_in_cents and items are required, notify_customer applies, and amount_in_cents cannot exceed what Shopify reports as refundable for the order.

Every item, of either refund type, must name a SKU on one of the order's active line items, and cannot ask for more units of it than those line items hold, counting all items of the same SKU together; otherwise the request is refused with 422 before anything is refunded. A request whose Content-Type is missing or is not application/json is rejected with 415.

Security
BearerAuth
Path
idinteger, (int64)required

Order ID

Bodyapplication/jsonrequired
amount_in_centsinteger, (int64), >= 1required

Amount to refund in cents, shipping included. For a refund to the original payment method it is in the currency Shopify refunds the order in, and cannot exceed what Shopify reports as refundable. For a gift card it is in the order's currency.

descriptionstring, <= 400 characters^[^\u0000]*$

Internal note stored with the refund

itemsArray of objects(OrderRefundItem)

The SKUs and quantities the refund is for, recorded with the refund. Required for a refund to the original payment method, where Shopify receives them as the refunded line items, without restocking.

notify_customerboolean

Whether Shopify notifies the customer about a refund to the original payment method

Default:false
shipping_amount_in_centsinteger, (int64), >= 0

The part of amount_in_cents that refunds shipping, in cents. Required for a refund to the original payment method, and cannot exceed the refundable shipping cost.

typestring(OrderRefundType)required

How the refund is paid out. Possible values:

  • gift_card: a Shopify gift card for the customer
  • original_payment_method: back to the payment method the customer paid with
Enum:"gift_card""original_payment_method"
curl -i -X PUT \
  'https://developers.hive.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}/refund' \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "original_payment_method",
    "amount_in_cents": 2499,
    "shipping_amount_in_cents": 499,
    "notify_customer": true,
    "description": "Damaged in transit",
    "items": [
      {
        "sku_id": 1001,
        "quantity": 1
      }
    ]
  }'

Responses

The refund was issued in Shopify and recorded

Bodyapplication/json
amount_in_centsinteger, (int64)required

Refunded amount in cents, in currency

created_atstring, (date-time)required

When the refund was recorded in Hive

currencystringrequired

Currency of the refund as Shopify issued it (ISO 4217)

idinteger, (int64)required

Refund ID

order_idinteger, (int64)required

ID of the refunded order

typestring(OrderRefundType)required

How the refund is paid out. Possible values:

  • gift_card: a Shopify gift card for the customer
  • original_payment_method: back to the payment method the customer paid with
Enum:"gift_card""original_payment_method"
Response
{
  "id": 5501,
  "order_id": 123456,
  "type": "original_payment_method",
  "amount_in_cents": 2499,
  "currency": "EUR",
  "created_at": "2026-10-01T09:30:00Z"
}