Criar plano de assinatura

Endpoint: POST /subscriptions/seller/{seller_id}/plans/

Autenticação: JWT bearer ou chave de API

Cria um novo plano de assinatura vinculado à conta do vendedor. O campo account é definido pelo servidor a partir do parâmetro de rota seller_id — não envie esse campo no corpo. Opcionalmente cria a configuração de notificações aninhada na mesma chamada.

Pré-requisitos

Quem chama precisa estar autenticado contra o vendedor identificado por seller_id.
A conta do vendedor já precisa existir na plataforma.

Parâmetros de rota

string

required

UUID unificado da conta do vendedor que será dona do plano.

Corpo da requisição

string

required

Nome de exibição do plano.

string

required

Descrição longa exibida ao assinante na página pública do plano.

string

required

Valor recorrente em centavos de BRL, como string (ex.: "4990" para R$ 49,90).

array

required

Métodos que o assinante pode escolher. Valores permitidos: credit_card, boleto, pix.

array

Subconjunto de payment_methods em que o vendedor absorve a taxa. Padrão [].

string

required

Cadência de cobrança. Um dos valores weekly, biweekly, monthly, bimonthly, quarterly, semiannual, annual.

string

Timestamp ISO-8601. Omita (ou envie null) para um plano perpétuo.

object

Opcional. Persiste a configuração de notificações associada:

notify_new_payment_link (boolean, padrão true)
days_before_due (integer, anulável) — dias antes do vencimento para notificar.
notify_on_due_date (boolean, padrão true)
days_after_overdue (integer, anulável) — dias após o vencimento para notificar.
notify_payment_confirmed (boolean, padrão true)

Resposta

201 Created. Retorna o plano completo, incluindo os campos somente leitura account, metrics, is_perpetual, created_at, updated_at e o notification_config aninhado.

{
  "id": "8b0e9f4a-2b7d-4f3f-9d8a-1c2e3a4b5c6d",
  "account": "11111111-2222-3333-4444-555555555555",
  "name": "Clube do Café — Mensal",
  "description": "Receba um pacote de 250g por mês.",
  "amount": "4990",
  "payment_methods": ["credit_card", "pix"],
  "payment_methods_no_tax": ["pix"],
  "end_date": null,
  "frequency": "monthly",
  "is_perpetual": true,
  "notification_config": {
    "id": "c0ffee00-0000-0000-0000-000000000000",
    "notify_new_payment_link": true,
    "days_before_due": 3,
    "notify_on_due_date": true,
    "days_after_overdue": 1,
    "notify_payment_confirmed": true
  },
  "metrics": {
    "total_subscribers": 0,
    "active_subscribers": 0,
    "overdue_subscribers": 0,
    "canceled_subscribers": 0,
    "failed_subscribers": 0,
    "paid_subscribers": 0,
    "pending_subscribers": 0
  },
  "created_at": "2026-05-14T12:00:00-03:00",
  "updated_at": "2026-05-14T12:00:00-03:00"
}

Inconsistência conhecida do campo amount: o valor é tanto enviado quanto retornado como string em centavos, diferente da convenção em centavos inteiros adotada em outros endpoints.

Erros

Status	Quando
`400`	Validação falhou — campo obrigatório ausente, `frequency` inválido, método de pagamento inválido etc.
`401`	Token ausente ou inválido.
`403`	Chamador sem vínculo com este vendedor.

Exemplos

curl -X POST https://api.dlpay.cloud/subscriptions/seller/SELLER_ID/plans/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clube do Café — Mensal",
    "description": "Receba um pacote de 250g por mês.",
    "amount": "4990",
    "payment_methods": ["credit_card", "pix"],
    "payment_methods_no_tax": ["pix"],
    "frequency": "monthly",
    "notification_config": {
      "days_before_due": 3,
      "days_after_overdue": 1
    }
  }'

import requests

response = requests.post(
    f"https://api.dlpay.cloud/subscriptions/seller/{seller_id}/plans/",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "Clube do Café — Mensal",
        "description": "Receba um pacote de 250g por mês.",
        "amount": "4990",
        "payment_methods": ["credit_card", "pix"],
        "payment_methods_no_tax": ["pix"],
        "frequency": "monthly",
    },
)
plan = response.json()

const response = await fetch(
  `https://api.dlpay.cloud/subscriptions/seller/${sellerId}/plans/`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Clube do Café — Mensal",
      description: "Receba um pacote de 250g por mês.",
      amount: "4990",
      payment_methods: ["credit_card", "pix"],
      payment_methods_no_tax: ["pix"],
      frequency: "monthly",
    }),
  },
);
const plan = await response.json();

Início

Autenticação e usuários

Vendedores

Vendas

Planos

Contas unificadas

Eventos

Assinaturas

Contas virtuais

Integrações do vendedor

Criar plano de assinatura

Pré-requisitos

Parâmetros de rota

Corpo da requisição

Resposta

Erros

Exemplos

​Pré-requisitos

​Parâmetros de rota

​Corpo da requisição

​Resposta

​Erros

​Exemplos

Pré-requisitos

Parâmetros de rota

Corpo da requisição

Resposta

Erros

Exemplos