Subscription

Eventos da família subscription.* notificam mudanças no ciclo de vida de assinaturas recorrentes.

Para eventos de cobranças individuais, consulte Subscription Transaction.

Eventos Disponíveis

subscription.active - Assinatura ativada
subscription.trial - Em período de teste
subscription.paused - Assinatura pausada
subscription.past_due - Pagamento em atraso
subscription.completed - Ciclo completo (todas as cobranças realizadas)
subscription.canceled - Assinatura cancelada
subscription.pending_cancellation - Cancelamento pendente

Estrutura do Payload

{
  "customer": {
    "id": "123456",
    "name": "João Silva",
    "email": "[email protected]",
    "document": "12345678900",
    "phone_numbers": [
      {
        "formatted_phone": "+5511999999999",
        "type": null,
        "raw_number": "999999999",
        "area_code": "11",
        "international_dialing_code": "55"
      }
    ],
    "address": {
      "street": "Rua Principal",
      "number": "123",
      "complement": "Apto 45",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postal_code": "01000-000"
    }
  },
  "subscription": {
    "id": "sub_abc123",
    "name": "Plano Mensal Premium",
    "status": "active",
    "created_at": 1705319000,
    "updated_at": 1705405400,
    "canceled_at": null,
    "cancellation_reason": null,
    "charged_times": 3,
    "current_cycle": 1,
    "current_cycle_start": 1705319000,
    "current_cycle_end": 1707911000
  },
  "products": [
    {
      "id": "prod_789",
      "name": "Plano Mensal Premium",
      "type": "subscription_plan",
      "quantity": 1,
      "unit_value": 9900,
      "total_value": 9900,
      "image_url": "https://example.com/product.jpg",
      "offer_type": "main"
    }
  ],
  "payment": {
    "currency": "BRL",
    "total": 9900,
    "discount_value": 0,
    "shipping_value": 0,
    "total_products_value": 9900,
    "payment_method": {
      "type": "credit_card",
      "brand": "visa",
      "last_digits": "1234",
      "expiration_month": "12",
      "expiration_year": "2028"
    },
    "coupons": []
  },
  "charge": {
    "id": "charge_001",
    "created_at": 1705319000,
    "status": "paid",
    "type": "cycle",
    "value": 9900
  }
}

Componentes do Payload

Customer

Campo	Tipo	Descrição
`id`	string \| null	ID único do cliente
`name`	string \| null	Nome completo
`email`	string \| null	E-mail
`document`	string \| null	Documento (CPF/CNPJ) apenas números
`phone_numbers`	array	Lista de telefones
`address`	object	Endereço

Phone Numbers

Campo	Tipo	Descrição
`formatted_phone`	string \| null	Telefone formatado em E.164
`type`	string \| null	Tipo do telefone
`raw_number`	string \| null	Número sem formatação
`area_code`	string \| null	Código de área (DDD)
`international_dialing_code`	string \| null	Código discagem internacional

Address

Campo	Tipo	Descrição
`street`	string \| null	Nome da rua
`number`	string \| null	Número
`complement`	string \| null	Complemento
`neighborhood`	string \| null	Bairro
`city`	string \| null	Cidade
`state`	string \| null	Estado (sigla)
`country`	string \| null	Código ISO 3166-1 alpha-2
`postal_code`	string \| null	CEP

Subscription

Campo	Tipo	Descrição
`id`	string \| null	ID único da assinatura
`name`	string \| null	Nome do plano
`status`	string \| null	Status normalizado
`created_at`	integer \| null	Timestamp de criação
`updated_at`	integer \| null	Timestamp da última atualização
`canceled_at`	integer \| null	Timestamp do cancelamento
`cancellation_reason`	string \| null	Motivo do cancelamento
`charged_times`	integer \| null	Número de cobranças realizadas
`current_cycle`	integer \| null	Ciclo atual
`current_cycle_start`	integer \| null	Timestamp de início do ciclo atual
`current_cycle_end`	integer \| null	Timestamp de fim do ciclo atual

Status Normalizados (SubscriptionStatus)

Valor	Descrição
`trial`	Em período de teste
`active`	Ativa e em dia
`past_due`	Pagamento em atraso
`paused`	Pausada
`canceled`	Cancelada
`completed`	Completa (todas as cobranças realizadas)

Products

Array de Produtos.

Campo	Tipo	Descrição
`id`	string \| null	ID do produto
`name`	string \| null	Nome do produto
`type`	string	Tipo do produto
`quantity`	integer \| null	Quantidade
`unit_value`	integer \| null	Valor unitário em centavos
`total_value`	integer \| null	Valor total em centavos
`image_url`	string \| null	URL da imagem
`offer_type`	string	Tipo de oferta

Product Type (ProductType)

Valor	Descrição
`product`	Produto físico ou digital
`subscription_plan`	Plano de assinatura

Offer Type (OfferType)

Valor	Descrição
`main`	Oferta principal
`order_bump`	Order bump (complemento)

Payment

Campo	Tipo	Descrição
`currency`	string \| null	Código ISO 4217 da moeda
`total`	integer \| null	Valor total em centavos
`discount_value`	integer \| null	Valor do desconto em centavos
`shipping_value`	integer \| null	Valor do frete em centavos
`total_products_value`	integer \| null	Valor total dos produtos em centavos
`payment_method`	object \| null	Método de pagamento
`coupons`	array	Lista de cupons aplicados

Coupon

Campo	Tipo	Descrição
`id`	string \| null	ID do cupom
`code`	string \| null	Código do cupom
`value`	integer \| null	Valor do desconto em centavos
`percentage`	float \| null	Percentual do desconto
`incidence`	string \| null	Incidência do cupom
`incidence_type`	string \| null	Tipo de incidência
`expiration_date`	integer \| null	Timestamp de expiração

Incidence (CouponIncidence)

Valor	Descrição
`total`	Incide sobre o total
`products`	Incide sobre os produtos
`shipping`	Incide sobre o frete

Incidence Type (CouponIncidenceType)

Valor	Descrição
`value`	Desconto em valor fixo
`percentage`	Desconto em percentual

Charge

Campo	Tipo	Descrição
`id`	string \| null	ID da cobrança
`created_at`	integer \| null	Timestamp de criação
`status`	string \| null	Status normalizado
`type`	string \| null	Tipo da cobrança
`value`	integer \| null	Valor em centavos

Status Normalizados (ChargeStatus)

Valor	Descrição
`paid`	Pago
`waiting_payment`	Aguardando pagamento
`expired`	Expirado
`disputed`	Em disputa
`canceled`	Cancelado

Tipos de Cobrança (InvoiceType)

Valor	Descrição
`cycle`	Cobrança recorrente
`upgrade`	Upgrade de plano
`downgrade`	Downgrade de plano
`upsell`	Upsell

Observações

Timestamps são em segundos Unix (epoch)
Valores monetários são sempre em centavos