Vouchers and Discounts

Overview

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

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

When a voucher is applied to a subscription, the resulting discount will be available in the subscription billing details.

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.

If the voucher has a limited recurrence, invoices of a subscription will only use the voucher for the duration of the specified recurrence window. For example, if a voucher is specified to be valid for three months, once the voucher is used for a subscription, all invoices created within those three months will have a discount, regardless of the plan period.

Once the recurrence window is exhausted, invoices won’t have a voucher applied to them anymore and thus will have the full amount.

Using Vouchers to apply Discounts

Creating a new Voucher

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

The voucher can be used once or for every subscription 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. It can be either once for the first invoice, always for every invoice or repeating for all invoices created during a certain time range.

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 or quote creation.

Using a Voucher

A voucher can be used to apply discounts to either quotes or subscriptions.

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

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"