SopagueDocs
v3

Criar Plano

POST/v2/recurrences/plans

Cria um novo plano de cobrança recorrente no catálogo da loja.

Cabeçalhos (Headers)

CabeçalhoValorObrigatórioDescrição
AuthorizationBearer <token>SimToken JWT Bearer autenticado
Content-Typeapplication/jsonSimTipo de mídia
Idempotency-Key<guid_ou_string>SimChave para prevenção de duplicidade

Parâmetros

Exemplo de requisição
{
  "externalId": "PLANO-GOLD-01",
  "name": "Plano Premium Mensal",
  "description": "Acesso a todos os recursos",
  "amount": 49.9,
  "currency": "BRL",
  "intervalUnit": "MONTH",
  "intervalCount": 1,
  "billingType": "PREPAID",
  "trialDays": 0,
  "gracePeriodDays": 3,
  "maxRetryAttempts": 3,
  "retryIntervalDays": 1,
  "isPublic": true
}

Resposta (201 Created)

Exemplo de resposta
{
  "id": "f5e4d3c2-1b0a-9f8e-7d6c-5b4a3f2e1d0c",
  "externalId": "PLANO-GOLD-01",
  "name": "Plano Premium Mensal",
  "description": "Acesso a todos os recursos",
  "amount": 49.9,
  "currency": "BRL",
  "intervalUnit": "MONTH",
  "intervalCount": 1,
  "billingType": "PREPAID",
  "trialDays": 0,
  "gracePeriodDays": 3,
  "maxRetryAttempts": 3,
  "retryIntervalDays": 1,
  "isPublic": true,
  "version": 1,
  "status": "ACTIVE",
  "createdOn": "2026-09-09T10:00:00Z",
  "lastModifiedOn": "2026-09-09T10:00:00Z"
}

Próximos Passos

Após cadastrar o plano, utilize o id retornado para:

  • Vincular a Assinaturas Diretas: Utilize este identificador no campo RecurrencePlanId ao Criar Assinatura.
  • Criar Sessões de Checkout Público: Gere links de pagamento compartilháveis informando este plano no campo planId ao Criar Sessão de Checkout.
  • Gerenciar o Catálogo: Consulte todos os planos ativos em Listar Planos ou edite as regras em Atualizar Plano.

Erros

As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.

Ver validações observadas em homologação

Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Idempotency-Key": [
      "The idempotencyKey field is required."
    ]
  },
  "traceId": "00-e21ec07f0a61b9a22aa27e8b3ddb42ff-c121aba64c46fae9-00"
}

Observado em homologação

Requisição com o header Idempotency-Key e corpo JSON vazio; os identificadores na rota são sintéticos.

[
  {
    "tag": "Name",
    "description": "Name é obrigatório."
  },
  {
    "tag": "Amount",
    "description": "Amount deve ser maior que zero."
  }
]

Campos da resposta de erro

A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.