Assinar um plano (criar assinatura)

Cria uma assinatura de verdade para um cliente em uma oferta de plano existente. id pode ser o id (uuid) ou o identifier da oferta de plano — mesma resolução usada em GET /offers/{identifier}.

Só aceita cartão de crédito.

A cobrança do cartão é feita no gateway depois da resposta desta requisição: a assinatura retorna com status: DRAFT. O webhook SUBSCRIPTION_CONFIRMED avisa que o gateway aceitou a assinatura — o status continua DRAFT — e ela vira ACTIVE quando a primeira fatura é paga. Se o gateway recusar, o webhook é SUBSCRIPTION_FAILED e o status vira FAILED. Como alternativa aos webhooks, faça polling em GET /subscriptions/{id}.

O header Idempotency-Key é obrigatório. Em caso de timeout, reenvie a requisição com a mesma chave: a resposta original será devolvida sem criar uma segunda assinatura.

Uma assinatura não é cobrada diretamente — cada ciclo cobrado (o primeiro e todas as renovações seguintes) gera uma Transaction própria, a mesma entidade retornada por GET /sales/GET /sales/{identifier}. Ou seja, para acompanhar os pagamentos de uma assinatura ao longo do tempo, use os eventos de transação (TRANSACTION_PAID, TRANSACTION_CANCELED, etc.) e GET /sales filtrando pelo cliente/período — os eventos de assinatura (SUBSCRIPTION_*) informam mudanças de status da assinatura em si, não de cada cobrança individual.

curl -X POST "https://pagpolar-api.creativecode.dev.br/v1/plans/offer/string/subscribe" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "installments": 1,    "customer": {      "name": "Fulano de Tal",      "email": "fulano@exemplo.com",      "document": "12345678909",      "phone": "11999999999"    },    "credit_card": {      "holder_name": "FULANO DE TAL",      "holder_document": "12345678909",      "number": "4111111111111111",      "expiration_month": 12,      "expiration_year": 2030,      "cvv": "123"    },    "buyer_ip": "203.0.113.10"  }'

{
  "data": {
    "id": "f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c",
    "status": "DRAFT",
    "payment_method": "CREDIT_CARD",
    "start_at": null,
    "next_billing_at": null,
    "next_billing_amount": null,
    "total_amount": null,
    "canceled_at": null,
    "created_at": "2026-01-15T12:00:00.000Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "request_id": "string"
  }
}