> ## 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. # Preços > Objeto price: campos, relacionamentos e eventos. Um `price` guarda as condições comerciais de um produto. No painel da Hubfy, esse cadastro é chamado de **oferta**. Um produto pode ter vários preços. A API permite cadastrar valores, categorias e modelos; a disponibilidade de uma combinação no checkout depende dos meios de venda suportados pela conta. ## 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": "prc_1234567890abcdef", "category": "one_time", "created_at": "2030-01-01T00:00:00.000Z", "currency": "BRL", "is_active": true, "metadata": {}, "min_price": null, "name": "Oferta principal", "object": "price", "package_size": 1, "product": "pro_1234567890abcdef", "renewal_interval_quantity": null, "renewal_interval_unit": null, "scheme": "standard", "setup_fee": null, "setup_fee_enabled": false, "suggested_price": null, "tiers": [], "trial_interval_quantity": null, "trial_interval_unit": null, "unit_amount": 4990, "unit_amount_decimal": null, "updated_at": "2030-01-01T00:00:00.000Z", "usage_aggregation": null, "used": false } ``` ## 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. **category** `string` Categoria: one\_time (compra única), subscription (assinatura), lead\_magnet (gratuito) ou pwyw (cliente escolhe o valor). Valores: `one_time`, `subscription`, `lead_magnet`, `pwyw`. **created\_at** `string` Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. **currency** `string` Moeda do preço: BRL ou USD, sempre em maiúsculas. Valores monetários são expressos em centavos dessa moeda. Valores: `BRL`, `USD`. **is\_active** `boolean` Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram. **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. **min\_price** `integer | null` Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias. **name** `string` Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio. **object** `string` Tipo do objeto retornado. O valor é fixo para este recurso. Sempre `price`. **package\_size** `integer` Quantidade de unidades por pacote. Inteiro maior ou igual a 1. **product** `string` ID do produto ao qual o preço pertence, na mesma conta. Obrigatório na criação; não pode ser alterado. **renewal\_interval\_quantity** `integer | null` Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias. **renewal\_interval\_unit** `string | null` Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade. Valores: `day`, `week`, `month`, `year`, `null`. **scheme** `string` Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total). Valores: `standard`, `package`, `graduated`, `volume`. **setup\_fee** `integer | null` Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado. **setup\_fee\_enabled** `boolean | null` Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup\_fee é obrigatório. **suggested\_price** `integer | null` Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min\_price. Pode ser null. **tiers** `array` Faixas para graduated e volume. Nesses modelos, envie uma lista não vazia, com limites crescentes e a última faixa sem limite (up\_to: null). **Campos de tiers** **flat\_amount** `integer` Valor fixo da faixa, em centavos; inteiro não negativo quando informado. É opcional. **unit\_amount** `integer` Valor por unidade nesta faixa, em centavos; inteiro não negativo. **up\_to** `integer | null` Limite superior inclusivo da faixa. Inteiro positivo; os limites crescem e a última faixa deve usar null (sem limite). **trial\_interval\_quantity** `integer | null` Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste. **trial\_interval\_unit** `string | null` Unidade do período de teste: day, week, month ou year. Pode ser null. Para subscription, envie unidade e quantidade juntas. Valores: `day`, `week`, `month`, `year`, `null`. **unit\_amount** `integer` Valor unitário inteiro, em centavos: 4990 representa R\$ 49,90 em BRL. Deve ser não negativo; lead\_magnet exige zero. **unit\_amount\_decimal** `string | null` Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647. **updated\_at** `string` Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. **usage\_aggregation** `string | null` Agregação de uso: sum (soma), last\_during\_period (último no período), last\_ever (último conhecido) ou max (máximo). Null quando não configurada. Valores: `sum`, `last_during_period`, `last_ever`, `max`, `null`. **used** `boolean` Indica se o preço já foi vinculado a checkout ou pedido. Quando true, somente name, metadata e is\_active podem ser editados pela API. Somente leitura. ## Criação e alterações Na criação, `product` é obrigatório e precisa pertencer à mesma conta. Esse vínculo é imutável. Depois do primeiro uso em checkout ou pedido (`used: true`), apenas `name`, `metadata` e `is_active` podem mudar. Para alterar valor ou recorrência de um preço usado, crie outro preço. Excluir um preço usado o desativa; um preço sem uso pode ser excluído. * `graduated` e `volume`: exigem faixas não vazias, com limites crescentes e última faixa `up_to: null`. * `lead_magnet`: exige `unit_amount: 0`. * `pwyw`: exige `min_price`; se houver `suggested_price`, ele deve ser maior ou igual ao mínimo. * `subscription`: exige `renewal_interval_unit` e `renewal_interval_quantity` positiva. O período de teste deve ter unidade e quantidade juntas. Taxa inicial habilitada exige `setup_fee`. * Valores inteiros recebidos não podem exceder `2147483647`. `package_size` deve ser pelo menos 1. Estas são condições do cadastro. Este recurso não cobra um cliente, cria assinaturas ou registra consumo. Campos omitidos em uma atualização são preservados. `metadata` substitui o objeto inteiro quando enviado. Campos desconhecidos são rejeitados. ## Relacionamentos `product` aponta para [Produtos](https://docs.hubfy.io/api-reference/products/object.md). [Pedidos](https://docs.hubfy.io/api-reference/orders/object.md) referenciam o preço em `price`. A utilização em checkout ou pedido torna `used` verdadeiro e preserva as condições comerciais. ## Eventos * [`price.created`](https://docs.hubfy.io/api-reference/webhooks/price.created) * [`price.updated`](https://docs.hubfy.io/api-reference/webhooks/price.updated) * [`price.deleted`](https://docs.hubfy.io/api-reference/webhooks/price.deleted) O primeiro uso em checkout ou pedido pode mudar `used` e gerar `price.updated`. A inclusão ou remoção do preço pode gerar `product.updated`. Desativar gera `price.updated`. 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.