Vouchers

Vouchers describe the discounts to apply to quotes and subscriptions.

Properties

Name
object
Type
string
Description
Type of object is always voucher.
Allowed values: voucher
Name
id
Type
string
Description
Unique identifier for the voucher.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Name
createdAt
Type
string
Description
Time when the voucher was created.
Example: "2021-02-14T19:38:34Z"
Name
name
Type
string
Description
The voucher's name.
Example: "Black Friday"
Name
priceDiscount
Type
nullable object
Description
The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Name
amount
Type
integer
Description
The discount amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 1
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
priceDiscountPercentage
Type
nullable number
Description
The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Example: 30.12
>= 1
<= 100
Name
recurrence
Type
object
Description
Details on whether and for how long the discounts applied via the voucher recur.
Name
type
Type
string
Description
Whether and how the voucher discount recurs.
Example: "once"
Allowed values: once repeating forever
Name
durationInMonths
Type
nullable integer
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1
Name
redemptions
Type
integer
Description
Number of times the voucher has been redeemed.
Example: 2
Name
retiredReason
Type
nullable string
Description
Label indicating the reason why the voucher is retired.
Allowed values: manualAction expired maxRedemptionsReached unknown
Name
status
Type
string
Description
Allowed values: available retired

Example

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34.0Z",
  "name": "Black Friday",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": 30.12,
  "recurrence": {
    "type": "once",
    "durationInMonths": 1
  },
  "redemptions": 2,
  "retiredReason": null,
  "status": "available"
}

GET/projects/{project}/vouchers

List all vouchers

Returns a list of vouchers. The vouchers returned are sorted by creation date, with the most recently created vouchers appearing first.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Query Parameters

Name
status
Type
array
Description
The status to filter the vouchers by.
Default: available
Name
code
Type
string
Description
The voucher code to filter the vouchers by.
Example: "SummerCode"
Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Responses

Returns a dictionary with an items property that contains an array of vouchers.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type `voucher`.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/vouchers

curl https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "voucher",
      "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "createdAt": "2021-02-14T19:38:34Z",
      "name": "Black Friday",
      "priceDiscount": {
        "amount": 999,
        "currency": "USD"
      },
      "priceDiscountPercentage": 30.12,
      "recurrence": {
        "type": "once",
        "durationInMonths": null
      },
      "redemptions": 2,
      "retiredReason": null,
      "status": "available"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/vouchers

Create a voucher

Creates a new voucher in the specified project.

Body

Name
name
Type
string
required
Description
The voucher's name.
Example: "Monthly Basic 15%"
Name
priceDiscount
Type
nullable object
Description
The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Name
amount
Type
integer
required
Description
The discount amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 1
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
priceDiscountPercentage
Type
nullable number
Description
The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Example: 30.12
>= 1
<= 100
Name
recurrence
Type
object
required
Description
Details on whether and for how long the discounts applied via the voucher recur.
Name
type
Type
string
required
Description
Whether and how the voucher discount recurs.
Example: "once"
Allowed values: once repeating forever
Name
durationInMonths
Type
nullable integer
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Responses

Returns the newly created voucher.

Name
object
Type
string
Description
Type of object is always voucher.
Allowed values: voucher
Name
id
Type
string
Description
Unique identifier for the voucher.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Name
createdAt
Type
string
Description
Time when the voucher was created.
Example: "2021-02-14T19:38:34Z"
Name
name
Type
string
Description
The voucher's name.
Example: "Black Friday"
Name
priceDiscount
Type
nullable object
Description
The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Name
amount
Type
integer
Description
The discount amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 1
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
priceDiscountPercentage
Type
nullable number
Description
The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Example: 30.12
>= 1
<= 100
Name
recurrence
Type
object
Description
Details on whether and for how long the discounts applied via the voucher recur.
Name
type
Type
string
Description
Whether and how the voucher discount recurs.
Example: "once"
Allowed values: once repeating forever
Name
durationInMonths
Type
nullable integer
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1
Name
redemptions
Type
integer
Description
Number of times the voucher has been redeemed.
Example: 2
Name
retiredReason
Type
nullable string
Description
Label indicating the reason why the voucher is retired.
Allowed values: manualAction expired maxRedemptionsReached unknown
Name
status
Type
string
Description
Allowed values: available retired

Request

POST

/projects/{project}/vouchers

curl https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d "{\"name\":\"Monthly Basic 15%\",\"priceDiscount\":{\"amount\":999,\"currency\":\"USD\"},\"priceDiscountPercentage\":null,\"recurrence\":{\"type\":\"once\",\"durationInMonths\":null}}"

Responses

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34Z",
  "name": "Black Friday",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": null,
  "recurrence": {
    "type": "once",
    "durationInMonths": null
  },
  "redemptions": 2,
  "retiredReason": null,
  "status": "available"
}

GET/projects/{project}/vouchers/{voucher}

Retrieve a voucher

Retrieves the details of an existing voucher. You need only supply the unique voucher identifier that was returned upon voucher creation.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
voucher
Type
string
required
Description
The unique identifier for the voucher.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"

Responses

Returns the voucher object.

Name
object
Type
string
Description
Type of object is always voucher.
Allowed values: voucher
Name
id
Type
string
Description
Unique identifier for the voucher.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Name
createdAt
Type
string
Description
Time when the voucher was created.
Example: "2021-02-14T19:38:34Z"
Name
name
Type
string
Description
The voucher's name.
Example: "Black Friday"
Name
priceDiscount
Type
nullable object
Description
The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Name
amount
Type
integer
Description
The discount amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 1
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
priceDiscountPercentage
Type
nullable number
Description
The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Example: 30.12
>= 1
<= 100
Name
recurrence
Type
object
Description
Details on whether and for how long the discounts applied via the voucher recur.
Name
type
Type
string
Description
Whether and how the voucher discount recurs.
Example: "once"
Allowed values: once repeating forever
Name
durationInMonths
Type
nullable integer
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1
Name
redemptions
Type
integer
Description
Number of times the voucher has been redeemed.
Example: 2
Name
retiredReason
Type
nullable string
Description
Label indicating the reason why the voucher is retired.
Allowed values: manualAction expired maxRedemptionsReached unknown
Name
status
Type
string
Description
Allowed values: available retired

Request

GET

/projects/{project}/vouchers/{voucher}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers/{voucher} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34Z",
  "name": "Black Friday",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": 30.12,
  "recurrence": {
    "type": "once",
    "durationInMonths": null
  },
  "redemptions": 2,
  "retiredReason": null,
  "status": "available"
}

POST/projects/{project}/vouchers/{voucher}/retire

Retire a voucher

Retires the voucher. This marks the voucher as no longer redeemable for new subscriptions, but does not affect any active discounts.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
voucher
Type
string
required
Description
The unique identifier for the voucher.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"

Responses

Returns the voucher.

Name
object
Type
string
Description
Type of object is always voucher.
Allowed values: voucher
Name
id
Type
string
Description
Unique identifier for the voucher.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Name
createdAt
Type
string
Description
Time when the voucher was created.
Example: "2021-02-14T19:38:34Z"
Name
name
Type
string
Description
The voucher's name.
Example: "Black Friday"
Name
priceDiscount
Type
nullable object
Description
The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Name
amount
Type
integer
Description
The discount amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 1
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
priceDiscountPercentage
Type
nullable number
Description
The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.
Example: 30.12
>= 1
<= 100
Name
recurrence
Type
object
Description
Details on whether and for how long the discounts applied via the voucher recur.
Name
type
Type
string
Description
Whether and how the voucher discount recurs.
Example: "once"
Allowed values: once repeating forever
Name
durationInMonths
Type
nullable integer
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1
Name
redemptions
Type
integer
Description
Number of times the voucher has been redeemed.
Example: 2
Name
retiredReason
Type
nullable string
Description
Label indicating the reason why the voucher is retired.
Allowed values: manualAction expired maxRedemptionsReached unknown
Name
status
Type
string
Description
Allowed values: available retired

Request

POST

/projects/{project}/vouchers/{voucher}/retire

curl https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers/{voucher}/retire \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34Z",
  "name": "Black Friday",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": 30.12,
  "recurrence": {
    "type": "once",
    "durationInMonths": null
  },
  "redemptions": 2,
  "retiredReason": null,
  "status": "available"
}