Skip to main content
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.

​
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
Categoria: one_time (compra única), subscription (assinatura), lead_magnet (gratuito) ou pwyw (cliente escolhe o valor).Valores: one_time, subscription, lead_magnet, pwyw.
​
string
Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura.
​
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.
​
boolean
Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram.
​
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.
​
integer | null
Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias.
​
string
Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio.
​
string
Tipo do objeto retornado. O valor é fixo para este recurso.Sempre price.
​
integer
Quantidade de unidades por pacote. Inteiro maior ou igual a 1.
​
string
ID do produto ao qual o preço pertence, na mesma conta. Obrigatório na criação; não pode ser alterado.
​
integer | null
Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias.
​
string | null
Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade.Valores: day, week, month, year, null.
​
string
Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total).Valores: standard, package, graduated, volume.
​
integer | null
Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado.
​
boolean | null
Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup_fee é obrigatório.
​
integer | null
Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min_price. Pode ser null.
​
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).
​
integer | null
Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste.
​
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.
​
integer
Valor unitário inteiro, em centavos: 4990 representa R$ 49,90 em BRL. Deve ser não negativo; lead_magnet exige zero.
​
string | null
Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647.
​
string
Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura.
​
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.
​
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. Pedidos referenciam o preço em price. A utilização em checkout ou pedido torna used verdadeiro e preserva as condições comerciais.

​
Eventos

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.