> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/guides/headless-guides/guide-refund-a-gift-subscription.md). # 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. {% hint style="info" %} 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. {% endhint %} ### Prerequisites * Access to the Limio Commerce API with a valid OAuth Bearer token. See [Authentication](https://docs.limio.com/developers/api/authentication-overview). * 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](#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. ```bash curl -X POST 'https://your-environment.prod.limio.com/api/order/preview' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "order_type": "gift_refund", "subscriptionId": "sub_gift_abc123", "data": { "gift_code": "k3TgR8mWq2Z" } }' ``` See the [Preview Order reference](https://docs.limio.com/api/orders-api/orders) 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`. ```bash curl -X POST 'https://your-environment.prod.limio.com/api/admin/order' \ -H 'Authorization: Bearer ' \ -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](https://docs.limio.com/api/orders-api/orders) 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](/guides/feature-implementation-guides/guide-how-to-sell-subscription-gift-codes-in-limio-commerce.md): selling and redeeming gift subscriptions * [Orders API reference](https://docs.limio.com/api/orders-api/orders): Preview Order and Submit Order request and response schemas * [Authentication](https://docs.limio.com/developers/api/authentication-overview): obtaining and refreshing API tokens When contacting support about a failed refund, include the error message returned and the `gift_code`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.limio.com/guides/headless-guides/guide-refund-a-gift-subscription.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.