Referência da API

Criar assinatura

Cria uma Subscription recorrente. Pode ser criada de duas formas:

A partir de uma Offer (modo snapshot): passe offerId e os valores são copiados da Offer (amount, billingCycle, billingCycleCount, maxCycles, trialDays).
Standalone (sem Offer): passe amount e billingCycle manualmente.

Valores monetários em centavos. A chave de API precisa da permissão isInvoiceAvailable.

POST/v2/subscriptions

Snapshot pattern

offerId Quando você cria via offerId, os campos amount/billingCycle/etc são copiados da Offer no momento da criação. Mudanças posteriores na Offer não afetam essa Subscription. Pra mudar valores depois, edite a Subscription diretamente via PATCH.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

customerIdstring (UUID)obrigatório

UUID do Customer dono da assinatura. Precisa pertencer à sua conta e não estar arquivado.

Exemplo: c8a5f4d2-...

offerIdstring (UUID)opcional

UUID da Offer pra puxar snapshot. Se omitido, você precisa informar amount e billingCycle manualmente. A Offer precisa ser recurring — Offers one-time são rejeitadas com 400.

Exemplo: off_xyz789

amountnumber (integer, centavos)opcional

Valor cobrado por ciclo, em centavos. Obrigatório (>=100) se offerId não for informado. Se for, sobrescreve o valor da Offer.

Exemplo: 9900

descriptionstringopcional

Descrição da assinatura. Aparece em cada invoice recorrente gerada por ela. Se omitida, a invoice usa um texto padrão ("Cobrança recorrente — ciclo N").

Exemplo: Assinatura de consultoria — plano mensal

Ciclo de cobrança. Obrigatório se offerId não for informado.

Exemplo: MONTHLY

billingCycleCountnumberopcional

Multiplicador do ciclo. MONTHLY + count=3 = a cada 3 meses. Default: 1.

Exemplo: 1

maxCyclesnumber | nullopcional

Total máximo de cobranças antes da Subscription expirar automaticamente. null ou ausente = infinito.

Exemplo: 12

startedAtstring (ISO 8601)opcional

Data de início da assinatura. Default: agora. Se a Offer tem trialDays > 0, a Subscription nasce em TRIAL com nextBillingAt = startedAt + trialDays.

Exemplo: 2026-06-01T00:00:00.000Z

nextBillingAtstring (ISO 8601)opcional

Data da próxima cobrança. Sobrescreve o cálculo automático (startedAt + trialDays ou startedAt direto).

Exemplo: 2026-06-08T00:00:00.000Z

expiresAtstring (ISO 8601) | nullopcional

Data fixa de fim da Subscription. Tem que ser depois de startedAt. Pode usar junto com maxCycles — o que acontecer primeiro encerra.

Exemplo: 2027-06-01T00:00:00.000Z

daysBeforeDueToBillnumberopcional

Quantos dias antes do vencimento o sistema gera a Invoice. Default: 5. Range: 0 a 60.

Exemplo: 5

daysBeforeDueToNotifynumberopcional

Quantos dias antes do vencimento o sistema envia lembrete ao cliente. Default: 3. Range: 0 a 30.

Exemplo: 3

lateFeeType'NONE' | 'FIXED' | 'PERCENTAGE'opcional

Tipo da multa aplicada em invoices vencidas. Default: NONE.

Exemplo: PERCENTAGE

lateFeeValuenumber (integer)opcional

Valor da multa. Obrigatório se lateFeeType != NONE. Quando FIXED: centavos (ex: 500 = R$ 5,00). Quando PERCENTAGE: percentual cru (ex: 2 = 2%; máximo 100).

Exemplo: 2

interestRatePerMonthnumber (percentual, aceita decimais)opcional

Juros mensais aplicados proporcionalmente por dia de atraso. Percentual cru ao mês (1 = 1% ao mês; aceita frações como 1.5; máximo 100). Default: 0.

Exemplo: 1

trialDaysnumber (integer)opcional

Dias grátis antes da primeira cobrança (standalone). A subscription nasce TRIAL e nextBillingAt = startedAt + trialDays. Via Offer, é copiado da Offer. Default: 0. Máximo: 365.

Exemplo: 7

chargeNowbooleanopcional

Se true, gera a primeira invoice na hora (fora do cron), desde que a subscription não esteja em TRIAL. Útil pra cobrar imediatamente ao criar. Default: false.

Exemplo: false

paymentMethodsInvoicePaymentMethod[]opcional

Métodos de pagamento aceitos nas invoices geradas. Default: ['PIX'].

Exemplo: ["PIX"]

notificationConfigobjectopcional

Configuração de quais notificações enviar e por qual canal. Estrutura livre.

Exemplo: { "onCreate": true, "channels": ["EMAIL"] }

metadataobjectopcional

JSON arbitrário pra anexar dados do seu sistema.

Exemplo: { "source": "import" }

Body da requisição

Content-Type: application/json

JSON

// Modo 1 — A partir de uma Offer (snapshot):
{
  "customerId": "c8a5f4d2-...",
  "offerId": "off_xyz789",
  "lateFeeType": "PERCENTAGE",
  "lateFeeValue": 5,
  "interestRatePerMonth": 1,
  "daysBeforeDueToBill": 5,
  "daysBeforeDueToNotify": 3
}

// Modo 2 — Standalone (sem Offer):
{
  "customerId": "c8a5f4d2-...",
  "amount": 9900,
  "billingCycle": "MONTHLY",
  "billingCycleCount": 1,
  "maxCycles": 12,
  "description": "Assinatura de consultoria — plano mensal",
  "startedAt": "2026-06-01T00:00:00.000Z",
  "lateFeeType": "FIXED",
  "lateFeeValue": 500
}

Respostas

201

Subscription criada. status inicial é TRIAL se há trialDays > 0 da Offer, senão ACTIVE. Valores em centavos.

JSON

{
  "id": "sub_abc123-...",
  "createdByUserId": "u-1234",
  "customerId": "c8a5f4d2-...",
  "offerId": "off_xyz789",
  "status": "ACTIVE",
  "amount": 4900,
  "billingCycle": "MONTHLY",
  "billingCycleCount": 1,
  "maxCycles": 12,
  "currentCycle": 0,
  "nextBillingAt": "2026-06-01T00:00:00.000Z",
  "daysBeforeDueToBill": 5,
  "daysBeforeDueToNotify": 3,
  "paymentMethods": ["PIX"],
  "lateFeeType": "PERCENTAGE",
  "lateFeeValue": 2,
  "interestRatePerMonth": 1,
  "startedAt": "2026-06-01T00:00:00.000Z",
  "expiresAt": null,
  "canceledAt": null,
  "metadata": null,
  "createdAt": "2026-05-26T14:32:01.923Z",
  "updatedAt": "2026-05-26T14:32:01.923Z"
}

400

Validação falhou. Causas comuns: Offer one-time, amount/billingCycle ausente em modo standalone, lateFeeValue ausente com lateFeeType != NONE, daysBeforeDueToBill fora de range.

JSON

{
  "status": 400,
  "error": "Oferta de pagamento unico nao pode virar assinatura"
}

404

Customer ou Offer não encontrados.

JSON

{ "status": 404, "error": "Customer nao encontrado" }

Exemplos

cURL

curl -X POST "https://api.ihubplay.com/v2/subscriptions" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "c8a5f4d2-...",
    "offerId": "off_xyz789",
    "lateFeeType": "PERCENTAGE",
    "lateFeeValue": 2,
    "interestRatePerMonth": 1
  }'

JavaScript

const token = Buffer.from("secret:" + process.env.IHUBGAMES_SECRET_KEY).toString("base64");

// Cria sub padrão R$49/mês sem trial, com multa 2% + 1% ao mês
const res = await fetch("https://api.ihubplay.com/v2/subscriptions", {
  method: "POST",
  headers: { Authorization: `Basic ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    customerId: "c8a5f4d2-...",
    offerId: "off_xyz789",
    lateFeeType: "PERCENTAGE",
    lateFeeValue: 2,             // 2% (percentual cru)
    interestRatePerMonth: 1,     // 1% ao mês (percentual cru)
  }),
});

const sub = await res.json();
console.log("status inicial:", sub.status, "próxima cobrança:", sub.nextBillingAt);