Guide: Refund a gift subscription

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

Overview

When a gift subscription needs to be refunded, you do it in two steps against the Orders API:

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.

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 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).

---

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": "GIFT-ABCD-1234-EFGH"
    }
  }'

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": "GIFT-ABCD-1234-EFGH",
    "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.

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, usually an invalid gift code, a gift with no charges, or a transient billing error	Verify the gift_code and that the gift was purchased and charged, then 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.