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

# Pedidos

> Objeto order: campos, relacionamentos e eventos.

Um `order` registra uma compra e seus vínculos com produto, preço e cliente. A API permite consultar pedidos e ajustar a validade de acesso e os metadados. O pagamento e o estado da assinatura são apenas consultáveis neste recurso.

## Objeto completo

Formato retornado pelas consultas e pelos itens das listagens. Os campos de retorno não são todos editáveis; confira as regras de escrita abaixo.

```json theme={null}
{
  "id": "ord_1234567890abcdef",
  "access_expires_at": null,
  "created_at": "2030-01-01T00:00:00.000Z",
  "currency": "BRL",
  "customer": "cus_1234567890abcdef",
  "effective_order_at": "2030-01-01T00:00:00.000Z",
  "metadata": {},
  "object": "order",
  "order_number": 1001,
  "payment_method": "credit_card",
  "price": "prc_1234567890abcdef",
  "product": "pro_1234567890abcdef",
  "status": "approved",
  "subscription_status": null,
  "type": "one_time",
  "unit_amount": 4990,
  "updated_at": "2030-01-01T00:00:00.000Z"
}
```

## Campos do objeto

**id** `string`

Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes.

**access\_expires\_at** `string | null`

Fim da validade de acesso, em ISO 8601 com fuso. Editável. Null representa ausência de prazo; assinaturas approved ou completed exigem uma data.

**created\_at** `string`

Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura.

**currency** `string`

Moeda do pedido, BRL ou USD. Somente leitura.

**customer** `string | null`

ID do cliente vinculado; pode ser null. Somente leitura.

**effective\_order\_at** `string | null`

Data efetiva da compra em ISO 8601 com fuso. Pode ser null. Somente leitura.

**metadata** `object`

Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use `{}` para limpar. Não aceita null.

**object** `string`

Tipo do objeto retornado. O valor é fixo para este recurso.

Sempre `order`.

**order\_number** `integer`

Número do pedido para exibição. Para chamadas da API, use id. Somente leitura.

**payment\_method** `string | null`

Método de pagamento registrado, como credit\_card ou pix. Pode ser null. Somente leitura.

**price** `string | null`

ID do preço vinculado; pode ser null. Somente leitura.

**product** `string | null`

ID do produto vinculado; pode ser null. Somente leitura.

**status** `string`

Estado registrado: pending, approved, completed, refunded, cancelled, chargeback ou disputed. Somente leitura.

**subscription\_status** `string | null`

Situação da assinatura vinculada: trialing, active, past\_due, paused, cancelled ou expired. Pode ser null. Somente leitura.

**type** `string`

Tipo do pedido: one\_time (compra única) ou subscription (assinatura). Somente leitura.

**unit\_amount** `integer`

Valor do pedido em centavos da moeda indicada em currency. Somente leitura.

**updated\_at** `string`

Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura.

## Criação e alterações

A atualização aceita exclusivamente `access_expires_at` e `metadata`. Alterar a validade de acesso não muda o pagamento, não cancela a assinatura e não provoca uma cobrança. Assinaturas com pedido `approved` ou `completed` não aceitam validade de acesso nula.

Não há criação, exclusão, estorno ou cancelamento de pedidos por este recurso. Consulte [Erros](https://docs.hubfy.io/api-reference/errors.md) para tratar campos não editáveis e recursos indisponíveis.

Campos omitidos em uma atualização são preservados. `metadata` substitui o objeto inteiro quando enviado. Campos desconhecidos são rejeitados.

## Relacionamentos

`product`, `price` e `customer` são IDs de [Produtos](https://docs.hubfy.io/api-reference/products/object.md), [Preços](https://docs.hubfy.io/api-reference/prices/object.md) e [Clientes](https://docs.hubfy.io/api-reference/customers/object.md). Podem ser null. Não são objetos expandidos: consulte as rotas correspondentes. Não há um recurso público independente de assinatura neste contrato.

## Eventos

* [`order.updated`](https://docs.hubfy.io/api-reference/webhooks/order.updated)

Só existe `order.updated` para este recurso. A primeira utilização de um preço também pode gerar `price.updated`. Não há evento público de criação de pedido.

Eventos descrevem mudanças efetivas no objeto público. Repetir uma operação sem alterar o objeto não garante um evento. Confira [entrega e assinatura](https://docs.hubfy.io/api-reference/webhooks/delivery.md).


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