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

# Vouchers API Quickstart

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

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:

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

Exchange the PIN for OAuth credentials:

```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 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:

```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).

Include the returned access token in the `Authorization` header of every subsequent request:

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

<Note>
  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.
</Note>

## 4. Create a Voucher

Create a voucher with an initial balance.

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

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.

```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. Redeem a Voucher

Redeeming a voucher consists of two operations:

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

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

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.

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

Save the returned reservation `id`.

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

### Charge the Reservation

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

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.

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

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

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Error Codes" icon="triangle-alert" href="/guides/voucher/error-codes">
    Reference for Vouchers API error codes and their meanings.
  </Card>

  <Card title="Voucher API Reference" icon="code" href="/api-reference/voucher">
    Full endpoint reference for all Vouchers API operations and parameters.
  </Card>
</CardGroup>