# Vouchers ## The Voucher object Vouchers describe the discounts to apply to quotes and subscriptions. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `voucher`. | | `id` | string | Yes | Unique identifier for the voucher. | | `createdAt` | string | Yes | Time when the voucher was created. | | `name` | string | Yes | The voucher's name. | | `priceDiscount` | object,null | Yes | The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `priceDiscountPercentage` | number,null | Yes | The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `recurrence` | object | Yes | Details on whether and for how long the discounts applied via the voucher recur. | | `redemptions` | integer | Yes | Number of times the voucher has been redeemed. | | `retiredReason` | null | manualAction | expired | maxRedemptionsReached | unknown | Yes | Label indicating the reason why the voucher is retired. | | `status` | available | retired | Yes | | --- ## List all vouchers `GET /projects/{project}/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 | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `status` | string[] | No | The status to filter the vouchers by. | | `code` | string | No | The voucher code to filter the vouchers by. | | `after` | string | No | 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. | | `before` | string | No | 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. | | `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. | ### Responses #### 200 — Returns a dictionary with an items property that contains an array of vouchers. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `voucher`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | #### 403 — The authenticated user doesn't have permissions to perform the request. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Create a voucher `POST /projects/{project}/vouchers` Creates a new voucher in the specified project. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | Yes | The voucher's name. | | `priceDiscount` | object,null | No | The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `priceDiscountPercentage` | number,null | No | The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `recurrence` | object | Yes | Details on whether and for how long the discounts applied via the voucher recur. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Responses #### 201 — Returns the newly created voucher. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `voucher`. | | `id` | string | Yes | Unique identifier for the voucher. | | `createdAt` | string | Yes | Time when the voucher was created. | | `name` | string | Yes | The voucher's name. | | `priceDiscount` | object,null | Yes | The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `priceDiscountPercentage` | number,null | Yes | The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `recurrence` | object | Yes | Details on whether and for how long the discounts applied via the voucher recur. | | `redemptions` | integer | Yes | Number of times the voucher has been redeemed. | | `retiredReason` | null | manualAction | expired | maxRedemptionsReached | unknown | Yes | Label indicating the reason why the voucher is retired. | | `status` | available | retired | Yes | | #### 403 — The authenticated user doesn't have permissions to perform the request. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Retrieve a voucher `GET /projects/{project}/vouchers/{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 | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `voucher` | string | Yes | The unique identifier for the voucher. | ### Responses #### 200 — Returns the voucher object. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `voucher`. | | `id` | string | Yes | Unique identifier for the voucher. | | `createdAt` | string | Yes | Time when the voucher was created. | | `name` | string | Yes | The voucher's name. | | `priceDiscount` | object,null | Yes | The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `priceDiscountPercentage` | number,null | Yes | The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `recurrence` | object | Yes | Details on whether and for how long the discounts applied via the voucher recur. | | `redemptions` | integer | Yes | Number of times the voucher has been redeemed. | | `retiredReason` | null | manualAction | expired | maxRedemptionsReached | unknown | Yes | Label indicating the reason why the voucher is retired. | | `status` | available | retired | Yes | | #### 403 — The authenticated user doesn't have permissions to perform the request. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Retire a voucher `POST /projects/{project}/vouchers/{voucher}/retire` Retires the voucher. This marks the voucher as no longer redeemable for new subscriptions, but does not affect any active discounts. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `voucher` | string | Yes | The unique identifier for the voucher. | ### Responses #### 200 — Returns the voucher. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `voucher`. | | `id` | string | Yes | Unique identifier for the voucher. | | `createdAt` | string | Yes | Time when the voucher was created. | | `name` | string | Yes | The voucher's name. | | `priceDiscount` | object,null | Yes | The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `priceDiscountPercentage` | number,null | Yes | The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage. | | `recurrence` | object | Yes | Details on whether and for how long the discounts applied via the voucher recur. | | `redemptions` | integer | Yes | Number of times the voucher has been redeemed. | | `retiredReason` | null | manualAction | expired | maxRedemptionsReached | unknown | Yes | Label indicating the reason why the voucher is retired. | | `status` | available | retired | Yes | | #### 403 — The authenticated user doesn't have permissions to perform the request. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | ---