Vouchers API Quickstart - JTL Developer Documentation

This guide walks you through the complete voucher lifecycle using the Vouchers API. By the end, you’ll have:

Created a voucher
Activated it after payment
Reserved and charged part of its balance
Refunded the charge
Recharged the voucher with additional credit

1. Set up Clients and Client Groups

Before your application can access the Vouchers API, it must be registered as a client. Start in the Voucher Cloud Admin UI. A client group defines the permissions available to one or more clients, such as POS terminals or online shops.

Scope	Permission
`read`	Read a single voucher
`read-lists`	Read voucher lists
`read-secrets`	Read voucher code and pin
`use`	Activate, reserve, charge, and cancel
`manage`	Create and delete vouchers
`update`	Update vouchers
`recharge`	Recharge a voucher

Create a client group with the scopes your integration requires, then create a client and assign it to that group.

2. Connect your Client

Each client needs OAuth credentials before it can authenticate with the API. In the Admin UI:

Select the Connect button (Wi-Fi icon) for your client.
Copy the generated connection PIN. The PIN is valid for 30 minutes.

Exchange the PIN for OAuth credentials:

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 both securely, as you’ll use them to request access tokens.

3. Request an Access Token

Use the OAuth 2 Client Credentials flow to get an access token:

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). Include the returned access token in the Authorization header of every subsequent request:

Authorization: Bearer <access_token>

The Vouchers API uses its own OAuth server. Access tokens issued by the JTL Platform or ERP API cannot be used with the Vouchers API.

4. Create a Voucher

Create a voucher with an initial balance.

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

{
  "amount": "10.00",
  "currency": "EUR"
}

Save the returned voucher id and code. You’ll use them throughout the remaining steps.

5. Activate the Voucher

New vouchers are created with the inactive status and cannot be redeemed until they are activated. Typically, activation happens after the customer has completed payment.

PATCH https://vouchers.api.jtl-software.com/v1/vouchers/{id}/status
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "status": "active"
}

6. Redeem a Voucher

Redeeming a voucher consists of two operations:

Reserve the amount to verify that sufficient balance is available.
Charge the reservation to deduct the reserved amount from the voucher.

This two-step process allows a voucher to be combined with other payment methods while the final order total is calculated.

Create a Reservation

Reserve an amount against the voucher. This locks the voucher and confirms sufficient balance.

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>"
}

Save the returned reservation id.

Reservations expire after 30 minutes. Creating a new reservation for the same voucher automatically replaces the existing one.

Charge the Reservation

Execute the deduction against 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"
}

Save the returned charge id, which you’ll use if the charge needs to be refunded.

7. Refund a Charge

If an order is cancelled or returned, refund all or part of the original 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 returns a new charge with type: refund.

8. Recharge a Voucher

You can add additional credit to an existing voucher, for example as store credit or part of a loyalty programme.

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 returns a new charge with type: recharge.

What’s Next?

Error Codes

Reference for Vouchers API error codes and their meanings.

Voucher API Reference

Full endpoint reference for all Vouchers API operations and parameters.

​1. Set up Clients and Client Groups

​2. Connect your Client

​3. Request an Access Token

​4. Create a Voucher

​5. Activate the Voucher

​6. Redeem a Voucher

​Create a Reservation

​Charge the Reservation

​7. Refund a Charge

​8. Recharge a Voucher

​What’s Next?

Error Codes

Voucher API Reference

1. Set up Clients and Client Groups

2. Connect your Client

3. Request an Access Token

4. Create a Voucher

5. Activate the Voucher

6. Redeem a Voucher

Create a Reservation

Charge the Reservation

7. Refund a Charge

8. Recharge a Voucher

What’s Next?