Skip to main content
POST
Criação de uma nova assinatura

Authorizations

X-Client-Id
string
header
required
X-Api-Key
string
header
required

Body

application/json
name
string
required

Nome da assinatura. Sem statementDescriptor nas configurações, é o texto enviado para a fatura do cartão

Maximum string length: 100
Example:

"Assinatura Premium com Eventos"

merchantId
string<uuid>
required

Identificador do merchant

Example:

"90d64a51-d442-426c-bbf9-b66e000e5576"

customerId
string<uuid>
required

Identificador do cliente

Example:

"b99e159e-27d5-4927-b46e-ae7348f20131"

items
object[]
required

Itens cobrados a cada ciclo. O valor do ciclo é a soma de amount vezes quantity de todos os itens

Minimum array length: 1
recurrence
object
required
paymentMethod
object
required
referenceKey
string

Chave de referência da assinatura no seu sistema. Não pode ser alterada depois da criação

Example:

"SUB-PREMIUM-001"

trial
object

Período de trial (opcional). O nome do campo é endDate. Um campo com outro nome é ignorado sem erro, e a assinatura nasce sem trial e é cobrada conforme startAt

splitRules
object[]

Regras de divisão de valores entre recebedores (opcional). Assinaturas aceitam split só por percentage

cancelAtPeriodEnd
boolean
default:false

Cria a assinatura já com cancelamento agendado. Com true e recurrence.cycles definido, cycles passa a ser o ciclo atual mais um

Example:

false

scheduledCancellationAt
string<date>

Data do cancelamento agendado (YYYY-MM-DD). Exige cancelAtPeriodEnd igual a true e não pode ser anterior a ontem (UTC). Sem esta data, o cancelamento acontece em trial.endDate ou, sem trial, em recurrence.nextDueDate

Example:

"2025-12-31"

scheduledCancellationReason
string

Motivo do cancelamento agendado (opcional)

Example:

"Cliente solicitou cancelamento"

Response

Assinatura criada. Se o primeiro ciclo foi cobrado na criação, lastCycle traz o resultado da cobrança, que pode ter falhado

id
string<uuid>

Identificador da assinatura

Example:

"abecf6d6-153e-4fc9-8222-8be5441de581"

name
string

Nome da assinatura

Example:

"Assinatura Premium com Eventos"

clientId
string<uuid>

Identificador do client

Example:

"567265cb-fa7f-419f-9c1c-8e878dd2faf7"

merchantId
string<uuid>

Identificador do merchant

Example:

"90d64a51-d442-426c-bbf9-b66e000e5576"

customerId
string<uuid>

Identificador do cliente

Example:

"b99e159e-27d5-4927-b46e-ae7348f20131"

referenceKey
string

Chave de referência da assinatura

Example:

"SUB-PREMIUM-001"

currency
string

Moeda da assinatura

Example:

"BRL"

items
object[]
recurrence
object
paymentMethod
object
trial
object

Período de trial. Só vem quando a assinatura foi criada com trial

splitRules
object[]

Regras de divisão de valores entre recebedores. Só vem quando a assinatura tem split

status
enum<string>

Status da assinatura

Available options:
created,
active,
paused,
canceled,
unpaid,
expired,
trialing
Example:

"created"

amount
integer

Valor de cada ciclo em centavos, a soma de amount vezes quantity dos itens

Example:

29900

liveMode
boolean

Indica se a assinatura está em modo de produção

Example:

true

lastCycle
object | null

Último ciclo da assinatura. Sempre presente nas respostas individuais (GET, CREATE, UPDATE), pode ser null se não houver ciclos. Não traz items.

createdAt
string<date-time>
Example:

"2025-07-31T13:36:40.118822Z"

updatedAt
string<date-time>
Example:

"2025-07-31T13:36:40.118822Z"

cancelAtPeriodEnd
boolean

Indica se a assinatura tem cancelamento agendado. Enquanto for true, recurrence.cycles mostra o ciclo atual mais um, e o valor anterior volta quando o agendamento é removido

Example:

true

scheduledCancellationAt
string<date>

Data efetiva do cancelamento agendado (YYYY-MM-DD). Só vem quando cancelAtPeriodEnd é true. Sem data enviada, é trial.endDate ou, sem trial, recurrence.nextDueDate

Example:

"2025-12-31"

scheduledCancellationReason
string

Motivo do cancelamento agendado. Só vem quando foi informado

Example:

"Cliente solicitou cancelamento"