> ## 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.

# Update a Product

> Atualiza um produto.

Atualiza um `product` com semântica de **merge**: campos ausentes ficam como
estão; envie `null` para limpar campos opcionais. `metadata`, quando enviado,
substitui o objeto inteiro.

A resposta direta **não** carrega diff; quem precisa de diff lê o webhook
[`product.updated`](/api-reference/webhooks/product.updated).

## 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.

## Parâmetros de caminho

<ParamField path="id" type="string" required>
  ID do produto (`prod_*`).
</ParamField>

## Attributes

Todos os campos são opcionais.

<ParamField body="default_price_id" type="string \| null">
  Aponta o `default_price_id` para outro preço existente do mesmo produto.
  Envie `null` para limpar.
</ParamField>

<ParamField body="description" type="string \| null">
  Nova descrição. Envie `null` para limpar.
</ParamField>

<ParamField body="image_url" type="string \| null">
  Nova imagem. Use a URL retornada por
  [`POST /v1/files`](/api-reference/files/create) com
  `purpose=product_image`. Envie `null` para limpar. URLs externas não são
  aceitas.
</ParamField>

<ParamField body="is_active" type="boolean">
  `false` tira o produto de novos fluxos de compra. `true` reativa.
</ParamField>

<ParamField body="is_tax_applicable" type="boolean">
  Ajusta a flag tributável.
</ParamField>

<ParamField body="metadata" type="object">
  Substitui completamente o `metadata` atual quando enviado.
</ParamField>

<ParamField body="name" type="string">
  Novo nome. Quando enviado, não pode ser vazio.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/products/prod_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "default_price_id": "price_456",
      "name": "Plano Pro Plus"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `product` completo (mesmo shape de
[`GET /v1/products/:id`](/api-reference/products/get#resposta)).

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "prod_123",
    "object": "product",
    "created_at": "2026-05-16T14:09:27Z",
    "default_price": "price_456",
    "description": "Acesso completo",
    "image_url": null,
    "is_active": true,
    "is_tax_applicable": true,
    "livemode": true,
    "metadata": {
      "reference_id": "sku_pro"
    },
    "name": "Plano Pro Plus",
    "prices": [
      {
        "id": "price_456",
        "object": "price",
        "created_at": "2026-05-16T14:30:00Z",
        "currency": "brl",
        "is_active": true,
        "livemode": true,
        "metadata": {},
        "name": "Anual",
        "product": "prod_123",
        "recurring": {
          "interval": "year",
          "interval_count": 1,
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "tax_behavior": "unspecified",
        "type": "recurring",
        "unit_amount": 99000,
        "updated_at": null
      }
    ],
    "updated_at": "2026-05-16T15:02:10Z"
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`             | Quando ocorre                                                                                                                        |
| ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_request`  | `name` enviado vazio; `is_tax_applicable`/`is_active` não-boolean; `metadata` não-objeto; `default_price_id` não pertence ao produto |
| `400`  | `invalid_request`  | `image_url` não aponta para um `file` ativo de `purpose=product_image` da organização                                                |
| `404`  | `resource_missing` | Produto não existe nesta organização                                                                                                 |

## Webhook

A atualização dispara [`product.updated`](/api-reference/webhooks/product.updated)
com o `product` completo em `data.object` e o diff em `data.previous_attributes`.