> ## Documentation Index > Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a list of vouchers > This call will give you a paginated list of vouchers. ## OpenAPI ````yaml /openapi/voucher.json get /vouchers openapi: 3.0.0 info: version: '1.8' title: JTL-Voucher Cloud API description: >- # Introduction Welcome to the JTL Voucher Cloud API documentation. Here you will find all information to get started using our API in your projects. contact: name: JTL-Software-GmbH url: https://www.jtl-software.com email: info@jtl-software.de servers: - url: https://vouchers.api.jtl-software.com/v1 description: JTL-Voucher Cloud API (Production) - url: https://vouchers-sbx.api.jtl-software.com/v1 description: JTL-Voucher Cloud API (Sandbox) security: - BearerAuth: - read - read-lists - read-secrets - use - manage - update - recharge tags: - name: Vouchers - name: Reservations - name: Charges - name: Clients paths: /vouchers: get: tags: - Vouchers summary: Get a list of vouchers description: This call will give you a paginated list of vouchers. parameters: - in: query name: page required: false schema: type: integer minimum: 1 default: 1 example: 2 - in: query name: per_page required: false schema: type: integer minimum: 1 default: 25 example: 10 - in: query name: filter[created_from] required: false schema: type: string format: RFC3339 example: '2017-07-21T17:32:28+00:00' description: >- Sets a filter to get all entries from this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339 - in: query name: filter[created_to] required: false schema: type: string format: RFC3339 example: 2017-07-21T17:32:28Z+00:00 description: >- Sets a filter to get all entries up to this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339 - in: query name: filter[valid_until_from] required: false schema: type: string format: RFC3339 example: '2017-07-21T17:32:28Z' description: >- Sets a filter to get all entries from this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339 - in: query name: filter[valid_until_to] required: false schema: type: string format: RFC3339 example: '2017-07-21T17:32:28Z' description: >- Sets a filter to get all entries up to this datetime - must be set in RFC3339 format, see https://tools.ietf.org/html/rfc3339 - in: query name: filter[client_id] required: false schema: type: string style: form example: cff8784e5eb28b81ca02a description: Sets a filter to get all entries of this client - in: query name: filter[client.client_group_id] required: false schema: type: string style: form example: da39a3ee5eb28b7392ef5 description: Sets a filter to get all entries of this group - in: query name: filter[code] required: false schema: type: string style: form example: 1A8S-9YSY-6EOB-KVNW description: Sets a filter to get a voucher with this specific code - in: query name: filter[id] required: false schema: type: string style: form example: A37FX description: Sets a filter to get all entries having this voucher id - in: query name: filter[sku] required: false schema: type: string style: form example: JHG75HJG description: Sets a filter to get all entries having this SKU - in: query name: filter[type] required: false schema: type: string enum: - digital - print style: form example: digital description: Sets a filter to get only entries of this type - in: query name: filter[amount] required: false schema: type: string style: form example: '10.53' description: Sets a filter to get all entries having this amount - in: query name: filter[status] required: false schema: type: array items: type: string style: form example: - inactive - active description: Sets a filter to get all entries with this status - in: query name: filter[batch] required: false schema: type: string style: form example: '123' description: Sets a filter to get all entries that belongs to a specific batch - in: query name: filter[remaining_amount] required: false schema: type: boolean style: form example: true description: >- Set to true to get only vouchers that still have credit. Set to false to get vouchers without remaining credit. - in: query name: filter[taxable] required: false schema: type: boolean style: form example: false description: Sets a filter to get only vouchers that are taxable or not - in: query name: filter[tax_rate] required: false schema: type: string style: form example: '19' description: Sets a filter to get only vouchers with this tax rate - in: query name: sort required: false schema: type: array items: type: string enum: - created_at style: form example: - created_at description: >- Sets one or multiple fields to sort the result. Each field can be prefixed by a minus sign (-) to sort descending. responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: data: type: array items: allOf: - type: object properties: id: type: string description: >- A unique custom identifier for this voucher (e.g. a sku). Also used for activation of this voucher. (optional, if not set for this voucher it will be auto generated based on the UI regex settings) maxLength: 255 example: 4ZH83T0ACUUC14CW client_id: type: string description: id of the client that created this voucher readOnly: true example: da39a3ee5eb28b7392ef5 sku: type: string maxLength: 255 description: Optional SKU example: AJHS8675FG batch: type: string maxLength: 30 description: Optional campaign or grouping identifier example: Winter Campaign amount: type: string minLength: 4 maxLength: 9 pattern: ^\d+\.\d{2}$ description: > Amount in the currency of this voucher. Must be send as string in the following pattern: * Up to five digits before the decimal point * The decimal point (.) * Exactly two digits after the decimal point example: '10.53' currency: type: string description: >- The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes minLength: 3 maxLength: 3 example: EUR valid_until: type: string format: RFC3339 readOnly: true description: >- Date until which this voucher is valid and can be redeemed. Calculated based on validity_value and validity_interval on activation. This property will be null if the voucher is inactive. example: '2025-07-21T17:32:28+00:00' validity_value: type: integer description: >- Calculates together with validity_interval the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI) example: 24 validity_interval: type: string enum: - days - weeks - months - years description: >- Calculates together with validity_value the date until which this voucher is valid after activation (if not set this property will be defined by the settings in the UI) example: months status: type: string enum: - active - inactive description: >- The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged. example: active type: type: string enum: - print - digital description: >- Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default. example: digital taxable: type: boolean description: >- Defines if this voucher is a taxable multi purpose voucher example: true default: false tax_rate: type: string description: >- The tax rate for this voucher (only required when taxable is true) example: '19' order_number: type: string description: An optional order number for this voucher example: Order 66 data: type: string description: >- Any additional custom data for this voucher as a JSON string example: '{"foo": "bar"}' created_at: type: string format: RFC3339 readOnly: true description: >- created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339 example: '2017-07-21T17:32:28+00:00' updated_at: type: string format: RFC3339 readOnly: true description: >- updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339 example: '2017-07-21T17:32:28+00:00' - properties: remaining_amount: type: string example: '5.50' description: The remaining amount of this voucher deletable: type: boolean example: true description: >- Indicates if this voucher is deletable as it was not used yet - type: object properties: links: type: object properties: first: type: string maxLength: 255 description: First page link example: http://domain/v1/vouchers?page=1 last: type: string maxLength: 255 description: Last page link example: http://domain/v1/vouchers?page=5 prev: type: string nullable: true maxLength: 255 description: Previous page link example: http://domain/v1/vouchers?page=3 next: type: string nullable: true maxLength: 255 description: Next page link example: http://domain/v1/vouchers?page=2 meta: type: object properties: current_page: type: integer minimum: 1 description: Current page example: 1 per_page: type: integer minimum: 1 description: Limit per page example: 15 from: type: integer minimum: 1 nullable: true description: Start of pagination example: 1 to: type: integer minimum: 1 nullable: true description: Start of pagination example: 15 last_page: type: integer minimum: 1 description: Last page example: 167 total: type: integer minimum: 1 description: Total pages count example: 2500 path: type: string maxLength: 255 description: Current path link example: http://domain/v1/vouchers security: - BearerAuth: - read-lists components: securitySchemes: BearerAuth: type: oauth2 description: > This API uses OAuth 2 with Client Credentials Flow (see: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials). > You can request only a subset of specific scopes for your client, however the available scopes for each client are defined through the client groups in the UI. > Within your token request, you can also send the optional parameter *client_type* (string with a max length of 32 chars). This value is only used for internal statistics. flows: clientCredentials: tokenUrl: https://vouchers.api.jtl-software.com/oauth/token scopes: read: Read single vouchers read-lists: Read voucher lists read-secrets: Read secret voucher information like code and pin use: Use a voucher (activation, reservation, charge and cancel) manage: Create and delete vouchers update: Update vouchers recharge: Recharge a voucher ````