> ## 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 Payment Link

> Atualiza um payment link.

Atualiza campos de um payment link. Apenas os campos enviados são modificados — o resto permanece intacto.

**Importante:** atualizações afetam **apenas cliques futuros**. Sessões já materializadas a partir de cliques anteriores guardam os `line_items` que tinham no momento do clique — é cópia, não referência. Trocar o preço hoje não muda nada do que já está em cobrança; só novos cliques a partir de agora veem o novo preço.

## Autenticação

Mesmo contrato de [POST /v1/payment-links](/api-reference/payment-links/create) — Org API key (`write` ou `admin`) ou API key da plataforma (`platform_admin`) com header `Organization`.

## Parâmetros de caminho

<ParamField path="id" type="string" required>
  ID do payment link, prefixo `plink_`.
</ParamField>

## Attributes

Todos os campos são opcionais. Apenas o que for enviado é atualizado.

<ParamField body="allow_discount_codes" type="boolean">
  Permite cupom no checkout.
</ParamField>

<ParamField body="cancel_url" type="string">
  Envie `null` pra remover.
</ParamField>

<ParamField body="discount_id" type="string">
  Desconto auto-aplicado. `null` remove.
</ParamField>

<ParamField body="is_active" type="boolean">
  Envie `false` para desativar o link. Cliques futuros retornam 404; sessões já materializadas continuam vivas. Envie `true` para reativar.
</ParamField>

<ParamField body="label" type="string">
  Nome interno. Envie `null` pra remover.
</ParamField>

<ParamField body="line_items" type="array">
  Substitui completamente os line items do link. Mesma forma de envio do [POST](/api-reference/payment-links/create). Os antigos são arquivados (cliques futuros não os enxergam mais); sessões já materializadas mantêm os antigos.
</ParamField>

<ParamField body="metadata" type="object">
  Substitui o objeto inteiro. Pra preservar chaves existentes, busque o link primeiro e envie o merge.
</ParamField>

<ParamField body="payment_method_options" type="object">
  Opções por método de pagamento. Substitui o objeto inteiro.

  <Expandable title="Campos de payment_method_options">
    <ParamField body="credit_card" type="object">
      Opções do cartão de crédito.

      <Expandable title="Campos de credit_card">
        <ParamField body="installments" type="object">
          Configuração do parcelamento.

          <Expandable title="Campos de installments">
            <ParamField body="has_interest" type="boolean">
              `true` quando o comprador paga o acréscimo do parcelamento;
              `false` quando o lojista absorve o acréscimo.
            </ParamField>

            <ParamField body="max_count" type="integer">
              Número máximo de parcelas oferecidas (1–12).
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="require_billing_address" type="boolean">
  Endereço de cobrança obrigatório. Boleto sempre exige.
</ParamField>

<ParamField body="require_document" type="boolean">
  Documento (CPF/CNPJ) do comprador obrigatório. Boleto sempre exige.
</ParamField>

<ParamField body="require_phone" type="boolean">
  Telefone do comprador obrigatório.
</ParamField>

<ParamField body="success_url" type="string">
  Envie `null` pra remover.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/payment-links/plink_demo_z2kkA78c" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "label": "Bio Instagram - Atualizado",
      "metadata": {
        "campaign": "spring2026",
        "channel": "instagram"
      },
      "success_url": "https://meusite.com/nova-pagina"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto canônico do payment link. Mesma forma da resposta de [POST /v1/payment-links](/api-reference/payment-links/create).

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "plink_demo_z2kkA78c",
    "object": "payment_link",
    "allow_discount_codes": true,
    "cancel_url": null,
    "created_at": "2026-05-02T18:31:00Z",
    "discount": null,
    "is_active": true,
    "label": "Bio Instagram - Atualizado",
    "line_items": [],
    "livemode": true,
    "metadata": {
      "campaign": "spring2026",
      "channel": "instagram"
    },
    "payment_method_options": {
      "credit_card": {
        "installments": {
          "has_interest": true,
          "max_count": 12
        }
      }
    },
    "require_billing_address": false,
    "require_document": true,
    "require_phone": false,
    "success_url": "https://meusite.com/nova-pagina",
    "updated_at": "2026-05-02T18:35:00Z",
    "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
  }
  ```
</ResponseExample>

## Webhook

Quando a chamada altera algum campo, a Chargefy emite `payment.link.updated`.
O webhook segue o envelope padrão: `data.object` carrega o payment link completo
já atualizado, e `data.previous_attributes` carrega apenas os campos alterados
com o valor anterior.

<ResponseExample>
  ```json Webhook payload theme={}
  {
    "id": "evt_1Nh3kZ8WqX",
    "object": "event",
    "created_at": "2026-05-02T18:35:00Z",
    "data": {
      "object": {
        "id": "plink_demo_z2kkA78c",
        "object": "payment_link",
        "allow_discount_codes": true,
        "cancel_url": null,
        "created_at": "2026-05-02T18:31:00Z",
        "discount": null,
        "is_active": true,
        "label": "Bio Instagram - Atualizado",
        "line_items": [],
        "livemode": true,
        "metadata": {
          "campaign": "spring2026",
          "channel": "instagram"
        },
        "payment_method_options": {
          "credit_card": {
            "installments": {
              "has_interest": true,
              "max_count": 12
            }
          }
        },
        "require_billing_address": false,
        "require_document": true,
        "require_phone": false,
        "success_url": "https://meusite.com/nova-pagina",
        "updated_at": "2026-05-02T18:35:00Z",
        "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
      },
      "previous_attributes": {
        "label": "Bio Instagram - Plano Pro",
        "metadata": {
          "campaign": "spring2026"
        },
        "success_url": "https://meusite.com/obrigado"
      }
    },
    "livemode": true,
    "organization": "org_123",
    "type": "payment.link.updated"
  }
  ```
</ResponseExample>

### Trocar o preço de um link

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/payment-links/plink_demo_z2kkA78c" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "line_items": [
        {
          "price_id": "price_demo_pro_yearly",
          "quantity": 1
        }
      ]
    }'
  ```
</RequestExample>

A partir desse momento, novos cliques abrem checkout com o novo preço. Cliques anteriores (sessões já criadas) seguem com o preço antigo até concluírem ou expirarem.

## Erros comuns

| HTTP  | Razão                                       |
| ----- | ------------------------------------------- |
| `404` | `id` não existe.                            |
| `400` | `line_items` enviado mas vazio ou inválido. |
| `403` | Sem permissão na org dona do link.          |