Este método irá criar uma assinatura e obrigatoriamente retornar o objeto subscription. Se os parâmetros do plano indicarem uma cobrança imediata, o retorno da mesma requisição também irá conter os detalhes da fatura emitida, representada pelo objeto bill. Dentro deste objeto você poderá encontrar informações mais detalhadas sobre o processamento da transação (last_transaction).

Exemplo de requisição

  {
    "plan_id": 12,
    "customer_id": 142,
    "payment_method_code": "credit_card",
    "product_items": [
      { "product_id": 14 }
    ]
  }

Para mais detalhes e possibilidades de customização, consulte abaixo a seção Parâmetros.

Método de pagamento

Para uma lista dos métodos de pagamento disponíveis e seus respectivos códigos, consulte o serviço GET payment_methods.

A plataforma tomará uma ação diferente dependendo do método de pagamento informado através do parâmetro payment_method_code. Caso o método exija, por exemplo, os dados do cartão de crédito do cliente, a plataforma irá verificar se o cliente em questão possui um cartão válido. Se possuir, uma tentativa de cobrança será efetuada. Se não possuir, um e-mail será enviado ao cliente solicitando seus dados de pagamento.

Caso a forma de pagamento não exija nenhum dado adicional, um e-mail será enviado ao cliente. Boletos bancários possuem exatamente este comportamento.

Produtos da assinatura

Por padrão, a lista de itens da nova assinatura herdará as configurações de itens do plano informado via plan_id.

Caso seja necessário, também é possível customizar esta lista de itens no momento da criação da assinatura através do array product_items. Através deste array de objetos é possível definir quais serão os produtos (product_id), quantidades (quantity) e o número de períodos (cycles) onde cada produto deverá será aplicado. Este atributo é especialmente útil para definir condições específicas que fogem das condições normais de precificação que você definiu no plano.

Customização da precificação

Caso o atributo pricing_schema não seja informado no product_item, a plataforma irá assumir a precificação padrão do produto. Se quiser customizar a precificação exclusivamente para esta assinatura, é possível informar o atributo pricing_schema com os parâmetros descritos abaixo. Mais detalhes sobre a precificação de produtos podem ser encontrados neste artigo.

Descontos

Cada produto da assinatura poderá receber um ou mais descontos que serão utilizados no cálculo da geração das faturas. Informe o atributo discounts para product_item. Caso mais de um desconto seja informado para o mesmo produto, os valores serão sempre calculados a partir do valor inicial.

Tratamento de assinaturas com pagamentos rejeitados

Conforme mencionado anteriormente, a plataforma irá retornar a fatura gerada (bill) caso a assinatura possua uma cobrança imediata. Se este retorno possuir uma fatura pendente ("status": "pending") e uma transação rejeitada, você terá as seguintes opções:

• Manter a assinatura ativa e aguardar a retentativa automática da plataforma na data indicada pelo atributo next_attempt.
• Efetuar uma nova tentativa de cobrança através do método POST /charges/{id}/charge. Opcionalmente você poderá informar um novo perfil de pagamento.
• Cancelar a assinatura e a fatura pendente através do método DELETE /subscriptions/{id}?cancel_bills=true.
• Enviar um e-mail com um link para a tela de pagamento da fatura. Este e-mail poderá ser enviado automaticamente pelas notificações da plataforma (cobrança rejeitada) ou se preferir, manualmente através do seu próprio backend. Neste caso, use o endereço contido no atributo url do objeto bill.