Billing Users
Gigs Billing is a flexible billing engine that you can use to bill your users. When billing is enabled, subscriptions are managed through invoices. These invoices contain the final price to charge, including any taxes and fees, and can be collected using your own payment integration. You have full control over how you handle the collection process.
When to use Billing
We designed Gigs Billing to allow you to:
- Use our billing engine to manage your own payments
- Stay compliant with U.S. tax regulations
- Use Gigs Connect with your preferred payment provider
How Billing works
When a subscription is created or renewed, an invoice is generated for the user. For new subscriptions,
the invoice must be paid to activate the subscription, while for renewals, payment ensures continued service.
You can subscribe to the invoice.finalized
event to trigger
payment processing with your payment provider and notify us upon completion.
Invoices
Invoices represent the amount a user must pay for a subscription period, including any taxes and fees. They are automatically generated for billed subscriptions and can have one of the following statuses:
Status | Description | Possible Actions |
---|---|---|
draft | The invoice is still being generated. | No action required. |
finalized | The invoice is awaiting payment. | Change its status to paid . |
paid | The invoice payment was collected. | No further action. |
voided | The invoice was canceled. | No further action. |
Credit Notes
Credit Notes represent adjustments to a paid invoice. They are commonly used to represent refunds, allowing you to reduce your taxes owed, and reflect them on invoice PDFs. While credit notes can cover the full amount of an invoice, certain taxes and fees may remain non-refundable and still need to be remitted to tax authorities.
Status | Description | Possible Actions |
---|---|---|
issued | The credit note was created. | Change its status to voided . |
voided | The credit note was canceled. | No further action. |
Creating billed subscriptions
Billing is configured at the time your project is created. Once enabled, creating a new subscription will
automatically generate an invoice.
The subscription will remain in the initiated
status until the invoice is paid.
Creating a subscription
curl --request POST \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"sim": "auto",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}'
Subscriptions don't contain references to their invoices, but you can easily find them by
listing invoices filtered by subscription. To find the first
invoice for a subscription, you can also filter by reason
using the value subscriptionCreation
.
Finding the first invoice for a subscription
curl --request GET \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/invoices?subscription=sub_0SNlurA049MEWV2gSfSxi00xlPIi&reason=subscriptionCreation" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
Collecting payments for invoices
The collection of payments for invoices is fully under your control. This is an asynchronous process that depends
on the way you are handling them. Generally, for new subscriptions it's common to collect the initial
payment when the subscription is created, while for renewals you would likely do it in response to
our invoice.finalized
event.
You can distinguish between invoices for new subscriptions and renewals by
checking the reason
property.
After confirming that the payment was successful, you need to mark the invoice as paid in Gigs. This action will trigger the activation process for new subscriptions or prevent the subscription from being ended on renewal.
Marking an invoice as paid
curl --request POST \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25/pay" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
If payment confirmation isn't required, invoices can be configured at the
project level to be marked as paid
upon creation.
Failing to collect funds
When an invoice is finalized
, it is your responsibility to ensure that the payment is collected and the invoice
is marked as paid
. The consequences of not collecting these funds depend on the type of the invoice:
-
For new subscriptions, not collecting the first invoice results in the subscription remaining in the
initiated
status indefinitely, or until it is explicitlyended
. -
For subscription renewals, not collecting the renewal invoice results in the subscription being
ended
just before the next renewal period begins.
In practice, the amount of time available to collect the funds depends on whether the invoice was created at renewal or was configured to be created in advance.
Invoicing users in advance
By default, invoices for subscription renewals are created after the subscription renews. This approach
may result in unrecoverable costs for the renewal period if funds cannot be collected. To mitigate this
risk, you can configure invoices to be created several days before the renewal date. When these invoices
remain unpaid by the renewal time, the subscriptions will not renew and will be ended
instead,
protecting you from potential losses.
Choosing the right invoicing time
When deciding how many days in advance to create invoices, consider the following factors:
- Estimate the average time it takes to collect funds from your users, ensuring that you have ample time to process payments.
- Account for any potential delays, such as unexpected downtime or issues in processing the
invoice.finalized
webhook events.
Crediting existing invoices
You can adjust the amount of a paid invoice by creating a Credit Note. At present, only full-amount credits are supported. To create a credit note, simply specify the invoice you want to credit. Once issued, the credit note will automatically adjust your tax calculations to reflect the reduced revenue.
Creating a credit note
curl --request POST \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25"
}'