Vouchers and Discounts

Overview

You can use vouchers to apply discounts to new subscriptions and subscription-addons. The voucher needs to be created beforehand and can be applied to one or more subscriptions and subscription add-ons that need the same discount.

Vouchers can be configured to discount the first invoice, every invoice, or all invoices created within a certain time window by configuring their recurrence.

When a voucher is applied to a subscription or a subscription add-on, the resulting discount will be available in the corresponding billing details for as long as it is valid, i.e. retrieving a subscription or subscription add-on will always contain the active discount. If no discount is returned, there's no active discount that will be used for the next invoice.

In order to use vouchers, billing users has to be enabled.

Validity

Once a voucher is created, it can be used as a blueprint that applies the specified discount to all invoices for a subscription or a subscription add-on.

Recurrence types

How the repeating window works for Subscriptions

repeating is time-based, not count-based. The discount applies to every invoice whose creation date falls within the window — it is not a fixed number of billing cycles.

The window is calculated as:

window start  =  date the discount was attached to the subscription
window end    =  window start + durationInMonths  (exclusive)

For example, a user signs up on April 17 for a 30-day plan with a 3-month repeating voucher. The discount window runs April 17 → July 18 (July 18 exclusive, so the last eligible day is July 17). That window covers 4 invoices — not 3:

The number of discounted invoices depends on the billing cycle length relative to the duration window.

Once the recurrence window closes, subsequent invoices reflect full pricing.

Using Vouchers to apply Discounts

Creating a new Voucher

In order to apply a discount for a new subscription or subscription add-on, a voucher needs to be created first.

The voucher can be used once or for every subscription or subscription add-on requiring the same discount. When creating a voucher, you can specify either a fixed discount amount or a percentage discount.

The recurrence indicates the discount validity. See Validity for details on how the repeating window is calculated.

If no existing voucher should be used, a new voucher has to be created.

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Monthly Basic",
    "priceDiscountPercentage": 10,
    "recurrence":{
        "type": "repeating",
        "durationInMonths": 3
    }
  }'

The returned voucher's ID can then be used during subscription, subscription-addon, or quote creation.

Using a Voucher

A voucher can be used to apply discounts to either quotes, subscriptions, or subscription add-ons.

For a new Quote

In order to apply a discount to a quote, a voucher ID needs to be specified during quote creation. The ID of the used voucher is also returned in the created quote.

Note that creating a quote with a voucher does not increase the redemption count of a voucher.

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", 
    "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
  }'

For a new Subscription

To use a discount for a new subscription, a voucher ID needs to be specified in the billing details when creating the 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", 
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", 
    "billing": {
      "discount": {
        "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
      } 
    } 
  }'

For a new Subscription Add-on

To use a discount for a new subscription add-on, a voucher ID needs to be specified in the billing details when creating the subscription add-on.

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionAddons" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "billing": {
      "discount": {
        "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
      } 
    } 
  }'

Retiring a Voucher

A voucher can be retired so that it can no longer be used when creating a subscription.

Retiring a voucher does not have any effect on any subscriptions that are already using it. The response will contain the updated voucher with a retiredReason set and its status updated.

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers/vou_0SNlurA049MEWV0h2jfjkdiOdplN/retire" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json"