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

# Recompensas

> Aprende a usar las recompensas en una experiencia de producto gamificada con Trophy.

## ¿Qué son las recompensas?

Las recompensas te permiten dar algo a los usuarios cuando alcanzan un hito, y dejar que elijan cuándo reclamarlo.

Una recompensa se **otorga** automáticamente cuando un usuario cumple uno de sus [desencadenadores](#reward-triggers), por ejemplo, al desbloquear un logro o alcanzar una racha de cierta duración. Solo se **entrega** cuando se **canjea**, lo cual haces llamando al [endpoint de canje](https://docs.trophy.so/es/api-reference/endpoints/rewards/redeem-a-reward.md) cuando el usuario la reclama en tu producto.

Otorgar una recompensa nunca modifica por sí solo el saldo de puntos de un usuario.

## Tipos de recompensas

Hay dos tipos de recompensa.

### Recompensas de puntos

Las recompensas de puntos otorgan una cantidad fija de puntos de un [sistema de puntos](https://docs.trophy.so/es/features/points.md) cuando se canjean.

Los puntos se otorgan según el valor en puntos de la recompensa en el momento del canje, y respetan cualquier [potenciador](https://docs.trophy.so/es/features/points.md#points-boosts) y el máximo del sistema de puntos. Si se superara el máximo a mitad del canje de varias recompensas otorgadas, se canjean las que caben y el resto permanece sin canjear para que puedas reintentarlo.

### Recompensas personalizadas

Las recompensas personalizadas no hacen nada dentro de Trophy al canjearse, salvo enviar el `reward.redeemed` [webhook](#webhooks). Úsalas cuando quieras entregar la recompensa tú mismo.

## ¿Recompensas o desencadenadores de puntos?

Tanto las recompensas como los [desencadenadores de puntos](https://docs.trophy.so/es/features/points.md#points-triggers) pueden dar puntos a los usuarios cuando ocurre algo, pero funcionan de forma distinta.

| | Desencadenadores de puntos | Recompensas |
| - | - | - |
| Los puntos se añaden al saldo del usuario | Automáticamente, en cuanto se activa el desencadenador | Solo cuando se canjea la recompensa |
| Requiere un paso de canje en tu producto | No | Sí |
| Puede otorgar algo distinto de puntos | No | Sí, con recompensas personalizadas |
| Webhooks | `points.changed` | `reward.awarded` y `reward.redeemed` |

> [!TIP]
>
> Si quieres que los puntos se apliquen automáticamente al saldo de un usuario y no necesitas un paso de canje, usa un [desencadenador de puntos](https://docs.trophy.so/es/features/points.md#points-triggers). Usa las recompensas cuando los usuarios deban reclamar algo o cuando tengas que entregarlo tú mismo.

## Casos de uso

### Bonificaciones reclamables

Otorga a los usuarios puntos de bonificación por alcanzar un hito, pero deja que pulsen un botón 'Reclamar' en tu producto para recibirlos. El momento de la reclamación es un lugar natural para mostrar una pantalla o una animación de celebración.

### Premios y ventajas

Usa recompensas personalizadas para entregar elementos que existen fuera de Trophy, como un código de descuento, un mes gratis o un premio físico. Trophy te informa cuándo se otorga y se canjea la recompensa, y tu sistema se encarga del resto.

## Crear recompensas

Para crear una recompensa, ve a la [página de recompensas](https://app.trophy.so/rewards) y sigue los pasos que se indican a continuación.

> [!TIP]
>
> Las recompensas nuevas se crean como 'Inactivas' y sin desencadenadores, para que puedas configurarlas y probarlas antes de publicarlas.

**1. Haz clic en Nueva recompensa**

Asigna un nombre y una clave única a la recompensa. La clave es lo que usarás para hacer referencia a la recompensa en las APIs y no se puede cambiar después de crearla.

**2. Elige un tipo de recompensa**

Elige entre una [recompensa de puntos](#points-rewards) y una [recompensa personalizada](#custom-rewards).

**3. Configura la recompensa**

En una recompensa de puntos, elige el sistema de puntos y la cantidad de puntos que se otorgarán cuando se canjee la recompensa. También puedes añadir una descripción que las APIs devuelven para mostrarla en tu aplicación.

**4. Establece un límite de canje (opcional)**

Limita cuántas veces se puede otorgar la recompensa a cada usuario. Consulta [límites de canje](#redemption-limits).

**5. Añade filtros de usuario (opcional)**

Restringe la recompensa a los usuarios con [atributos de usuario personalizados](https://docs.trophy.so/es/features/users.md#custom-user-attributes) específicos. Consulta [filtros de usuario](#user-filters).

**6. Añade activadores y activa**

Añade uno o más [activadores](#reward-triggers) y luego cambia el estado de la recompensa a activo para ponerla en producción.

También puedes crear recompensas y sus activadores de forma programática con la API de administración:

```bash cURL theme={null}
curl -X POST https://admin.trophy.so/v1/rewards \
     -H "X-API-KEY: <api-key>" \
     -H "Content-Type: application/json" \
     -d '[
       {
         "name": "Welcome bonus",
         "key": "welcome-bonus",
         "type": "points",
         "pointsSystemId": "points-system-uuid",
         "points": 100,
         "triggers": [
           {
             "type": "achievement",
             "achievementId": "achievement-uuid",
             "status": "active"
           }
         ]
       }
     ]'
```

```typescript Node theme={null}
await trophy.admin.rewards.create([
  {
    name: "Welcome bonus",
    key: "welcome-bonus",
    type: "points",
    pointsSystemId: "points-system-uuid",
    points: 100,
    triggers: [
      {
        type: "achievement",
        achievementId: "achievement-uuid",
        status: "active",
      },
    ],
  },
]);
```

```python Python theme={null}
client.admin.rewards.create(
    request=[
        {
            "name": "Welcome bonus",
            "key": "welcome-bonus",
            "type": "points",
            "points_system_id": "points-system-uuid",
            "points": 100,
            "triggers": [
                {
                    "type": "achievement",
                    "achievement_id": "achievement-uuid",
                    "status": "active",
                }
            ],
        }
    ],
)
```

```php PHP theme={null}
$trophy->admin->rewards->create([
    [
        'name' => 'Welcome bonus',
        'key' => 'welcome-bonus',
        'type' => 'points',
        'pointsSystemId' => 'points-system-uuid',
        'points' => 100,
        'triggers' => [
            [
                'type' => 'achievement',
                'achievementId' => 'achievement-uuid',
                'status' => 'active',
            ],
        ],
    ],
]);
```

```java Java theme={null}
CreateRewardsResponse response = client.admin().rewards().create(
  List.of(
    CreateRewardRequestItem.builder()
      .name("Welcome bonus")
      .key("welcome-bonus")
      .type(CreateRewardRequestItemType.POINTS)
      .pointsSystemId("points-system-uuid")
      .points(100)
      .triggers(List.of(
        CreateRewardTriggerRequestItem.builder()
          .type(CreateRewardTriggerRequestItemType.ACHIEVEMENT)
          .achievementId("achievement-uuid")
          .status(CreateRewardTriggerRequestItemStatus.ACTIVE)
          .build()
      ))
      .build()
  )
);
```

```go Go theme={null}
response, err := client.Admin.Rewards.Create(
    context.TODO(),
    []*api.CreateRewardRequestItem{
        {
            Name: "Welcome bonus",
            Key: "welcome-bonus",
            Type: api.CreateRewardRequestItemTypePoints,
            PointsSystemId: api.String("points-system-uuid"),
            Points: api.Int(100),
            Triggers: []*api.CreateRewardTriggerRequestItem{
                {
                    Type: api.CreateRewardTriggerRequestItemTypeAchievement,
                    AchievementId: api.String("achievement-uuid"),
                    Status: api.CreateRewardTriggerRequestItemStatusActive.Ptr(),
                },
            },
        },
    },
)
```

```csharp C# theme={null}
await trophy.Admin.Rewards.CreateAsync(new[]
{
    new CreateRewardRequestItem
    {
        Name = "Welcome bonus",
        Key = "welcome-bonus",
        Type = CreateRewardRequestItemType.Points,
        PointsSystemId = "points-system-uuid",
        Points = 100,
        Triggers = new[]
        {
            new CreateRewardTriggerRequestItem
            {
                Type = CreateRewardTriggerRequestItemType.Achievement,
                AchievementId = "achievement-uuid",
                Status = CreateRewardTriggerRequestItemStatus.Active,
            },
        },
    },
});
```

```ruby Ruby theme={null}
result = client.admin.rewards.create([
  {
    name: 'Welcome bonus',
    key: 'welcome-bonus',
    type: 'points',
    points_system_id: 'points-system-uuid',
    points: 100,
    triggers: [
      {
        type: 'achievement',
        achievement_id: 'achievement-uuid',
        status: 'active'
      }
    ]
  }
])
```

## Activadores de recompensa

Las recompensas se otorgan mediante activadores. Puedes añadir tantos activadores como quieras a una recompensa, y cada uno se puede activar y desactivar de forma independiente.

> [!NOTE]
>
> Los activadores funcionan de forma independiente entre sí. Cada activador activo puede otorgar la recompensa por sí solo, por lo que el usuario **no** necesita cumplir todos los activadores de una recompensa. Por ejemplo, una recompensa con un activador de racha y un activador de logro se otorga cuando el usuario alcanza la longitud de la racha y de nuevo cuando completa el logro. Cualquier [límite de canje](#redemption-limits) se aplica a todos los activadores de la recompensa en conjunto.

### Tipos de disparadores

#### Disparadores de métrica

La recompensa se otorga cada vez que el total de una [métrica](https://docs.trophy.so/es/features/metrics.md) del usuario aumenta según el umbral que establezcas, por ejemplo "otorgar cada 10 tareas completadas". El recuento comienza desde que se activó el disparador.

Si vuelves a activar el disparador, o cambias su métrica, umbral o atributos de evento, se inicia un nuevo recuento.

#### Disparadores de racha

La recompensa se otorga cada vez que la [racha](https://docs.trophy.so/es/features/streaks.md) actual del usuario aumenta según la duración de racha que establezcas, por ejemplo "otorgar cada 7 días". El período en el que se activó el disparador cuenta como el primer período, y si cambias la duración de la racha, se inicia un nuevo recuento.

Una racha que terminó antes de activarse el disparador, o que se interrumpió después, no reduce el recuento.

> [!TIP]
>
> Los disparadores de racha otorgan la recompensa de forma repetida. Establece un [límite de canjes](#redemption-limits) de 1 para otorgarla solo una vez.

#### Disparadores de logro

La recompensa se otorga una sola vez, cuando el usuario completa un [logro](https://docs.trophy.so/es/features/achievements.md) específico. No se otorga a los usuarios que completaron el logro antes de que existiera el disparador.

#### Disparadores de clasificación

La recompensa se otorga al usuario que termina una ejecución de [clasificación](https://docs.trophy.so/es/features/leaderboards.md) en exactamente la posición que establezcas. En las clasificaciones con atributos de desglose, se otorga al usuario que ocupa esa posición en cada segmento.

### Creación de disparadores

Para añadir un disparador, abre la recompensa desde la [página de recompensas](https://app.trophy.so/rewards) y sigue los pasos siguientes.

> [!TIP]
>
> Todos los disparadores de recompensa nuevos se crean como 'Inactivo' para permitir las pruebas antes de implementarlos en producción. El tipo de un disparador solo se puede cambiar mientras está inactivo.

**1. Haz clic en Nuevo activador**

Elige un [tipo de activador](#types-of-triggers).

**2. Configura el activador**

* Para un activador de **Métrica**, elige la métrica y el umbral.
* Para un activador de **Racha**, define la duración de la racha.
* Para un activador de **Logro**, elige el logro.
* Para un activador de **Clasificación**, elige la clasificación y la posición.

**3. Añade filtros de atributos (opcional)**

* Para limitar un activador de **Métrica** a eventos con [atributos de evento personalizados](https://docs.trophy.so/es/features/events.md#custom-event-attributes) específicos, añade uno o más filtros en la sección **Atributos del evento**. Si defines varios filtros de atributos de evento, todos deben coincidir.
* Para limitar cualquier activador a usuarios con [atributos de usuario personalizados](https://docs.trophy.so/es/features/users.md#custom-user-attributes) específicos, añade los atributos y los valores deseados en la sección **Atributos del usuario**.

**4. Guarda y activa**

Cuando estés seguro de que el activador se comportará como esperas, cambia su estado a activo para ponerlo en funcionamiento.

Los activadores también se pueden añadir con la API de administración:

```bash cURL theme={null}
curl -X POST https://admin.trophy.so/v1/rewards/{rewardId}/triggers \
     -H "X-API-KEY: <api-key>" \
     -H "Content-Type: application/json" \
     -d '[
       {
         "type": "metric",
         "metricId": "metric-uuid",
         "metricThreshold": 10,
         "status": "active"
       }
     ]'
```

```typescript Node theme={null}
await trophy.admin.rewards.triggers.create("reward-uuid", [
  {
    type: "metric",
    metricId: "metric-uuid",
    metricThreshold: 10,
    status: "active",
  },
]);
```

```python Python theme={null}
client.admin.rewards.triggers.create(
    reward_id="reward-uuid",
    request=[
        {
            "type": "metric",
            "metric_id": "metric-uuid",
            "metric_threshold": 10,
            "status": "active",
        }
    ],
)
```

```php PHP theme={null}
$trophy->admin->rewards->triggers->create("reward-uuid", [
    [
        'type' => 'metric',
        'metricId' => 'metric-uuid',
        'metricThreshold' => 10,
        'status' => 'active',
    ],
]);
```

```java Java theme={null}
CreateRewardTriggersResponse response = client.admin().rewards().triggers().create(
  "reward-uuid",
  List.of(
    CreateRewardTriggerRequestItem.builder()
      .type(CreateRewardTriggerRequestItemType.METRIC)
      .metricId("metric-uuid")
      .metricThreshold(10)
      .status(CreateRewardTriggerRequestItemStatus.ACTIVE)
      .build()
  )
);
```

```go Go theme={null}
response, err := client.Admin.Rewards.Triggers.Create(
    context.TODO(),
    "reward-uuid",
    []*api.CreateRewardTriggerRequestItem{
        {
            Type: api.CreateRewardTriggerRequestItemTypeMetric,
            MetricId: api.String("metric-uuid"),
            MetricThreshold: api.Int(10),
            Status: api.CreateRewardTriggerRequestItemStatusActive.Ptr(),
        },
    },
)
```

```csharp C# theme={null}
await trophy.Admin.Rewards.Triggers.CreateAsync("reward-uuid", new[]
{
    new CreateRewardTriggerRequestItem
    {
        Type = CreateRewardTriggerRequestItemType.Metric,
        MetricId = "metric-uuid",
        MetricThreshold = 10,
        Status = CreateRewardTriggerRequestItemStatus.Active,
    },
});
```

```ruby Ruby theme={null}
result = client.admin.rewards.triggers.create(
  'reward-uuid',
  [
    {
      type: 'metric',
      metric_id: 'metric-uuid',
      metric_threshold: 10,
      status: 'active'
    }
  ]
)
```

### Cuándo no se otorgan recompensas

Las recompensas solo se otorgan por las acciones que los usuarios realizan después de que un activador esté activo. Esto significa que:

* **Los logros ya completados no otorgan recompensas.** Si un usuario completó un logro antes de que añadieras un activador de logro, no recibe la recompensa.
* **Los logros retroactivos no otorgan recompensas.** Cuando activas o editas un logro, o estableces el `signUpDate` de un usuario, Trophy [completa los logros de los usuarios que ya cumplen los requisitos](https://docs.trophy.so/es/features/achievements.md#backdating-achievements). Estas finalizaciones silenciosas no otorgan recompensas.
* **El progreso anterior no cuenta.** Los activadores de métrica y de racha cuentan desde el momento en que se activó el activador, por lo que el progreso que los usuarios lograron antes no se recompensa.

Las recompensas inactivas y los activadores inactivos detienen la concesión de nuevas recompensas, pero las recompensas ya concedidas aún se pueden canjear. Las recompensas archivadas no se conceden, no se listan ni se canjean.

## Límites de canje

Establece un límite de canje en una recompensa para limitar cuántas veces se puede conceder a cada usuario. Cuando un usuario alcanza el límite, deja de recibir la recompensa.

## Filtros de usuario

Añade filtros de atributos de usuario a una recompensa, o a activadores individuales, para controlar quién puede recibirla. Para recibir una recompensa, un usuario debe cumplir los filtros de la recompensa y los del activador.

## Seguimiento de las recompensas de un usuario

### Recompensas concedidas por un evento

Cuando un [evento de métrica](https://docs.trophy.so/es/api-reference/endpoints/events/submit-a-metric-event.md) o la [finalización de un logro](https://docs.trophy.so/es/api-reference/endpoints/achievements/mark-an-achievement-as-completed.md) concede una recompensa, la respuesta la incluye en el array `rewards`. Tiene el mismo formato que la respuesta del endpoint de recompensas del usuario. Si se repite un evento con la misma [clave de idempotencia](https://docs.trophy.so/es/api-reference/idempotency.md), se devuelve un array vacío.

Úsalo para mostrar un mensaje del tipo "Has obtenido una recompensa" en el mismo momento en que ocurre.

```json Response [expandable] theme={null}
{
  ...,
  "rewards": [
    {
      "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
      "awardedAt": "2026-10-20T09:15:00Z",
      "redeemed": false,
      "redeemedAt": null,
      "reward": {
        "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
        "key": "streak-bonus",
        "name": "Streak bonus",
        "description": null,
        "type": "points",
        "points": 50,
        "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
        "pointsSystemKey": "xp"
      },
      "trigger": {
        "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
        "type": "streak",
        "streakLengthThreshold": 7
      }
    }
  ],
  ...
}
```

Las recompensas concedidas por otras fuentes, como los activadores de clasificación cuando finaliza una ejecución, no se devuelven en las llamadas a la API. Usa el [webhook `reward.awarded`](#webhooks) o el endpoint de recompensas del usuario para encontrarlas.

### Listado de las recompensas de un usuario

Usa el [endpoint de recompensas del usuario](https://docs.trophy.so/es/api-reference/endpoints/users/get-a-users-rewards.md) para listar las recompensas que se han concedido a un usuario. Filtra por `redeemed` para mostrar solo las recompensas pendientes de reclamar, y por rango de fechas para recorrer el historial.

```bash cURL theme={null}
curl --request GET \
  --url "https://api.trophy.so/v1/users/{id}/rewards?redeemed=false" \
  --header 'X-API-KEY: <api-key>'
```

```typescript Node theme={null}
trophy.users.rewards("user-id", {
  redeemed: false,
});
```

```python Python theme={null}
client.users.rewards(
    id="user-id",
    redeemed=False,
)
```

```php PHP theme={null}
$request = new UsersRewardsRequest([
    'redeemed' => false
]);

$trophy->users->rewards("user-id", $request);
```

```java Java theme={null}
UsersRewardsRequest request = UsersRewardsRequest.builder()
      .redeemed(false)
      .build();

List<UserRewardResponse> response = client.users().rewards("user-id", request);
```

```go Go theme={null}
redeemed := false

response, err := client.Users.Rewards(
    "user-id",
    &api.UsersRewardsRequest{
        Redeemed: &redeemed,
    },
)
```

```csharp C# theme={null}
await trophy.Users.RewardsAsync("user-id", new UsersRewardsRequest {
   Redeemed = false
});
```

```ruby Ruby theme={null}
result = client.users.rewards(
  :id => 'user-id',
  :redeemed => false
)
```

```json Response [expandable] theme={null}
[
  {
    "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
    "awardedAt": "2026-10-20T09:15:00Z",
    "redeemed": false,
    "redeemedAt": null,
    "reward": {
      "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
      "key": "welcome-bonus",
      "name": "Welcome bonus",
      "description": "Points for finishing onboarding",
      "type": "points",
      "points": 100,
      "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "pointsSystemKey": "xp"
    },
    "trigger": {
      "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
      "type": "metric",
      "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
      "metricThreshold": 10
    }
  }
]
```

Cada concesión incluye el activador que la originó tal como está configurado actualmente, solo con los campos correspondientes a su tipo actual.

## Canjear recompensas

Cuando un usuario reclame una recompensa en tu producto, llama al [endpoint de canje](https://docs.trophy.so/es/api-reference/endpoints/rewards/redeem-a-reward.md) con la clave de la recompensa y el ID del usuario.

```bash cURL theme={null}
curl -X POST https://api.trophy.so/v1/rewards/welcome-bonus/redeem \
     -H "X-API-KEY: <api-key>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18"
  }
}'
```

```typescript Node theme={null}
trophy.rewards.redeem("welcome-bonus", {
  user: {
    id: "18",
  },
});
```

```python Python theme={null}
client.rewards.redeem(
    key="welcome-bonus",
    user={"id": "18"},
)
```

```php PHP theme={null}
$request = new RewardsRedeemRequest([
    'user' => new UpsertedUser([
        'id' => '18'
    ])
]);

$trophy->rewards->redeem("welcome-bonus", $request);
```

```java Java theme={null}
RedeemRewardRequest request = RedeemRewardRequest.builder()
      .user(
        UpsertedUser.builder()
          .id("18")
          .build()
      )
      .build();

RedeemRewardResponse response = client.rewards().redeem("welcome-bonus", request);
```

```go Go theme={null}
response, err := client.Rewards.Redeem(
    "welcome-bonus",
    &api.RedeemRewardRequest{
        User: &api.UpsertedUser{
            Id: "18",
        },
    },
)
```

```csharp C# theme={null}
var request = new RedeemRewardRequest {
   User = new UpsertedUser {
      Id = "18"
   }
};

await trophy.Rewards.RedeemAsync("welcome-bonus", request);
```

```ruby Ruby theme={null}
result = client.rewards.redeem(
  :key => 'welcome-bonus',
  :user => {
    :id => '18'
  }
)
```

Trophy canjea de una sola vez todas las recompensas otorgadas al usuario que siguen sin canjear, empezando por las más antiguas, y las devuelve en `redemptions`. En las recompensas de puntos, la respuesta también incluye el total de `points` concedidos y cada `leaderboards` donde cambió el rango del usuario.

```json Response [expandable] theme={null}
{
  "reward": {
    "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
    "key": "welcome-bonus",
    "name": "Welcome bonus",
    "description": "Points for finishing onboarding",
    "type": "points",
    "points": 100,
    "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
    "pointsSystemKey": "xp"
  },
  "redemptions": [
    {
      "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
      "awardedAt": "2026-10-20T09:15:00Z",
      "redeemedAt": "2026-10-28T12:00:00Z"
    }
  ],
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 350,
      "added": 100,
      "awards": [...]
    }
  },
  "leaderboards": {}
}
```

El canje sigue funcionando para las recompensas inactivas, pero no para las archivadas ni las eliminadas. La solicitud devuelve un error cuando no puede canjear nada:

* `404` si nunca se otorgó la recompensa al usuario.
* `409` si ya se han canjeado todas las recompensas otorgadas.

Si se alcanza el máximo de puntos a mitad del proceso, se canjean las recompensas que caben y el resto queda sin canjear para que puedas reintentarlo más tarde.

## Webhooks

Trophy envía dos [webhooks](https://docs.trophy.so/es/webhooks/introduction.md) para las recompensas:

* [`reward.awarded`](https://docs.trophy.so/es/webhooks/events/rewards/reward-awarded) se activa cuando se otorga una recompensa a un usuario. Todavía no se ha aplicado nada.
* [`reward.redeemed`](https://docs.trophy.so/es/webhooks/events/rewards/reward-redeemed) se activa cuando se canjea la recompensa, una vez por cada recompensa otorgada. En las recompensas personalizadas, esta es la señal para entregarlas.

Ambos incluyen la recompensa, el canje y el desencadenante que la originó.

```json Webhook reward.awarded — request body [expandable] theme={null}
{
  "type": "reward.awarded",
  "timestamp": "2026-10-20T09:15:00Z",
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "tz": "Europe/London",
    "subscribedToEmails": true,
    "created": "2021-01-01T00:00:00Z",
    "updated": "2021-01-01T00:00:00Z",
    "attributes": {
      "department": "engineering",
      "role": "developer"
    }
  },
  "reward": {
    "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
    "key": "welcome-bonus",
    "name": "Welcome bonus",
    "description": "Points for finishing onboarding",
    "type": "points",
    "points": 100,
    "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
    "pointsSystemKey": "xp"
  },
  "redemption": {
    "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
    "redeemed": false,
    "awardedAt": "2026-10-20T09:15:00Z",
    "redeemedAt": null,
    "trigger": {
      "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
      "type": "achievement",
      "achievementId": "5100fe51-6bce-6j44-b0hs-bddc4e123682"
    }
  }
}
```

```json Webhook reward.redeemed — request body [expandable] theme={null}
{
  "type": "reward.redeemed",
  "timestamp": "2026-10-28T12:00:00Z",
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "tz": "Europe/London",
    "subscribedToEmails": true,
    "created": "2021-01-01T00:00:00Z",
    "updated": "2021-01-01T00:00:00Z",
    "attributes": {
      "department": "engineering",
      "role": "developer"
    }
  },
  "reward": {
    "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
    "key": "welcome-bonus",
    "name": "Welcome bonus",
    "description": "Points for finishing onboarding",
    "type": "points",
    "points": 100,
    "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
    "pointsSystemKey": "xp"
  },
  "redemption": {
    "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
    "redeemed": true,
    "awardedAt": "2026-10-20T09:15:00Z",
    "redeemedAt": "2026-10-28T12:00:00Z",
    "trigger": {
      "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
      "type": "achievement",
      "achievementId": "5100fe51-6bce-6j44-b0hs-bddc4e123682"
    }
  }
}
```

## Recompensas y puntos

Los puntos concedidos al canjear una recompensa se comportan como cualquier otro tipo de puntos:

* Aparecen en el historial de puntos del usuario y en su [resumen de puntos](https://docs.trophy.so/es/api-reference/endpoints/users/get-a-users-points-summary.md).
* Actualizan las [clasificaciones de puntos](https://docs.trophy.so/es/features/leaderboards.md) de ese sistema de puntos.
* No se incluyen en el `points` devuelto por los eventos de métrica ni al completar un Logro, ya que no se concede nada hasta el canje.

## Analíticas de recompensas

Cada recompensa del panel de Trophy incluye analíticas integradas, como:

* Concesiones a lo largo del tiempo
* Canjes a lo largo del tiempo
* Concesiones desglosadas por tipo de activador
* En las recompensas de puntos, una estimación de los puntos otorgados y de los puntos realmente canjeados (incluidos los potenciadores y el máximo de puntos)

Filtra por atributos de usuario para comparar cómo interactúan con una recompensa distintos grupos de usuarios. Los puntos otorgados por las recompensas también aparecen como una fila independiente en el gráfico de fuentes de puntos.

## Obtener soporte

¿Quieres ponerte en contacto con el equipo de Trophy? Escríbenos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.