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

# Create a Price

> Cria um preço.

Cria um recurso `price` para um `product` existente. Campos de valor são
imutáveis depois da criação: para mudar `currency`, `unit_amount`, `type`,
`recurring` ou `product_id`, crie outro preço e desative o antigo.

Use `metadata` para correlacionar o preço com IDs do seu sistema. Qualquer
chave funciona; o objeto inteiro é retornado em todos os webhooks.

## Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o
header `Organization: <organization_id>` apontando para uma organização
conectada ativa.

## Attributes

<ParamField body="currency" type="string" required>
  Código ISO 4217 em minúsculas. Ex.: `brl`, `usd`.
</ParamField>

<ParamField body="recurring" type="object">
  Obrigatório quando `type` é `recurring`. Vem ausente em preços `one_time`.

  <Expandable title="Campos de recurring">
    <ParamField body="interval" type="string" required>
      Valores: `day`, `week`, `month` ou `year`.
    </ParamField>

    <ParamField body="interval_count" type="integer" default="1">
      Quantidade de intervalos entre cobranças.
    </ParamField>

    <ParamField body="trial_period_days" type="integer">
      Trial padrão em dias para assinaturas criadas a partir deste preço.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Se o preço fica disponível para novas vendas.
</ParamField>

<ParamField body="metadata" type="object">
  Objeto livre `string → string`. Padrão `{}`.
</ParamField>

<ParamField body="name" type="string">
  Rótulo interno do preço (ex.: `"Mensal"`, `"Anual"`). Envie `null` para
  deixar vazio.
</ParamField>

<ParamField body="product_id" type="string" required>
  ID do produto (`prod_*`) dono do preço.
</ParamField>

<ParamField body="set_as_default" type="boolean" default="false">
  Quando `true`, atualiza `product.default_price` para apontar para este
  preço imediatamente após a criação.
</ParamField>

<ParamField body="tax_behavior" type="string" default="unspecified">
  `unspecified`, `inclusive` ou `exclusive`.
</ParamField>

<ParamField body="type" type="string" default="one_time">
  `one_time` ou `recurring`.
</ParamField>

<ParamField body="unit_amount" type="integer" required>
  Valor unitário em minor units (centavos). `0` é válido para `one_time` e
  `recurring`.
</ParamField>

<RequestExample>
  ```bash one_time theme={}
  curl -X POST "https://api.chargefy.io/v1/prices" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "currency": "brl",
      "product_id": "prod_123",
      "unit_amount": 4990
    }'
  ```

  ```bash recurring theme={}
  curl -X POST "https://api.chargefy.io/v1/prices" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "currency": "brl",
      "product_id": "prod_123",
      "recurring": {
        "interval": "year"
      },
      "type": "recurring",
      "unit_amount": 99000
    }'
  ```

  ```bash recurring gratuito theme={}
  curl -X POST "https://api.chargefy.io/v1/prices" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "currency": "brl",
      "name": "Gratuito",
      "product_id": "prod_123",
      "recurring": {
        "interval": "month"
      },
      "type": "recurring",
      "unit_amount": 0
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `price` completo. Todo campo declarado pelo DTO público
é sempre retornado; vazio é `null` ou `{}`.

| Campo          | Tipo             | Observação                                                                                   |
| -------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `id`           | `string`         | ID do preço (`price_*`)                                                                      |
| `object`       | `string`         | Sempre `"price"`                                                                             |
| `product`      | `string`         | Produto dono                                                                                 |
| `name`         | `string \| null` | —                                                                                            |
| `type`         | `string`         | `one_time` ou `recurring`                                                                    |
| `currency`     | `string`         | ISO 4217 minúsculo                                                                           |
| `unit_amount`  | `integer`        | Minor units                                                                                  |
| `recurring`    | `object \| null` | `null` em `one_time`; inclui `interval`, `interval_count`, `trial_period_days`, `usage_type` |
| `tax_behavior` | `string`         | `unspecified`/`inclusive`/`exclusive`                                                        |
| `is_active`    | `boolean`        | —                                                                                            |
| `livemode`     | `boolean`        | `true` em produção; `false` em ambiente de teste                                             |
| `metadata`     | `object`         | Eco do `metadata` enviado                                                                    |
| `created_at`   | `string`         | ISO 8601                                                                                     |
| `updated_at`   | `string \| null` | ISO 8601                                                                                     |

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "price_123",
    "object": "price",
    "created_at": "2026-05-16T14:09:27Z",
    "currency": "brl",
    "is_active": true,
    "livemode": true,
    "metadata": {},
    "name": "Anual",
    "product": "prod_123",
    "recurring": {
      "interval": "year",
      "interval_count": 1,
      "trial_period_days": 14,
      "usage_type": "licensed"
    },
    "tax_behavior": "unspecified",
    "type": "recurring",
    "unit_amount": 99000,
    "updated_at": null
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`             | Quando ocorre                                                                                              |
| ------ | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`  | `product_id` ausente; `currency` não é ISO de 3 letras; `unit_amount` negativo ou ausente; `type` inválido |
| `400`  | `invalid_request`  | `recurring.interval` ausente em `recurring`; `recurring.interval_count` não-inteiro ou \< 1                |
| `400`  | `invalid_request`  | `recurring` enviado em `one_time`; `tax_behavior` inválido; `metadata` não-objeto                          |
| `404`  | `resource_missing` | `product_id` não existe nesta organização                                                                  |

## Webhook

A criação dispara [`price.created`](/api-reference/webhooks/price.created)
com o `price` completo em `data.object`.