> 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/developer-guides/guide-refund-a-gift-subscription.md). # Guide: Refund a gift subscription ### 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. {% 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 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)). *** ### 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": "GIFT-ABCD-1234-EFGH" } }' ``` 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": "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](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, 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](/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.limio.com/guides/developer-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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.