Skip to main content
PATCH
Update a Subscription
Este endpoint faz duas coisas diferentes, e cada requisição pode fazer apenas uma delas.
  • Editar campos. metadata, failure_policy e retry_offsets_days podem ser alterados a qualquer momento.
  • Trocar o plano. Envie product_id, opcionalmente com quantity.
product_id não pode ser combinado com os campos editáveis, e quantity exige product_id. As duas combinações são recusadas com 422, para que nenhuma parte da requisição seja descartada em silêncio. Valor, intervalo e moeda não são editados diretamente — eles vêm do plano e mudam quando o plano muda. Um webhook subscription.updated é disparado em todos os casos. Numa assinatura com Pix Automático, a troca de plano não está disponível: enviar product_id retorna 422 e o plano não muda (PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD quando a assinatura está vinculada a um plano do catálogo). retry_offsets_days é gravado, mas não tem efeito ali, porque o intervalo entre tentativas segue as regras do Pix Automático.

Para quais planos a assinatura pode ir

A assinatura só pode trocar de plano quando já está vinculada a um plano do catálogo. Confira productId antes: quando ele é null, não há troca possível. O alvo precisa ser um plano ativo da mesma família de produtos do atual — productFamilyId indica qual família é essa. Um alvo de outra família, ou um produto que não seja um plano recorrente, é recusado antes de qualquer cobrança ou gravação.

O que acontece, e quando o cliente é cobrado

O ciclo de cobrança tem precedência: mover entre planos de ciclos diferentes é sempre imediato e sempre cobra o valor cheio, qualquer que seja o nível do alvo. Quando a cobrança é recusada, o plano não muda — a requisição falha com 402 e a assinatura fica exatamente como estava. Quando a cobrança não devolve resultado nenhum — um timeout, por exemplo — o desfecho é desconhecido, não uma recusa, e a requisição falha com 409 PLAN_CHARGE_INDETERMINATE. O plano não muda. Repita a mesma troca depois que a cobrança se resolver; antes disso ela é recusada, porque a cobrança pode já ter entrado.

Trocas agendadas

Uma troca agendada para o fim do período fica visível em pendingChange, com o plano de destino, o valor que será cobrado — o plano mais o que for cobrado junto dele — e a data em que passa a valer. O preço é congelado no momento do agendamento, então edições posteriores no plano não alteram o que foi combinado. Para cancelar uma troca agendada, envie product_id com o plano em que a assinatura já está. pendingChange volta a ser null.

Campos da resposta

Erros

Leia a seguir

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

id
string<uuid>
obrigatório

Public subscription id (UUID).

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Corpo

application/json
metadata
object | null
failure_policy
enum<string>
Opções disponíveis:
immediate_cancel,
retry_then_cancel
retry_offsets_days
integer[]
Required array length: 1 - 10 elements
Intervalo obrigatório: 1 <= x <= 30
product_id
string<uuid>

Public id of a catalog product in the same family. Changes the subscription's plan.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
quantity
integer

Quantity for the new plan. Omitted keeps the current one.

Intervalo obrigatório: 1 <= x <= 999999

Resposta

Success

success
boolean
obrigatório
requestId
string
obrigatório
data
object
obrigatório