Billing Users

We are currently working on a set of APIs to make billing and payments much easier. In the meantime, this guide aims to provide information on how to set up your own billing and payments for your Gigs API integration.

When should you bill?

Ultimately the decision of when to bill your users is entirely up to you.

Gigs bills your organization for a subscription's entire next period once it renews. The cutoff point for preventing a subscription's renewal is exactly one hour before the end of its current period. Canceling a subscription after this point will result in it remaining active for the whole next period.

As a rule, we generally recommend attempting to collect payment early enough that, in case of payment failure, you can retry collection several times without having to pay the cost of the subscription to Gigs.

As such, your billing logic might look something like this:

Listen for subscription lifecycle events

Use Gigs webhooks to listen for subscription.created and subscription.renewed.

Schedule first collection attempt before next renewal

On receipt of one of the above events, schedule a collection attempt to happen a number of days before the currentPeriod.end timestamp. The exact number you use is, of course, up to you, but we recommend roughly 3-5 days before renewal.

Cancel the subscription prior to the renewal cutoff if payment collection fails

When you have decided that it will not be possible to accept payment, you should cancel the subscription to avoid being charged.

The next possible end timestamp is always provided in the earliestEndAt field and, 1 hour before the renewal, it will change to the end of the following subscription period. Once this has happened it is no longer possible to avoid being charged for the next subscription period. As such, we recommend canceling the subscription at least 2 hours before the renewal occurs. You will likely also want to inform your user that this has happened.

If you wish to be extra cautious, you could choose to cancel the subscription immediately on the first payment failure, and then resume the subscription once payment has been successfully collected. Note that the cutoff point for resuming a subscription is also one hour before the currentPeriod.end timestamp.

Retry collection on payment failures

If the collection attempt succeeds, then simply allow the subscription to renew as normal (or, if you have proactively canceled it, resume the subscription).

Otherwise, retry collection several times over the following days.

You may also wish to take this opportunity to send payment reminders to your users & inform them that their subscription will be canceled if they do not pay.

Start a new subscription if the user pays after the subscription has ended

Sometimes a user is not able to pay for their subscription until after it has already ended. It is not possible to resume an ended subscription. In order for the user to keep their phone number, you must create a new subscription for the same SIM used in the ended one.

You have 60 days to create such a subscription and keep the number before the SIM transitions into a retired state. At this point the phone number is returned to the pool and is no longer recoverable.