Guide: Refund a gift subscription

Preview and process a refund for a gift subscription using the Orders API.

Overview

Refunding a gift subscription is a headless operation: your server calls the Orders API, and no Limio page or component is involved. You do it in two steps:

1. Preview the refund to see the amount that will be credited, using POST api/order/preview with order_type: gift_refund.
2. Submit the refund to process it, using POST api/admin/order with order_type: refund.

Both steps identify the gift by its gift_code. Limio looks up the gift's original charges in the billing system, raises a credit memo for them, refunds it, and marks the gift code as used. You can refund a gift only once, and only while it is still unredeemed. An expired gift code does not stop the refund.

The two steps use different order_type values on purpose: gift_refund previews the amount, refund processes it. Send the same gift_code to both.

Prerequisites

• Access to the Limio Commerce API with a valid OAuth Bearer token. See Authentication.
• The gift_code for the gift being refunded.
• The subscriptionId of the gift subscription that the gift_code belongs to. If the two do not match, Limio rejects the refund.
• The gift must have been purchased and have charges in the billing system. A gift code that was never charged has nothing to refund.
• The gift must not have been redeemed yet, and must not have been refunded before. Once a recipient redeems the gift, cancel the resulting subscription instead (see Cancelling a gift). If a gift code has more than one seat, you can refund it until all of its seats are used. The refund uses the amount that you send in total, and the unused seats can no longer be redeemed.
• The gift code can be expired. Limio refunds an expired gift that nobody redeemed.

---

Step 1: Preview the refund

Call POST api/order/preview with order_type: gift_refund. The response returns the credit memo(s) and a schedule showing what will be refunded, so you can confirm the amount before processing.

curl -X POST 'https://your-environment.prod.limio.com/api/order/preview' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_type": "gift_refund",
    "subscriptionId": "sub_gift_abc123",
    "data": {
      "gift_code": "k3TgR8mWq2Z"
    }
  }'

See the Preview Order reference for the full request and response schema.

---

Step 2: Submit the refund

Once the amount is confirmed, process the refund with POST api/admin/order and order_type: refund. Send the same gift_code and the amount to refund in total.

curl -X POST 'https://your-environment.prod.limio.com/api/admin/order' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_type": "refund",
    "subscriptionId": "sub_gift_abc123",
    "gift_code": "k3TgR8mWq2Z",
    "total": { "amount": 120, "currency": "GBP" }
  }'

The order runs through Limio's order orchestration: it raises the credit memo for that amount, refunds it to the original payment method, and marks the gift code as used. If the gift was redeemed or refunded before, Limio rejects the order and does not raise a credit memo.

See the Submit Order reference for the full request and response schema.

---

Cancelling a gift

Refunding a gift cancels it. The refund reverses the purchaser's payment, the gift subscription moves to a cancelled state, and the gift code can no longer be redeemed. This is the path for a gift the recipient has not yet redeemed, and it can be done only once.

Once a recipient has redeemed their gift, the refund path no longer applies. To end the resulting active subscription, cancel it like any other: submit POST api/admin/order with order_type: cancel_subscription and the subscription in forSubscription (see the cancelSubscription example on the Submit Order endpoint).

---

Errors

Both endpoints return { "message": "..." } on failure.

Status	Meaning	Resolution
401	Missing or invalid Bearer token	Check the Authorization header
502	The request could not be processed. The usual causes are a gift code that does not exist, a gift that was redeemed or refunded before, a gift with no charges, or a transient billing error	Make sure that the gift_code is correct and that the gift was purchased and charged. If the gift was redeemed or refunded before, do not retry

Bank transfer and PayPal gifts. The credit memo is still raised, but the automatic refund step is skipped for these payment methods. The refund is settled outside Limio.

---

Related resources

• Guide: Subscription Gift Codes: selling and redeeming gift subscriptions
• Orders API reference: Preview Order and Submit Order request and response schemas
• Authentication: obtaining and refreshing API tokens

When contacting support about a failed refund, include the error message returned and the gift_code.