Skip to main content
This guide walks through the most common tasks: creating a voucher, activating it, reserving and charging an amount, refunding, and recharging.

​
1. Set up clients and client groups

Start in the Voucher Cloud Admin UI. Client groups organize clients (POS terminals, online shops, etc.) and define which scopes are available to them:
ScopePermission
readRead a single voucher
read-listsRead voucher lists
read-secretsRead voucher code and pin
useActivate, reserve, charge, and cancel
manageCreate and delete vouchers
updateUpdate vouchers
rechargeRecharge a voucher
Create a client group and assign the scopes your integration needs. Then create a client (the entity representing your POS or shop) and assign it to that group.

​
2. Get credentials for your client

The Voucher API uses OAuth 2 client credentials. To get a client_id and client_secret for your client:
  1. In the Admin UI, click the connect button (wifi icon) for your client. A dialog shows a connection pin valid for 30 minutes.
  2. Exchange the pin for credentials using the Client connect endpoint:
POST https://vouchers.api.jtl-software.com/v1/clients/connect
Content-Type: application/json

{
  "pin": "<pin from Admin UI>"
}
The response contains your client_id and client_secret. Store them securely - you will need them to get tokens.

​
3. Get an access token

Use the client credentials flow against the Voucher API’s own token endpoint: 
POST https://vouchers.api.jtl-software.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your client_id>
&client_secret=<your client_secret>
&client_type=my_pos
client_type is optional and used for internal statistics only (max 32 chars). The response is a standard OAuth 2 access token. Pass it in every subsequent request as a Bearer token: 
Authorization: Bearer <access_token>
The Voucher API has its own OAuth 2 server. Tokens from the JTL platform or ERP API are not valid here.

​
4. Create a voucher

POST https://vouchers.api.jtl-software.com/v1/vouchers
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "amount": "10.00",
  "currency": "EUR"
}
Note the id and code from the response - you will need them in the next steps.

​
5. Activate the voucher

Vouchers are created with status inactive by default. An inactive voucher cannot be charged. Activate it after payment: 
PATCH https://vouchers.api.jtl-software.com/v1/vouchers/{id}/status
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "status": "active"
}

​
6. Reserve and charge

Charging a voucher is a two-step process: first reserve an amount (locks the voucher and confirms sufficient balance), then charge it (executes the deduction). Reservation and charge flow The split exists because a customer may combine a voucher with another payment method. The reservation holds the amount while the POS or shop calculates the final split.

​
6.1 Create a reservation

POST https://vouchers.api.jtl-software.com/v1/reservations
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "amount": "5.00",
  "currency": "EUR",
  "code": "<voucher code>"
}
Note the id from the response.
A reservation expires after 30 minutes, or when a new reservation is created for the same voucher.

​
6.2 Charge the reservation

POST https://vouchers.api.jtl-software.com/v1/reservations/{reservation_id}/charge
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "order_number": "ORDER-001"
}
Note the id of the resulting charge object.

​
7. Refund a charge

If a customer returns goods, refund the charge: 
POST https://vouchers.api.jtl-software.com/v1/charges/{charge_id}/refund
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "amount": "5.00",
  "currency": "EUR"
}
The response is a charge object with type: refund.

​
8. Recharge a voucher

Add credit to an existing voucher (for bonus card or store credit use cases): 
POST https://vouchers.api.jtl-software.com/v1/vouchers/recharge
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "code": "<voucher code>",
  "amount": "10.00",
  "currency": "EUR",
  "order_number": "RECHARGE-001"
}
The response is a charge object with type: recharge.
From here, explore the full API reference for all available endpoints and parameters.