> ## 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.

# Voucher API Quickstart

> Set up a client, get credentials, and run through the full voucher lifecycle.

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:

| 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 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](/api-reference/voucher/clients/post-clients-connect) endpoint:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
Authorization: Bearer <access_token>
```

<Note>
  The Voucher API has its own OAuth 2 server. Tokens from the JTL platform or ERP API are not valid here.
</Note>

## 4. Create a voucher

```http theme={null}
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:

```http theme={null}
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).

<img src="https://mintcdn.com/jtlsoftwaregmbh/Hqc_7adhpPM3v5rg/images/voucher-charge-flow.jpg?fit=max&auto=format&n=Hqc_7adhpPM3v5rg&q=85&s=4d4c68ff959a55c23fdc446c76e111bd" alt="Reservation and charge flow" width="1562" height="782" data-path="images/voucher-charge-flow.jpg" />

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

```http theme={null}
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.

<Note>
  A reservation expires after 30 minutes, or when a new reservation is created for the same voucher.
</Note>

### 6.2 Charge the reservation

```http theme={null}
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:

```http theme={null}
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):

```http theme={null}
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](/api-reference/voucher) for all available endpoints and parameters.