Pedidos

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.

{
  "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

string

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

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.

string

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

string

Moeda do pedido, BRL ou USD. Somente leitura.

string | null

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

string | null

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

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.

string

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

integer

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

string | null

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

string | null

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

string | null

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

string

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

string | null

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

string

Tipo do pedido: one_time (compra única) ou subscription (assinatura). Somente leitura.

integer

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

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 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, Preços e Clientes. 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

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.

Fundamentos da API

Objetos

Webhooks e eventos

Objeto completo

Campos do objeto

Criação e alterações

Relacionamentos

Eventos

​Objeto completo

​Campos do objeto

​Criação e alterações

​Relacionamentos

​Eventos

Objeto completo

Campos do objeto

Criação e alterações

Relacionamentos

Eventos