Skip to main content
PATCH
/
vouchers
/
{id}
/
status
Set the status for a voucher
curl --request PATCH \
  --url https://vouchers.api.jtl-software.com/v1/vouchers/{id}/status \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "active",
  "comment": "reason for this status change"
}
'
{
  "id": "4ZH83T0ACUUC14CW",
  "client_id": "da39a3ee5eb28b7392ef5",
  "sku": "AJHS8675FG",
  "batch": "Winter Campaign",
  "amount": "10.53",
  "currency": "EUR",
  "valid_until": "2025-07-21T17:32:28+00:00",
  "validity_value": 24,
  "validity_interval": "months",
  "status": "active",
  "type": "digital",
  "taxable": true,
  "tax_rate": "19",
  "order_number": "Order 66",
  "data": "{\"foo\": \"bar\"}",
  "created_at": "2017-07-21T17:32:28+00:00",
  "updated_at": "2017-07-21T17:32:28+00:00"
}

Authorizations

​
Authorization
string
header
required

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.

Path Parameters

​
id
string
required

Body

application/json

Voucher status request body

​
status
enum<string>
required

new status

Available options:
active,
inactive
Example:

"active"

​
comment
string

comment

Maximum string length: 255
Example:

"reason for this status change"

Response

OK

​
id
string

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)

Maximum string length: 255
Example:

"4ZH83T0ACUUC14CW"

​
client_id
string
read-only

id of the client that created this voucher

Example:

"da39a3ee5eb28b7392ef5"

​
sku
string

Optional SKU

Maximum string length: 255
Example:

"AJHS8675FG"

​
batch
string

Optional campaign or grouping identifier

Maximum string length: 30
Example:

"Winter Campaign"

​
amount
string

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
Required string length: 4 - 9
Pattern: ^\d+\.\d{2}$
Example:

"10.53"

​
currency
string

The three-character ISO-4217 currency code - https://en.wikipedia.org/wiki/ISO_4217#Active_codes

Required string length: 3
Example:

"EUR"

​
valid_until
string<RFC3339>
read-only

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
integer

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
enum<string>

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)

Available options:
days,
weeks,
months,
years
Example:

"months"

​
status
enum<string>

The status of this voucher. In general vouchers are inactive when created, and gets activated when payed. Only activated vouchers can be charged.

Available options:
active,
inactive
Example:

"active"

​
type
enum<string>

Defines if this voucher is printed or digital. Printed vouchers will have the status inactive by default.

Available options:
print,
digital
Example:

"digital"

​
taxable
boolean
default:false

Defines if this voucher is a taxable multi purpose voucher

Example:

true

​
tax_rate
string

The tax rate for this voucher (only required when taxable is true)

Example:

"19"

​
order_number
string

An optional order number for this voucher

Example:

"Order 66"

​
data
string

Any additional custom data for this voucher as a JSON string

Example:

"{\"foo\": \"bar\"}"

​
created_at
string<RFC3339>
read-only

created_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339

Example:

"2017-07-21T17:32:28+00:00"

​
updated_at
string<RFC3339>
read-only

updated_at - datetime in RFC3339 format, see https://tools.ietf.org/html/rfc3339

Example:

"2017-07-21T17:32:28+00:00"