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.

Quotes

Quotes represent the amount a user will likely pay for a subscription period, including any taxes and fees.

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:

Credit Notes

Credit Notes represent adjustments to a paid invoice. They are commonly used to represent refunds or credits, 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.

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.

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. The first invoice is always created synchronously and you can assume it is available after receiving a successful response from the subscriptions endpoint.

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

Previewing taxes and fees

Before creating a subscription, you can create a Quote to preview the total cost of a plan or add-on, including taxes and fees. This way you don't have to create a subscription to see the final price on the invoice.

Depending on plan configuration in your project, you may be required to provide user's address to calculate the taxes. Consult the address field in requirements property of the plan resource.

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/quotes" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "address": "adr_0SuxrVXR1PC5fj4Hrzy5TJp8BBlr"
  }'

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.

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 the next renewal.

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 your integration does not require payment confirmation, you can configure invoices at the project level to automatically transition to paid when they are finalized. If the amount due on an invoice is zero (for example, because of a full discount or a free plan), the invoice automatically transitions to paid as well.

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 marking it as paid depend on the type of the invoice:

• For new subscriptions, not marking the first invoice as paid results in the subscription remaining in the initiated status indefinitely, or until it is explicitly ended.

• For subscription renewals, not marking the renewal invoice as paid will eventually prevent the subscription to renew according the behavior defined by your delinquency settings.

See the next section Invoicing users in advance to know more about the moment the invoice gets created and the section Managing delinquency to know more about what happens when invoices are not paid.

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 at the renewal time, the subscriptions will not renew and will be ended instead, protecting you from potential losses.

Crediting existing invoices

You can adjust the amount of a paid invoice by creating a Credit Note. We support both full and partial Credit Notes, but the sum of all Credit Notes issued for an invoice cannot exceed the original amount.

• For full Credit Notes, specify only the invoice ID.
• For partial Credit Notes, specify the individual line items, fees, and taxes you want to credit by their IDs.

Once issued, the Credit Note will automatically adjust your tax calculations in the background to reflect the reduced revenue.

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",
    "lineItems": [
      {
        "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
        "amount": 100,
        "taxes": [
          {
            "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
            "amount": 10
          }
        ]
      }
    ],
  }'

Managing delinquency

When a renewal invoice is created, your delinquency settings determine what happens if the invoice isn't paid. These settings control when an invoice is considered overdue and what action to take when that happens.

You can configure these two settings at both Project and Subscription levels:

1. Invoice Overdue Days: Indicates how many days after renewal an invoice can be past-due before it becomes overdue. Setting this to 0 means the invoice becomes overdue immediately at renewal, while a higher value (e.g., 3) provides a grace period.

2. Invoice Overdue Action: Indicates what happens immediately to the subscription when a renewal invoice becomes overdue. One of:

   • none: The subscription remains active until the next renewal period.
   • end: The subscription ends immediately.
   • restrict: The subscription's connectivity is restricted immediately.

Renewal invoices are always due at the time of renewal, and will become overdue according to the settings. These settings are configurable at the project level to apply to all subscriptions. For specific subscriptions requiring different behavior, you can override these settings when creating the subscription.

If no action is taken to mark an overdue invoice as paid, subscriptions will be ended according to these settings, or at the very latest by the next renewal period. You can subscribe to the invoice.willBeOverdue event emitted 24h before an invoice becomes overdue or the invoice.overdue events to take any action if needed.

Restricting delinquent subscriptions

When users don't pay their invoices, we can restrict their subscription connectivity to reduce costs and nudge them to pay. Subscriptions in restricted status have a reduced allowance, with no data and only incoming calls and SMS. This prevents further usage while still allowing users to receive important communications.

Once their overdue invoices are paid, the subscriptions will automatically be restored and become active again. You can subscribe to the subscription.restricted and subscription.restored events to take any action when this happens.

As with active subscriptions that have overdue invoices, a restricted subscription is ended automatically at the next renewal if the overdue invoice is still not paid. You can end the subscription earlier if needed.

Period restarts upon subscription restore

When a restricted subscription is restored after paying overdue invoices, a period restart occurs automatically. This provides users with a fresh, full allowance period instead of continuing with the remaining time from the restricted period.

Here's how period restarts work:

1. Current period shortening: The current subscription period ends at the time of restoration.
2. New period creation: A new full period begins immediately, giving users the complete plan benefits they paid for.
3. Credit note creation: A credit note is issued for the original paid invoice with creditTo: userBalance. You must not take any action on this credit note.
4. New invoice creation: A new invoice is created for the fresh period with reason: subscriptionRestore.
5. Automatic payment: The new invoice is immediately paid using the credit from the previous invoice.

This process ensures users receive the full value of their payment while maintaining accurate billing records.

Choosing the right invoicing window

When combining the advance invoicing and delinquency settings, you can create flexible billing scenarios. For example:

• Invoice at renewal and provide a grace period with full connectivity
• Invoice a few days before renewal and provide a grace period with restricted connectivity
• Invoice a few days before renewal and provide no grace period at all

To decide how many days in advance to create invoices, how long the grace period should be and which action to take when an invoice becomes overdue, 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 event webhooks.
• Consider how much time your users typically need to resolve payment issues, balancing generous grace periods against the risk of unpaid service usage.
• Assess how subscription termination impacts your user experience, weighing immediate ending against maintaining restricted connectivity.
• Keep in mind that when a restricted subscription is restored, the renewal anchor shifts to the restore time