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 and 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 invoices

The collection of the invoices is fully under your control. This is an asynchronous process that depends on the way you are handling payments. 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}"

When payment confirmation isn't required, invoices can be configured to be set as paid upon creation.

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"
  }'