Vouchers

The Voucher resource

Properties

Name
object
Type
string
Description
Type of object is always 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: 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
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
required
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
restrictions
Type
object
Description
Conditions under which the voucher can be used.
Name
expiresAt
Type
nullable string
required
Description
Time after which the voucher can no longer be used.
Example: 2021-04-14T19:38:34Z
Name
maximumRedemptions
Type
nullable integer
required
Description
Maximum number of times the voucher can be redeemed.
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

Response

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34Z",
  "name": "Monthly Basic 15%",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": 30.12,
  "recurrence": {
    "type": "once"
  },
  "redemptions": 2,
  "restrictions": {
    "expiresAt": "2021-04-14T19:38:34Z"
  },
  "retiredReason": null,
  "status": "available"
}

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

Retrieve a voucher code

Retrieves the details of an existing code for a given voucher.

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
Name
code
Type
string
required
Description
The unique identifier for the code.
Example: voc_0SNlurA049MEWV0Q5vaTJnKoXc1v

Response Schemas

Name
object
Type
string
required
Description
Type of object is always voucherCode.
Name
id
Type
string
required
Description
Unique identifier for the voucher code.
Example: voc_0SNlurA049MEWV0Q5vaTJnKoXc1v
Name
code
Type
string
required
Description
The associated code.
Example: BlackFriday22
Name
createdAt
Type
string
required
Description
Time when the voucher code was created.
Example: 2021-02-14T19:38:34Z
Name
redemptions
Type
integer
required
Description
Number of times the voucher code has been redeemed.
Example: 2
Name
restrictions
Type
object
required
Description
Conditions under which the voucher code can be redeemed.
Name
retiredReason
Type
nullable string
required
Description
Label indicating the reason why the voucher code is retired.
Allowed values: , expired, voucherExpired, maxRedemptionsReached, voucherMaxRedemptionsReached, voucherManuallyRetired
Name
status
Type
string
required
Description
Allowed values: active, inactive, retired
Name
voucher
Type
string
required
Description
Unique identifier of the voucher associated to the voucher code.
Example: vou_0SNlurA049MEWV0h2jfjkdiOdplN

Request

GET

/projects/{project}/vouchers/{voucher}/codes/{code}

curl https://api.gigs.com/projects/{project}/vouchers/{voucher}/codes/{code} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "voucherCode",
  "id": "voc_0SNlurA049MEWV0Q5vaTJnKoXc1v",
  "code": "BlackFriday22",
  "createdAt": "2021-02-14T19:38:34Z",
  "redemptions": 2,
  "restrictions": {
    "firstTimeTransaction": true,
    "maximumRedemptions": null,
    "minimumPrice": {
      "amount": 999,
      "currency": "USD"
    },
    "expiresAt": "2021-04-14T19:38:34Z"
  },
  "retiredReason": null,
  "status": "active",
  "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}

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

List all voucher codes

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

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

Query Parameters

Name
status
Type
array
Description
The status to filter the voucher codes by.
Default: active
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

Response Schemas

Name
object
Type
string
required
Description
Type of object is always list.
Name
items
Type
array
required
Description
List of objects of type `voucherCode`.
Name
moreItemsAfter
Type
nullable string
required
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
required
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/{voucher}/codes

curl https://api.gigs.com/projects/{project}/vouchers/{voucher}/codes \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "voucherCode",
      "id": "voc_0SNlurA049MEWV0Q5vaTJnKoXc1v",
      "code": "BlackFriday22",
      "createdAt": "2021-02-14T19:38:34Z",
      "redemptions": 2,
      "restrictions": {
        "firstTimeTransaction": true,
        "maximumRedemptions": null,
        "minimumPrice": {
          "amount": 999,
          "currency": "USD"
        },
        "expiresAt": "2021-04-14T19:38:34Z"
      },
      "retiredReason": null,
      "status": "active",
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

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

Response Schemas

Name
object
Type
string
required
Description
Type of object is always voucher.
Name
id
Type
string
required
Description
Unique identifier for the voucher.
Example: vou_0SNlurA049MEWV0h2jfjkdiOdplN
Name
createdAt
Type
string
required
Description
Time when the voucher was created.
Example: 2021-02-14T19:38:34Z
Name
name
Type
string
required
Description
The voucher's name.
Example: Monthly Basic 15%
Name
priceDiscount
Type
nullable object
required
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
required
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
required
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1
Name
redemptions
Type
integer
required
Description
Number of times the voucher has been redeemed.
Example: 2
Name
restrictions
Type
object
required
Description
Conditions under which the voucher can be used.
Name
expiresAt
Type
nullable string
required
Description
Time after which the voucher can no longer be used.
Example: 2021-04-14T19:38:34Z
Name
maximumRedemptions
Type
nullable integer
required
Description
Maximum number of times the voucher can be redeemed.
Name
retiredReason
Type
nullable string
required
Description
Label indicating the reason why the voucher is retired.
Allowed values: , manualAction, expired, maxRedemptionsReached, unknown
Name
status
Type
string
required
Description
Allowed values: available, retired

Request

GET

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

curl https://api.gigs.com/projects/{project}/vouchers/{voucher} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34Z",
  "name": "Monthly Basic 15%",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": 30.12,
  "recurrence": {
    "type": "once",
    "durationInMonths": null
  },
  "redemptions": 2,
  "restrictions": {
    "expiresAt": "2021-04-14T19:38:34Z",
    "maximumRedemptions": null
  },
  "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

Response Schemas

Name
object
Type
string
required
Description
Type of object is always list.
Name
items
Type
array
required
Description
List of objects of type `voucher`.
Name
moreItemsAfter
Type
nullable string
required
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
required
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/{project}/vouchers \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "voucher",
      "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "createdAt": "2021-02-14T19:38:34Z",
      "name": "Monthly Basic 15%",
      "priceDiscount": {
        "amount": 999,
        "currency": "USD"
      },
      "priceDiscountPercentage": 30.12,
      "recurrence": {
        "type": "once",
        "durationInMonths": null
      },
      "redemptions": 2,
      "restrictions": {
        "expiresAt": "2021-04-14T19:38:34Z",
        "maximumRedemptions": null
      },
      "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
Name
restrictions
Type
nullable object
Description
Conditions under which the voucher can be used.
Name
expiresAt
Type
nullable string
Description
Time after which the voucher can no longer be used.
Example: 2021-04-14T19:38:34Z
Name
maximumRedemptions
Type
nullable integer
Description
Maximum number of times the voucher can be redeemed.

Path Parameters

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

Response Schemas

Name
object
Type
string
required
Description
Type of object is always voucher.
Name
id
Type
string
required
Description
Unique identifier for the voucher.
Example: vou_0SNlurA049MEWV0h2jfjkdiOdplN
Name
createdAt
Type
string
required
Description
Time when the voucher was created.
Example: 2021-02-14T19:38:34Z
Name
name
Type
string
required
Description
The voucher's name.
Example: Monthly Basic 15%
Name
priceDiscount
Type
nullable object
required
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
required
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
required
Description
For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.
>= 1
Name
redemptions
Type
integer
required
Description
Number of times the voucher has been redeemed.
Example: 2
Name
restrictions
Type
object
required
Description
Conditions under which the voucher can be used.
Name
expiresAt
Type
nullable string
required
Description
Time after which the voucher can no longer be used.
Example: 2021-04-14T19:38:34Z
Name
maximumRedemptions
Type
nullable integer
required
Description
Maximum number of times the voucher can be redeemed.
Name
retiredReason
Type
nullable string
required
Description
Label indicating the reason why the voucher is retired.
Allowed values: , manualAction, expired, maxRedemptionsReached, unknown
Name
status
Type
string
required
Description
Allowed values: available, retired

Request

POST

/projects/{project}/vouchers

curl https://api.gigs.com/projects/{project}/vouchers \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"name\":\"Monthly Basic 15%\",\"priceDiscount\":{\"amount\":999,\"currency\":\"USD\"},\"priceDiscountPercentage\":null,\"recurrence\":{\"type\":\"once\",\"durationInMonths\":null},\"restrictions\":{\"expiresAt\":\"2021-04-14T19:38:34Z\"}}"

Responses

{
  "object": "voucher",
  "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
  "createdAt": "2021-02-14T19:38:34Z",
  "name": "Monthly Basic 15%",
  "priceDiscount": {
    "amount": 999,
    "currency": "USD"
  },
  "priceDiscountPercentage": null,
  "recurrence": {
    "type": "once",
    "durationInMonths": null
  },
  "redemptions": 2,
  "restrictions": {
    "expiresAt": "2021-04-14T19:38:34Z",
    "maximumRedemptions": null
  },
  "retiredReason": null,
  "status": "available"
}