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

# BenefitUsageHistory

> Histórico de benefício ou desconto aplicado a um pedido

O `BenefitUsageHistory` registra a aplicação de uma gratuidade ou desconto em um [Order](/data-modelling/sales/order). O Order pertence a uma única Company, então a aplicação do benefício ocorre no total do pedido daquela empresa.

## Campos

| Campo                       | Tipo                       | Descrição                                              |
| --------------------------- | -------------------------- | ------------------------------------------------------ |
| `benefitUsageHistoryId`     | `UUID`                     | Identificador único                                    |
| `orderId`                   | `UUID`                     | Pedido em que o benefício foi aplicado                 |
| `customerId`                | `UUID`                     | Cliente beneficiado                                    |
| `fareBenefitCategoryId`     | `UUID?`                    | Categoria de benefício aplicada                        |
| `fareBenefitProgramId`      | `UUID?`                    | Programa de benefício aplicado                         |
| `passengerBenefitRequestId` | `UUID?`                    | Solicitação aprovada que autorizou o uso               |
| `organizationId`            | `UUID`                     | Organização relacionada ao uso                         |
| `companyId`                 | `UUID`                     | Empresa relacionada ao uso                             |
| `routeId`                   | `UUID?`                    | Rota relacionada ao uso, quando aplicável              |
| `tripId`                    | `UUID?`                    | Viagem relacionada ao uso, quando aplicável            |
| `originalAmount`            | `Int`                      | Valor original do pedido em centavos                   |
| `discountAmount`            | `Int`                      | Valor descontado em centavos                           |
| `finalAmount`               | `Int`                      | Valor final do pedido em centavos após o benefício     |
| `discountType`              | `FareBenefitDiscountType?` | Forma de cálculo aplicada                              |
| `discountValue`             | `Int?`                     | Valor do programa aplicado no momento do uso           |
| `status`                    | `BenefitUsageStatus`       | Status do registro de uso                              |
| `usedAt`                    | `DateTime`                 | Data em que o benefício foi aplicado                   |
| `reversedAt`                | `DateTime?`                | Data de reversão do benefício, quando aplicável        |
| `createdBy`                 | `UUID?`                    | Usuário que criou o registro, quando aplicável         |
| `createdAt`                 | `DateTime`                 | Data de criação                                        |
| `updatedBy`                 | `UUID?`                    | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`                 | `DateTime`                 | Data da última atualização                             |

## Relacionamentos

* Relaciona-se com [Order](/data-modelling/sales/order).
* Relaciona-se com [Customer](/data-modelling/identity/customer).
* Relaciona-se com [FareBenefitCategory](/data-modelling/benefits/fare-benefit-category).
* Relaciona-se com [FareBenefitProgram](/data-modelling/benefits/fare-benefit-program).
* Relaciona-se com [PassengerBenefitRequest](/data-modelling/benefits/passenger-benefit-request), quando o uso depende de aprovação prévia.
* Relaciona-se com [Company](/data-modelling/tenant/company), [Route](/data-modelling/operations/route) e [Trip](/data-modelling/operations/trip), quando o contexto da regra exigir.

## Regras de Negócio

* Cada registro representa uma aplicação de benefício no Order.
* O Order pertence a uma única Company; por isso o benefício não precisa ser aplicado diretamente em cada Ticket.
* Se o benefício exigir elegibilidade nominal, ela é validada por `customerId` e `passengerBenefitRequestId`.
* `discountAmount` deve ser maior ou igual a zero.
* `finalAmount` não pode ser menor que zero.
* Benefício de gratuidade deve resultar em `finalAmount = 0`.
* O histórico deve guardar os valores calculados no momento da aplicação, sem depender de recálculo posterior da política.
* Reversões devem marcar `status = REVERSED` e preencher `reversedAt`.
* `createdBy` e `updatedBy` seguem o padrão de auditoria do DEVMOB e registram o usuário responsável pela mutação, quando aplicável.

## Enums

### BenefitUsageStatus

| Valor      | Descrição                    |
| ---------- | ---------------------------- |
| `APPLIED`  | Benefício aplicado ao pedido |
| `REVERSED` | Benefício revertido          |

## Example

```json theme={null}
{
  "benefitUsageHistoryId": "0197f714-4f15-7e39-9ab1-51ff61aac5ea",
  "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "customerId": "0197a7f6-4d36-7c0a-a7cb-54fcb33a3148",
  "fareBenefitCategoryId": "0197f710-b826-77f0-a60b-6c62b9fdd301",
  "fareBenefitProgramId": "0197f711-bf5b-7b90-a45b-577e6269a061",
  "passengerBenefitRequestId": "0197f712-8a7e-7a53-9d28-51f8f3c77d41",
  "organizationId": "0197a801-1690-7590-b3cf-19599b9be3e4",
  "companyId": "0197a801-6a42-79aa-9e56-d3c85148c0fa",
  "routeId": "0197a80c-4204-7b77-9005-48cc23677587",
  "tripId": "0197a80f-2d8f-7710-b243-b67fb477a1c0",
  "originalAmount": 5000,
  "discountAmount": 2500,
  "finalAmount": 2500,
  "discountType": "PERCENTAGE",
  "discountValue": 5000,
  "status": "APPLIED",
  "usedAt": "2026-07-04T13:00:00.000Z",
  "reversedAt": null,
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T13:00:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T13:00:00.000Z"
}
```