Skip to content
KrokoPay
Sign inCreate account

Subscriptions

Recurring revenue with a lifecycle you can read

Create a monthly or yearly price, send your customer to the checkout and follow every subscription through five states. Each change arrives as a webhook event, so your app always knows who has access.

Start charging monthlyRead the subscriptions docs

Test mode runs the full lifecycle without charging anyone.

Members club

Monthly plan · R$49.00/month

sub_5Hn2RtK8wPz4Bq
Current status
Active
Next charge
Dec 3, 2026

Subscription history

  1. Trial started

    Aug 20, 2026
    The customer subscribed with a card. No charge during the trial.subscription.created

  2. First charge paid

    Sep 3, 2026
    Trial over: R$49.00 charged and the subscription is active.charge.paid

  3. Renewed

    Oct 3, 2026
    R$49.00 charged for the new period.subscription.renewed

  4. Renewal declined

    Nov 3, 2026
    The card had insufficient funds. The subscription is past due.subscription.past_due

  5. Payment recovered

    Nov 5, 2026
    The customer updated the card and the renewal was paid.subscription.renewed
Play a scenario: a renewal fails and the subscription recovers, pauses or ends.

The lifecycle

Pick a state and see what moves it

Every subscription is in exactly one state. Choose one to see what it means, how it gets there, where it can go next and which webhook event tells your system.

Products and prices

One product, monthly or yearly

A product holds what you sell. Each price sets an amount and an interval. Offer both on your pricing page and open the checkout for the price the customer picks.

  • Prices are set per product, with a monthly or a yearly interval.
  • The price id goes in the request that creates the subscription.
  • Changing plans mid-period is not part of the current proposal.
Products and prices in the docs

Examples follow a provisional API contract proposal. There is no SDK; requests are plain HTTP.

When a renewal fails

A failed renewal is a state, not a surprise

The subscription moves to past_due and your system gets two events. What happens next is up to the next charge: it is paid and the subscription returns to active, or you pause or cancel it.

  1. charge.failed

    The renewal charge was not paid. The payload carries the failure_code.

  2. subscription.past_due

    The subscription is now past_due. This is your cue to warn the customer.

  3. charge.paid

    A later attempt is paid, for example after the customer updates the card.

  4. subscription.renewed

    The subscription is back to active and the new period starts.

If it is not recovered, you decide: subscription.paused or subscription.canceled.

Warning: Retry policy: to be announced

How many automatic attempts are made, and when, has not been defined yet. Until it is, treat past_due as the signal and do not assume a schedule.
See what is still provisional
subscription.past_dueJSON
{  "id": "evt_3Uu4Vv5Ww6Xx7Y",  "object": "event",  "type": "subscription.past_due",  "api_version": "2026-11-01",  "created_at": "2026-12-03T12:00:12.000Z",  "data": {    "object": {      "id": "sub_5Hn2RtK8wPz4Bq",      "object": "subscription",      "customer_id": "cus_8Hq2LmZr4TxN1a",      "product_id": "prod_6Rj8YdF3nQs5Kv",      "price_id": "price_9Tm4BxW2gLp7Zc",      "status": "past_due",      "method": "card",      "started_at": "2026-09-03T12:00:00.000Z",      "current_period_start": "2026-11-03T12:00:00.000Z",      "current_period_end": "2026-12-03T12:00:00.000Z",      "canceled_at": null,      "cancel_at_period_end": false    }  }}

Provisional API contract proposal — not an operational endpoint.

Questions about subscriptions

Short answers. When something is not defined yet, we say so.

Need a term that is not here yet?

See pricingTalk to us

The first payment can be made with Pix or card at checkout. How Pix renewals reach the customer is still being defined, so the examples on this page renew by card.

The retry policy is to be announced. What is defined today: the subscription moves to past_due and you receive charge.failed and subscription.past_due.

Canceling now ends the subscription immediately. Canceling at the end of the period sets cancel_at_period_end, keeps it active until current_period_end and then sends subscription.canceled.

Yes. A subscription created with a trial starts as trialing and the first charge happens when the trial ends.

Upgrades, downgrades and proration are not part of the current proposal. Today you cancel one subscription and create another with the new price.

Fees are to be announced. The pricing page lists what is defined and what is still provisional.

Start with one monthly price

Create an account, add a product with a price and follow a test subscription through its states before your first real customer.

Start charging monthlyTalk to us