> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Canjear una tarjeta de regalo en mostrador

POST https://app.recurrente.com/api/gift_cards/{gift_card_id}/redemption
Content-Type: application/json

Gasta saldo de la tarjeta por una venta cobrada fuera de un checkout de
Recurrente (efectivo, otra terminal), como "Canjear" en el panel. Un canje
en otra sucursal de la organización se le paga a esa sucursal. Emite
`gift_card.redeem`. Requiere que la llave pueda mover dinero.


Reference: https://docs.recurrente.com/referencia-api/api-reference/gift-cards/redeem-gift-card

## Authentication

- `X-SECRET-KEY` header (required) — Tu clave secreta de API. Una llave de cuenta (`sk_live_...`, `sk_test_...`) opera sobre su propia cuenta y, con `X-ACCOUNT-ID`, sobre sus cuentas conectadas. La llave también fija el ambiente: una `sk_test_` solo lista y resuelve objetos de prueba (`live_mode: false`) y una `sk_live_` solo objetos reales. Un ID del otro ambiente responde `404` (`401` en `/customers`). Una llave de organización (`sk_org_live_...`, `sk_org_test_...`) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con `X-ACCOUNT-ID`; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde `403` con `code: organization_key_unsupported`.

## Request

### Path parameters

- `gift_card_id` (string, required)

### Body (application/json)

This endpoint expects an object.

- `amount_in_cents` (integer, required)
- `note` (string, optional)

## Response

### 201

La tarjeta, con el canje

- `id` (string, optional)
- `account_id` (string, optional) — La cuenta que la vendió.
- `code` (string, optional) — El código que se canjea. Es un secreto al portador.
- `status` (enum, optional)
  - Allowed values: `active`, `depleted`, `expired`, `voided`
- `currency` (string, optional)
- `initial_amount_in_cents` (integer, optional)
- `balance_in_cents` (integer, optional)
- `expires_on` (date, optional, nullable)
- `recipient` (GiftCardRecipient, optional)
- `message` (string, optional, nullable)
- `deliver_on` (date, optional, nullable)
- `delivered_at` (datetime, optional, nullable)
- `purchaser` (GiftCardPurchaser, optional)
- `checkout_id` (string, optional, nullable) — El checkout que la vendió.
- `public_url` (string, optional) — La página de saldo de la tarjeta, la que abre su QR.
- `transactions` (list of GiftCardTransaction, optional) — Sus movimientos, del más viejo al más nuevo.
- `created_at` (datetime, optional)

## Errors

### 403 Forbidden Error

La llave no puede mover dinero (`money_movement_not_enabled`)

- `message` (string, optional) — Mensaje de error
- `code` (string, optional) — Código estable legible por máquinas, cuando aplica
- `refund_id` (string, optional) — ID del reembolso relacionado cuando aplica
- `endpoint` (string, optional) — Acción de API rechazada, cuando aplica
- `errors` (ErrorErrors, optional) — Detalles de errores por campo

### 422 Unprocessable Entity Error

La tarjeta no está activa o el saldo no alcanza (`invalid_gift_card_movement`)

- `message` (string, optional) — Mensaje de error
- `code` (string, optional) — Código estable legible por máquinas, cuando aplica
- `refund_id` (string, optional) — ID del reembolso relacionado cuando aplica
- `endpoint` (string, optional) — Acción de API rechazada, cuando aplica
- `errors` (ErrorErrors, optional) — Detalles de errores por campo

## Types

### GiftCardRecipient

- `name` (string, optional, nullable)
- `email` (string, optional, nullable)
- `phone` (string, optional, nullable)

### GiftCardPurchaser

- `name` (string, optional, nullable)
- `email` (string, optional, nullable)

### GiftCardTransaction

Un movimiento del saldo de una tarjeta. `amount_in_cents` lleva signo (un canje es negativo).

- `id` (string, optional)
- `kind` (enum, optional)
  - Allowed values: `issue`, `redeem`, `release`, `reload`, `refund_back`, `adjust`, `expire`, `void`, `refund_void`
- `amount_in_cents` (integer, optional)
- `balance_after_in_cents` (integer, optional)
- `currency` (string, optional)
- `account_id` (string, optional) — La cuenta (sucursal) donde ocurrió.
- `checkout_id` (string, optional, nullable)
- `note` (string, optional, nullable)
- `created_at` (datetime, optional)

### ErrorErrors

Detalles de errores por campo

## Examples

**Request**

```json
{
  "amount_in_cents": 4000
}
```

**Response**

```json
{
  "id": "gc_9f8e7d6c",
  "account_id": "ac_7890abcd",
  "code": "GC-7X9Y-Z3PQ",
  "status": "active",
  "currency": "GTQ",
  "initial_amount_in_cents": 25000,
  "balance_in_cents": 21000,
  "expires_on": "2024-12-31",
  "recipient": {
    "name": "Carlos Méndez",
    "email": "carlos.mendez@example.com",
    "phone": "+502 5555 1234"
  },
  "message": "Feliz cumpleaños, disfruta tu regalo!",
  "deliver_on": "2024-01-10",
  "delivered_at": "2024-01-10T15:45:00Z",
  "purchaser": {
    "name": "Ana López",
    "email": "ana.lopez@example.com"
  },
  "checkout_id": "chk_4567efgh",
  "public_url": "https://recurrente.com/gift_cards/gc_9f8e7d6c",
  "transactions": [
    {
      "id": "gct_1234abcd",
      "kind": "issue",
      "amount_in_cents": 25000,
      "balance_after_in_cents": 25000,
      "currency": "GTQ",
      "account_id": "ac_7890abcd",
      "checkout_id": "chk_4567efgh",
      "note": "Emisión inicial de la tarjeta",
      "created_at": "2023-12-01T10:00:00Z"
    },
    {
      "id": "gct_5678efgh",
      "kind": "redeem",
      "amount_in_cents": -4000,
      "balance_after_in_cents": 21000,
      "currency": "GTQ",
      "account_id": "ac_7890abcd",
      "checkout_id": "null",
      "note": "Canje en mostrador por venta en efectivo",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "created_at": "2023-12-01T10:00:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://app.recurrente.com/api/gift_cards/gift_card_id/redemption"

payload = { "amount_in_cents": 4000 }
headers = {
    "X-SECRET-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.recurrente.com/api/gift_cards/gift_card_id/redemption';
const options = {
  method: 'POST',
  headers: {'X-SECRET-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"amount_in_cents":4000}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.recurrente.com/api/gift_cards/gift_card_id/redemption"

	payload := strings.NewReader("{\n  \"amount_in_cents\": 4000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-SECRET-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.recurrente.com/api/gift_cards/gift_card_id/redemption")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SECRET-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount_in_cents\": 4000\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://app.recurrente.com/api/gift_cards/gift_card_id/redemption")
  .header("X-SECRET-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount_in_cents\": 4000\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.recurrente.com/api/gift_cards/gift_card_id/redemption', [
  'body' => '{
  "amount_in_cents": 4000
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-SECRET-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.recurrente.com/api/gift_cards/gift_card_id/redemption");
var request = new RestRequest(Method.POST);
request.AddHeader("X-SECRET-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"amount_in_cents\": 4000\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-SECRET-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["amount_in_cents": 4000] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://app.recurrente.com/api/gift_cards/gift_card_id/redemption")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```