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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Gestiona un programa de recompensas

> Publica recompensas remuneradas mediante la API, financia el depósito de garantía con el saldo de una cuenta, programa repeticiones, recibe y revisa envíos, y cancela recompensas.

Publica tareas remuneradas desde tu propio producto, financíalas con el saldo de una cuenta y lleva la cola de envíos a tu propia interfaz. Esta guía cubre el ciclo completo: crear una recompensa, recibir trabajo, revisarlo y cancelar.

> [!NOTE]
>
> Necesitas una clave de API con `bounty:create` y `payout:transfer_funds`, porque publicar una recompensa mueve dinero. Leer los envíos requiere `bounty:basic:read`.

## Publica una recompensa

[`POST /bounties`](https://docs.whop.com/es/api-reference/bounties/create-bounty) necesita un `title`, una `description` con las instrucciones que sigue un trabajador y un `gross_reward_amount`.

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: process.env.WHOP_API_KEY });

const bounty = await client.bounties.create({
	title: "Clip our launch stream",
	description: "Cut a 30 to 60 second vertical clip and post it to TikTok. Include the product name in the caption.",
	gross_reward_amount: 25,
	accepted_submissions_limit: 4,
	business_goal_type: "clipping",
	account_id: "biz_XXXXXXXX",
	allowed_country_codes: ["US", "CA"],
});

console.log(bounty.id);
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(token=os.environ["WHOP_API_KEY"])

bounty = client.bounties.create(
    title="Clip our launch stream",
    description="Cut a 30 to 60 second vertical clip and post it to TikTok. Include the product name in the caption.",
    gross_reward_amount=25,
    accepted_submissions_limit=4,
    business_goal_type="clipping",
    account_id="biz_XXXXXXXX",
    allowed_country_codes=["US", "CA"],
)

print(bounty.id)
```

### Lo que te cuesta la recompensa

`gross_reward_amount` se expresa en dólares estadounidenses enteros **por envío aceptado**, no por recompensa. `accepted_submissions_limit` establece cuántos envíos pueden ganar, y su valor predeterminado es `1`. Whop retiene en depósito de garantía el producto de ambos, y ese total debe ser de al menos $5. El ejemplo anterior retiene $100.

Las comisiones de la plataforma y las participaciones de afiliados se descuentan del importe bruto en lugar de sumarse, por lo que una recompensa de $25 le cuesta $25 a quien la financia.

### De dónde sale el dinero

El fondo se toma del saldo personal del llamador de forma predeterminada. Pasa `account_id` para financiarlo con el saldo de una cuenta, lo que requiere permiso para mover los fondos de esa cuenta.

### Dónde se ubica la recompensa

`experience_id` coloca una recompensa en una experiencia específica, pública para una recompensa abierta o privada para una por invitación, y **es obligatorio a menos que establezcas `account_id`**. Cuando estableces `account_id` y omites la experiencia, la recompensa se ubica en el foro público de esa cuenta.

### Declara el objetivo

`business_goal_type` indica lo que debe lograr el trabajo, y lo declaras una sola vez al crear la recompensa. Acepta `clipping`, `post_engagement`, `owned_account_growth`, `ugc_content`, `local_activation`, `data_capture` u `other`.

`capture_spec` solo se acepta cuando el objetivo es `data_capture`. Enviarlo con cualquier otro objetivo falla.

## Programa y repite

Una recompensa se publica en cuanto la creas, a menos que establezcas `publish_at`. Whop la crea como un borrador oculto y luego la financia y la publica a la hora que indicaste. `publish_at_timezone` es obligatorio siempre que se establezca `publish_at`.

`frequency` convierte una recompensa programada en una recurrente. Su valor predeterminado es `once`, acepta `hourly`, `daily`, `weekly` o `monthly`, y **solo se aplica junto con `publish_at`**. Cada repetición es una recompensa independiente con sus propios envíos y su propio depósito de garantía.

```typescript TypeScript theme={null}
const weekly = await client.bounties.create({
	title: "Weekly product clip",
	description: "One vertical clip per week featuring a different product from the catalog.",
	gross_reward_amount: 50,
	account_id: "biz_XXXXXXXX",
	business_goal_type: "clipping",
	publish_at: "2026-09-01T15:00:00Z",
	publish_at_timezone: "America/New_York",
	frequency: "weekly",
});
```

```python Python theme={null}
weekly = client.bounties.create(
    title="Weekly product clip",
    description="One vertical clip per week featuring a different product from the catalog.",
    gross_reward_amount=50,
    account_id="biz_XXXXXXXX",
    business_goal_type="clipping",
    publish_at="2026-09-01T15:00:00Z",
    publish_at_timezone="America/New_York",
    frequency="weekly",
)
```

## Edita una recompensa

Lo que acepta [`PATCH /bounties/{id}`](https://docs.whop.com/es/api-reference/bounties/update-bounty) depende de si la recompensa se ha publicado. Un **borrador programado** lo acepta todo: la recompensa, los cupos de ganadores, la programación y los campos de contenido.

Una **recompensa publicada** solo acepta contenido, es decir, `title`, `description`, `allowed_country_codes` y `business_goal_type`. Incluso esos se rechazan una vez que la recompensa deja de aceptar intentos, o una vez que algún envío llega a `submitted` o `approved`. La recompensa, los cupos de ganadores y la programación quedan fijados una vez que se publica una recompensa.

`accepted_submissions_per_user_limit` limita cuántos cupos puede ganar un trabajador. Su valor predeterminado es `1`, no puede superar `accepted_submissions_limit`, y un trabajador realiza un intento a la vez.

## Recibe envíos

[`POST /bounty_submissions`](https://docs.whop.com/es/api-reference/bounty-submissions/create-bounty-submission) acepta el `bounty_id` y un `deliverable`. Combina `urls`, `file_ids` y un `caption`, con **al menos un enlace o un archivo**. Whop rechaza un entregable vacío. En una recompensa estándar, esta única llamada es todo el flujo del trabajador, y el envío pasa directamente a revisión. Los envíos necesitan una credencial de usuario, por lo que una clave de API de cuenta no puede crear uno.

```typescript TypeScript theme={null}
const submission = await client.bountySubmissions.create({
	bounty_id: "bnty_XXXXXXXX",
	deliverable: {
		urls: ["https://www.tiktok.com/@creator/video/1234567890"],
		file_ids: ["file_XXXXXXXX"],
		caption: "Vertical cut, 42 seconds.",
	},
});
```

```python Python theme={null}
submission = client.bounty_submissions.create(
    bounty_id="bnty_XXXXXXXX",
    deliverable={
        "urls": ["https://www.tiktok.com/@creator/video/1234567890"],
        "file_ids": ["file_XXXXXXXX"],
        "caption": "Vertical cut, 42 seconds.",
    },
)
```

`allowed_country_codes` restringe quién puede realizar una recompensa. Acepta códigos ISO 3166 alfa-2. Una lista vacía significa todo el mundo.

Un trabajador puede retirar su propio intento con [`DELETE /bounty_submissions/{id}`](https://docs.whop.com/es/api-reference/bounty-submissions/cancel-bounty-submission). Solo puede hacerlo el trabajador que lo inició, y una clave de API de cuenta no puede hacerlo en su nombre.

### Objetivos que tu integración no puede completar

Dos tipos de objetivo acumulan su prueba fuera de la API. En una recompensa `data_capture`, crea el envío **sin** un entregable: eso inicia un intento reclamado cuyos clips se acumulan en el servidor. La prueba de una recompensa de transmisión en vivo pasa por una superficie que la API pública no expone. Tu integración puede publicar estas recompensas y leer sus colas, pero el trabajador termina el intento en Whop.

## Revisa la cola

Lee los envíos con [`GET /bounty_submissions`](https://docs.whop.com/es/api-reference/bounty-submissions/list-bounty-submissions), filtrados por `bounty_id` y, opcionalmente, por `status`.

```typescript TypeScript theme={null}
const queue = await client.bountySubmissions.list({
	bounty_id: "bnty_XXXXXXXX",
	status: "submitted",
});

for (const submission of queue.data) {
	console.log(submission.id, submission.status);
}
```

```python Python theme={null}
queue = client.bounty_submissions.list(
    bounty_id="bnty_XXXXXXXX",
    status="submitted",
)

for submission in queue.data:
    print(submission.id, submission.status)
```

Un envío pasa por cuatro estados:

| `status` | Significado |
| - | - |
| `in_progress` | Un intento activo que no ha enviado prueba |
| `submitted` | A la espera de una decisión |
| `approved` | Aceptado, y se paga la recompensa en depósito de garantía |
| `denied` | Rechazado. `denial_reason` incluye el motivo cuando existe uno presentable, y es `null` en caso contrario |

> [!WARNING]
>
> La aprobación y el rechazo se realizan en el panel de Whop. La API no tiene ninguna operación de aprobar o rechazar, así que tu producto puede mostrar la cola y sus resultados, pero una persona decide en Whop.

Las recompensas no emiten webhooks. Para reflejar los resultados en tu propio producto, consulta periódicamente `GET /bounty_submissions` filtrado por la recompensa. Una vez por minuto es adecuado para una cola que revisa una persona. Reduce la frecuencia a cada pocos minutos cuando una recompensa no tenga actividad reciente.

## Cancela una recompensa

[`POST /bounties/{id}/cancel`](https://docs.whop.com/es/api-reference/bounties/cancel) reembolsa a quien la financió inmediatamente cuando no hay trabajo en curso. Cuando hay trabajo en revisión, detiene los nuevos envíos y se cancela una vez que ese trabajo se resuelve y se paga.

Repetir la solicitud no hace nada. Una recompensa que ya pagó todos sus cupos devuelve un `400`.

## Solicitudes que pasan la validación y aun así fallan

Cuatro reglas que el esquema de la solicitud no puede expresar. Cada una devuelve un error aunque el cuerpo esté bien formado:

* `experience_id` omitido sin `account_id` establecido.
* `frequency` enviado sin `publish_at`.
* `capture_spec` enviado cuando `business_goal_type` es cualquier valor distinto de `data_capture`.
* Un `deliverable` que no incluye ni un enlace ni un archivo.

## Próximos pasos

> [card] [Descripción general de las recompensas](https://docs.whop.com/es/developer/bounties/overview.md)
>
> Los objetos y cómo encajan entre sí.

> [card] [Sube archivos](https://docs.whop.com/es/developer/guides/upload-files.md)
>
> Obtén los ID de archivo a los que hace referencia un entregable.

> [card] [Referencia de recompensas](https://docs.whop.com/es/api-reference/bounties/bounty)
>
> Estructuras de solicitud y respuesta de cada endpoint.

> [card] [Referencia de envíos de recompensas](https://docs.whop.com/es/api-reference/bounty-submissions/retrieve-bounty-submission.md)
>
> El objeto de envío y sus filtros.


## Related topics

- [Recompensas](https://docs.whop.com/es/developer/bounties/overview.md)
- [API de Product Affiliates](https://docs.whop.com/es/api-reference/product-affiliates/product-affiliate.md)
- [API de Partners](https://docs.whop.com/es/api-reference/partners/partner.md)
