Assinaturas - Pausa e Cupons

Pausar e reativar

Pausar uma assinatura para de gerar faturas para ela até você reativar. As faturas que já existem continuam como estão.

Shell

curl -X PUT https://payments.cefis.com.br/api/v1/subscription/pause \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "subscription": { "id": 205465 } }'

Para reativar, o mesmo corpo em PUT /subscription/unpause. A assinatura volta a active e, se a próxima cobrança venceu durante a pausa, ela passa a ser agora: a fatura sai na próxima rotina de cobrança.

As duas respostas são 201 com { "subscription": { ... } } e disparam o webhook subscription.updated.

Só pausa a assinatura active, overdue ou trial, e só reativa a paused. Nos outros status, a API responde 400 INVALID_STATE_ERROR. Para encerrar uma assinatura, cancele com POST /subscription/cancel.

Cupons

Um cupom dá desconto nas faturas de uma assinatura (type: "subscription") ou num link de pagamento (type: "payment_link").

Criando um cupom

Shell

curl -X POST https://payments.cefis.com.br/api/v1/coupons \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "subscription",
    "name": "Black Friday",
    "code": "BLACK20",
    "percentage": 20,
    "value": 0,
    "duration": 3,
    "max_usages": 100,
    "expiration_date": "2026-11-30"
  }'

Campo	O que faz
`code`	O código que o cliente digita, até 50 caracteres
`percentage`	O desconto em porcentagem do valor da fatura
`value`	Um desconto fixo, em centavos, somado ao da porcentagem (`0` para só a porcentagem)
`duration`	Em quantas faturas da assinatura o desconto vale (opcional; sem ele, em todas)
`max_usages`	Quantas vezes, no total, o cupom pode ser usado (opcional)
`expiration_date`	Até quando o cupom pode ser aplicado (opcional)

O desconto nunca passa do valor da fatura. Para desativar um cupom, PUT /coupons/{id} com "status": "canceled".

Aplicando numa assinatura

Na criação da assinatura, mande os códigos em coupon_codes:

JSON

{
  "customer": { "id": 315968 },
  "plan": { "id": 413 },
  "method": "credit",
  "coupon_codes": ["BLACK20"]
}

Numa assinatura que já existe, aplique pelo id do cupom; o desconto entra nas próximas faturas:

Shell

curl -X POST https://payments.cefis.com.br/api/v1/subscriptions/205465/coupons \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "coupon_id": 77 }'

GET /subscriptions/{id}/coupons lista os cupons da assinatura, com o status de cada um: unused (ainda não usado), using (já deu desconto e ainda restam faturas), used (acabou a duração) ou canceled.
PUT /subscription/coupons/{id}/cancel tira o cupom da assinatura (o id é o do cupom na assinatura, da listagem acima). As faturas que já tiveram desconto não mudam.

Cada desconto aparece como um item negativo na fatura, Cupom <código>.