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

# Atualizar um plano

> Altera nome, preço, periodicidade, trial e outros dados de um plano. As mudanças valem só para novas assinaturas.

Esta rota muda a configuração de um plano existente. Ela serve para reajustar o preço de venda, trocar o nome comercial, incluir ou remover um trial e mudar a mensagem ao comprador. Quem já assinou não é afetado: preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Reajuste de preço para novos clientes | Envie `merchantId` e o novo `price` |
| Lançar ou encerrar uma promoção de trial | Envie `trial` com a nova configuração, ou `trial: null` para remover |
| Renomear o plano | Envie `merchantId` e `name` |
| Parar de vender o plano | Use [Alterar status do plano](https://docs.fastpaybrasil.com/referencia/planos/alterar-status.md). O `status` não faz parte desta rota |
| Trocar a imagem do plano | Use [Enviar imagem do plano](https://docs.fastpaybrasil.com/referencia/planos/enviar-imagem.md) |
| Reajustar o preço de quem já assina | Não é possível. A assinatura mantém as condições da contratação. Para mudar, cancele e crie outra assinatura |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil)).
* Tenha o `id` do plano e o `merchantId` dono dele.

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

> [!WARNING]
>
> Editar o plano **não** altera assinaturas existentes. Se você reduzir o preço, os assinantes atuais continuam pagando o valor antigo. Comunique isso ao seu time comercial e de atendimento antes de anunciar um novo preço.

## Parâmetros de caminho

**id** `string` *required*

Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

## Corpo da requisição

Campo obrigatório: `merchantId`. Os demais são opcionais: envie os que quer alterar.

**merchantId** `string` *required*

ID do merchant dono do plano, usado na validação da requisição. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**name** `string`

Nome do plano. Ex.: `Plano Premium Atualizado`.

**price** `number`

Novo preço do plano, em reais. Ex.: `119.9` (R\$ 119,90).

**currency** `string`

Código da moeda. Ex.: `BRL`. Planos cobrados no cartão aceitam apenas `BRL`.

**recurrenceType** `string`

Periodicidade: `weekly` (semanal), `biweekly` (quinzenal), `monthly` (mensal) ou `custom` (intervalo personalizado).

**recurrenceInterval** `integer`

Intervalo da recorrência personalizada, em dias corridos. Ex.: `90` (a cada 90 dias). Usado só quando `recurrenceType` é `custom`. Note que `custom` com `30` não é igual a `monthly`: o mensal mantém o dia do mês, e o `custom` só soma dias.

**endDate** `string`

Data de término do plano (formato `date`). Ex.: `2025-12-31`.

**buyerMessage** `string`

Mensagem exibida ao comprador.

**paymentMethods** `string[]`

Formas de pagamento aceitas. Ex.: `["credit_card"]`.

**trial** `object | null`

Configuração de trial para **novas** assinaturas. Envie `null` para remover o trial do plano.

**propriedades**

**durationDays** `integer`

Duração do trial em dias. Mínimo `1`, máximo `365`.

**isFree** `boolean`

Se o trial é grátis.

**price** `number`

Valor cobrado durante o trial, em reais. Obrigatório quando `isFree` é `false`.

> [!NOTE]
>
> Na criação do plano, `durationDays` e `isFree` são obrigatórios dentro de `trial`. No contrato desta rota, nenhum campo de `trial` é marcado como obrigatório. Para evitar ambiguidade, envie o objeto `trial` completo sempre que alterá-lo.

## Respostas

A resposta `200` traz só o `id` do plano. Para ver o plano com as alterações, chame [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md).

**id** `string`

Identificador único do plano.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Plano atualizado | `{"id": "..."}` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` |

> [!NOTE]
>
> **Para o negócio:** um reajuste feito aqui cria duas tabelas de preço convivendo: a dos assinantes antigos (preço da contratação) e a dos novos (preço atualizado). A Finvia não migra assinantes de preço. Se a sua estratégia exige que todos paguem o novo valor, o caminho é cancelar a assinatura antiga e criar uma nova, com cobrança imediata e um ciclo novo.

## Exemplos por caso de uso

> [tab] Reajuste de preço
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "price": 119.9
> }
> ```

> [tab] Incluir trial grátis
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "trial": { "durationDays": 7, "isFree": true }
> }
> ```

> [tab] Remover trial
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "trial": null
> }
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](https://docs.fastpaybrasil.com/referencia/planos/listar.md) |
| `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |
| Assinantes antigos continuam com o preço anterior | Comportamento documentado: a edição vale só para novas assinaturas | Para migrar alguém, cancele e crie nova assinatura |
| Requisição com `status` não desativa o plano | `status` não faz parte desta rota | Use [Alterar status do plano](https://docs.fastpaybrasil.com/referencia/planos/alterar-status.md) |

```http REST (JSON) theme={null}
PUT /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "name": "Plano Premium Atualizado",
  "price": 119.9,
  "currency": "BRL"
}
```

```bash cURL theme={null}
curl -X PUT "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "name": "Plano Premium Atualizado",
    "price": 119.9,
    "currency": "BRL"
  }'
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(
  'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q',
  {
    method: 'PUT',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      merchantId: '2RhQg9M7ZCg3X3nMb9W1kX8Q',
      name: 'Plano Premium Atualizado',
      price: 119.9,
      currency: 'BRL',
    }),
  },
);

const { id } = await response.json();
// Para conferir as alterações: GET /v1/subscription-plans/{id}
```

```python Python theme={null}
import os

import requests

payload = {
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "name": "Plano Premium Atualizado",
    "price": 119.9,
    "currency": "BRL",
}

response = requests.request(
    "PUT",
    "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'merchantId' => '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    'name' => 'Plano Premium Atualizado',
    'price' => 119.9,
    'currency' => 'BRL',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
              "name": "Plano Premium Atualizado",
              "price": 119.9,
              "currency": "BRL"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("PUT", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "name": "Plano Premium Atualizado",
  "price": 119.9,
  "currency": "BRL"
}
""";

var request = new HttpRequestMessage(HttpMethod.Put, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
	  "name": "Plano Premium Atualizado",
	  "price": 119.9,
	  "currency": "BRL"
	}`)

	req, err := http.NewRequest("PUT", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q")
request = Net::HTTP::Put.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "merchantId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "name" => "Plano Premium Atualizado",
  "price" => 119.9,
  "currency" => "BRL",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Subscription plan not found"
}
```

## Veja também

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Recorrência, trial e status do plano.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Fluxo completo, do cliente à cobrança recorrente.

> [card] [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
>
> Status, renovação, retentativas e cancelamento.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Eventos enviados a cada etapa da assinatura.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Guarde o cartão no cofre antes de criar a assinatura.

> [card] [Alterar status do plano](https://docs.fastpaybrasil.com/referencia/planos/alterar-status.md)
>
> Ative ou desative o plano para novas assinaturas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.