> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Compra en volumen

Una sola llamada a `purchaseGiftCard` compra **exactamente una** tarjeta de regalo, para **una oferta** a **una tasa**. No existe un campo `quantity`, y una sola llamada nunca se divide entre múltiples ofertas o tasas. Para comprar varias tarjetas, envía la mutación varias veces — una por tarjeta, cada una con su propia `idempotencyKey` única.

Cómo cada llamada elige su oferta y tasa depende de si pasas `offerId` o `merchantSlug`.

### Flujo de compra a simple vista

![](https://files.readme.io/bf6ad80159ab3e0beecb76d51f498a4093b793bf7368288abe62e5c81b2b36c5-diagram.svg)

### `offerId` — fija una oferta y tasa específicas

Cuando pasas `offerId`, la compra queda bloqueada a esa oferta exacta y su tasa. Si esa oferta ya no se puede cumplir (por ejemplo, una oferta con control de inventario que se agotó), la llamada **falla** — **no** sustituirá silenciosamente una oferta diferente. Consulta el error de falta de stock a continuación.

### `merchantSlug` — selección automática de la mejor oferta disponible

Cuando pasas `merchantSlug` (sin `offerId`), el sistema selecciona la **mejor oferta disponible con stock** para ese comercio **en el momento de cada llamada**. Debido a que la selección ocurre por llamada, compras repetidas para el mismo comercio pueden resolverse en **ofertas diferentes** a medida que cambia la disponibilidad.

### Ofertas fijas vs. variables e inventario

* Las **ofertas de denominación fija** tienen control de inventario por denominación. Una vez que se agota una denominación, ya no se puede seleccionar, y cualquier llamada posterior fijada a ella (vía `offerId`) devuelve un error de falta de stock.
* Las **ofertas variables** no están limitadas por inventario de la misma manera. Normalmente permanecen disponibles y actúan como respaldo cuando una oferta fija/con stock se agota. Una oferta variable a menudo tiene una **tasa de recompensa diferente (frecuentemente menor)** que la oferta fija a la que reemplaza.

> 📘 Qué sucede cuando compras más tarjetas de las que hay en stock
>
> Supón que la mejor oferta de un comercio es una oferta fija con control de inventario con solo **8** unidades restantes, y quieres **10** tarjetas (es decir, 10 llamadas separadas a `purchaseGiftCard`):
>
> * **Usando** `offerId` (fijado a la oferta fija): las primeras 8 llamadas tienen éxito; la 9.ª y 10.ª llamadas **fallan** con un error de falta de stock. No ocurre un cambio automático a otra oferta o tasa.
> * **Usando** `merchantSlug` (selección automática): las primeras 8 llamadas compran en la oferta fija; cuando se agota, las llamadas restantes seleccionan automáticamente la **siguiente mejor oferta disponible** — que puede ser una **oferta variable con una tasa de recompensa más baja**.
>
> En todos los casos, cada tarjeta se compra de forma atómica con la oferta y tasa resueltas para esa llamada individual — no hay pedidos combinados ni parcialmente cumplidos.

### Protege tu tasa con `minRewardRate`

Cuando compras con `merchantSlug`, usa `minRewardRate` para establecer un piso de la tasa de recompensa. Antes de comprar, el sistema verifica la mejor tasa disponible para el comercio, monto y método de pago; si esa tasa está **por debajo de tu** `minRewardRate` (o no se puede cotizar ninguna tasa), la llamada **falla** en lugar de comprar a la tasa inferior. Esta es la forma recomendada de evitar comprar sin querer las tarjetas restantes en una oferta variable de menor tasa después de que se agote una oferta con stock y tasa más alta.

> 🚧 `minRewardRate` solo aplica a compras con `merchantSlug`.
>
> Si proporcionas `offerId`, se ignora `minRewardRate` (la oferta — y su tasa — ya están fijas). El piso se evalúa por llamada, así que inclúyelo en cada llamada cuando compres múltiples tarjetas.

### Error de falta de stock

Cuando una oferta ya no se puede cumplir por inventario, la mutación devuelve:

```json theme={null}
{
  "code": "GC-0009",
  "message": "This offer is currently out of stock. Please select a different amount or try again later."
}
```

Vuelve a cotizar con `getOfferQuote` / `getMerchants` para encontrar la mejor oferta disponible actual antes de reintentar.

> 📘
>
> ### Qué sucede cuando compras más tarjetas de las que hay en stock
>
> Supón que la mejor oferta de un comercio es una oferta fija con control de inventario con solo **8** unidades restantes y quieres **10** tarjetas (10 llamadas separadas a `purchaseGiftCard`):
>
> * **Usando** `offerId` (fijado a la oferta fija): las primeras 8 llamadas tienen éxito a la tasa con stock; la 9.ª y 10.ª llamadas **fallan** con `GC-0009`. No ocurre un cambio automático a otra oferta o tasa.
> * **Usando** `merchantSlug` (selección automática): las primeras 8 llamadas compran en la oferta fija a la tasa más alta; cuando se agota, las llamadas restantes seleccionan automáticamente la **siguiente mejor oferta disponible** — que puede ser una **oferta variable con una tasa de recompensa más baja**.

> 🚧
>
> ### Protege tu tasa con `minRewardRate`
>
> Al comprar con `merchantSlug`, establece `minRewardRate` como un piso de la tasa de recompensa. Antes de cada compra, el sistema verifica la mejor tasa disponible para el comercio, monto y método de pago; si esa tasa está **por debajo** de tu `minRewardRate` (o no se puede cotizar ninguna tasa), la llamada **falla** en lugar de comprar a la tasa inferior. Esta es la forma recomendada de evitar comprar sin querer las tarjetas restantes en una oferta variable de menor tasa después de que se agote una oferta con stock y tasa más alta.
>
> `minRewardRate` se **ignora** cuando proporcionas `offerId` (la tasa ya está fija), y se evalúa **por llamada** — inclúyelo en cada llamada cuando compres múltiples tarjetas.

Para verificar el inventario antes de comprar, consulta [Obtener inventario en ofertas con stock](/get-inventory).