Skip to content

PW – looks and feel changes #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

PW – looks and feel changes #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
14c3487
Update docs.json
p-woznikowski Aug 13, 2025
8c52de6
Fixes
p-woznikowski Aug 13, 2025
9488632
Documentation edits made through Mintlify web editor
mintlify[bot] Aug 13, 2025
180d682
Update docs.json
p-woznikowski Aug 13, 2025
eba6e6f
Fix
p-woznikowski Aug 13, 2025
a9a6747
Documentation edits made through Mintlify web editor
mintlify[bot] Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Mint Starter Kit",
"theme": "willow",
"name": "Voucherify test documentation",
"colors": {
"primary": "#122460",
"light": "#07C983",
Expand Down Expand Up @@ -35,7 +35,8 @@
"guides/development/API-Endpoints",
"guides/development/API-Optimization",
"guides/development/API-Reference",
"guides/development/API-Version-Upgrades"
"guides/development/API-Version-Upgrades",
"guides/development/Distributions"
]
},
{
Expand Down
41 changes: 20 additions & 21 deletions guides/campaign_recipes/Locking-Validation-Session.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
---
title: "Locking Validation Session"
description: "Temporary lock the voucher's usage until redemption is successful."


---

The validation and redemption mechanisms always work in a transactional way. As a result, the voucher's usage is registered permanently once redemption is successful. By using the session feature, you can temporarily record (lock) the voucher usage after the voucher has been validated.

The established session is released when one of the following events happens:

* Expiration time passes
* Redemption is being registered for the session
* Manual release using a dedicated API endpoint (for vouchers only: [Release Validation Session](ref:release-validation-session))
* Manual release using the [Validations Manager in the Dashboard](https://support.voucherify.io/article/16-dashboard-sections#validations) to unlock sessions.
- Expiration time passes
- Redemption is being registered for the session
- Manual release using a dedicated API endpoint (for vouchers only: [Release Validation Session](ref:release-validation-session))
- Manual release using the [Validations Manager in the Dashboard](https://support.voucherify.io/article/16-dashboard-sections#validations) to unlock sessions.

Once the session is established, the API returns a unique session key. The key must be used with each of the following validation or redemption requests to clearly identify the session. Multiple requests with the same key will always override existing session values.

By default, the number of available validation sessions is equal to the Code redemption limit set in the campaign manager. For example:

- If the code redemption limit is set to `4`, Voucherify will be able to lock up to four sessions. Next sessions will result in the `quantity_exceeded` error.
- If the code redemption limit is set to `unlimited`, Voucherify will allow any number of sessions.

Expand All @@ -26,12 +25,12 @@ By default, the number of available validation sessions is equal to the Code red

You can establish the locking session while validating the code. Put the `session` object in your request by following the session object reference.

| **Parameter** | **Description** | **Example** |
| :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| session.type `string` **required** | Type of the session. Required to establish a new session. Supported session types are listed in the table at the end of this guide. | "session":`{"type": "LOCK"}` |
| session.key `string` **optional** | Unique session identifier. | "session": `{"key": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts","type": "LOCK"}` |
| session.ttl_unit `string` **optional** Default value for session is 7 days | Defines the type of unit for session time. Allowed values: `DAYS`, `HOURS`, `MICROSECONDS`, `MILLISECONDS`, `MINUTES`, `NANOSECONDS`, `SECONDS` | "session": `{"type": "LOCK","ttl": 7,"ttl_unit": "DAYS"}` |
| session.ttl `number`**optional** Default value for session is 7 days | Value for the period of time that the session is active. Units for this paremter are defines by session.ttl_unit | "session": `{"type": "LOCK","ttl": 7,"ttl_unit": "DAYS"}` |
| **Parameter** | **Description** | **Example** |
| :------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
| session.type `string` **required** | Type of the session. Required to establish a new session. Supported session types are listed in the table at the end of this guide. | "session":`{"type": "LOCK"}` |
| session.key `string` **optional** | Unique session identifier. | "session": `{"key": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts","type": "LOCK"}` |
| session.ttl_unit `string` **optional** Default value for session is 7 days | Defines the type of unit for session time. Allowed values: `DAYS`, `HOURS`, `MICROSECONDS`, `MILLISECONDS`, `MINUTES`, `NANOSECONDS`, `SECONDS` | "session": `{"type": "LOCK","ttl": 7,"ttl_unit": "DAYS"}` |
| session.ttl `number`**optional** Default value for session is 7 days | Value for the period of time that the session is active. Units for this paremter are defines by session.ttl_unit | "session": `{"type": "LOCK","ttl": 7,"ttl_unit": "DAYS"}` |

To link a request with the given session, always use the same session key for session-related validation and redemption requests. You can use your own session key or the system will generate one for you once the session option is enabled with the request.

Expand Down Expand Up @@ -71,6 +70,7 @@ To link a request with the given session, always use the same session key for se
}
}
```

```json Response
{
"valid": true,
Expand Down Expand Up @@ -133,7 +133,7 @@ To link a request with the given session, always use the same session key for se
```

> 📘 Default session time
>
>
> If you do not establish a session timeframe by passing the `session.ttl` and `session.ttl_unit`, it will be active for 7 days.

### Step 2: Redeem the code with the session key
Expand Down Expand Up @@ -166,6 +166,7 @@ When redeeming the code, the session object needs to define `session.type` and `
}
}
```

```json Response
{
"redemptions": [
Expand Down Expand Up @@ -245,27 +246,25 @@ When redeeming the code, the session object needs to define `session.type` and `

### Step 3: Track redemption

If the redemption request includes a proper `session.key` value, the request is validated and the redemption is executed. When Voucherify registers a new redemption for the locked resource, the session is automatically released.


If the redemption request includes a proper `session.key` value, the request is validated and the redemption is executed. When Voucherify registers a new redemption for the locked resource, the session is automatically released.

If you need to remove an established session manually, use the [Release Validation Session](ref:release-validation-session) endpoint.

> 👍 Locking Session in Short
>
>
> Registering a session will record a temporary usage for the specified timeframe. This means it will influence other incoming validation and redemption requests until the session is released.
>
>
> Once redemption is successful the session is removed automatically.

## Session Keys

The following table presents the type of sessions that can be established.

| **Session Type** | **Behaviour** |
| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Session Type** | **Behaviour** |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LOCK | Locks the following parameters within the session:- redemption quantity by 1 - redemption gift credits specified with the requests - redemption loyalty points specified with the request |

You can always release established sessions by calling [Release Validation Session](ref:release-validation-session) endpoint.
You can always release established sessions by calling [Release Validation Session](ref:release-validation-session) endpoint.

> 📘 Postman Collection
>
Expand Down
6 changes: 3 additions & 3 deletions guides/development/API-Version-Upgrades.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ hidden: false
order: 200
---

Your API version controls the API and webhook behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.). Your version is set the first time you make an API request. When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don’t change your version until you’re ready to upgrade.
Your API version controls the API and webhook behavior you see (e.g., what properties you see in responses, what parameters you're permitted to send in requests, etc.). Your version is set the first time you make an API request. When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don't change your version until you're ready to upgrade.

---

## How can I upgrade my API?

If you’re running an older version, you’ll want to upgrade to take advantage of the latest API. For changing your API version, go to your Project Settings and click** Upgrade to the latest API version**.
If you're running an older version, you'll want to upgrade to take advantage of the latest API. For changing your API version, go to your Project Settings and click** Upgrade to the latest API version**.

---

Expand All @@ -34,7 +34,7 @@ If you’re running an older version, you’ll want to upgrade to take advantage
| Version | Description |
| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v2017-04-05 version deprecated | - Responses from the voucher and campaign listing methods were moved to the new object structure. Methods will now render specific properties for a total count and an array of objects.- Introduced validation for listing parameters: `limit` and `page`. A limit can range between 1 and 100 items.- Get voucher/campaign methods render **validation rules** related to the voucher object. They can be inherited from a campaign.- Created an API method for getting a campaign identified by name. |
| v2017-04-20 version deprecated | Response from the voucher publish method was moved to the new object structure. Returned voucher details are wrapped by transaction object describing publication event:{ "id": "pub_whQzIndYoyZoqiLEKN0s04GK", "object": "publication", "created_at": "2017-04-20T13:18:01Z", "customer_id": "cust_mOjhGypfbqch0v3DpAA9LDXj", "tracking_id": "janusz", "channel": "API", "metadata": { "test":true }, "voucher": {} } |
| v2017-04-20 version deprecated | Response from the voucher publish method was moved to the new object structure. Returned voucher details are wrapped by transaction object describing publication event:`{ "id": "pub_whQzIndYoyZoqiLEKN0s04GK", "object": "publication", "created_at": "2017-04-20T13:18:01Z", "customer_id": "cust_mOjhGypfbqch0v3DpAA9LDXj", "tracking_id": "janusz", "channel": "API", "metadata": { "test":true }, "voucher": {} } ` |
| v2018-08-01 | This version introduces a new model for building Validation Rules. The extended mechanism gives an advanced configuration for making promo conditions.The modifications in this version affect the following API methods:- `List Promotion Tiers`: replaced an object describing conditions by a list of records describing an association between rule and tier - `validation_rule_assignments`- `List Promotion Tiers for campaign` - as above- `Promotion Tier Object` - as above- `Validation Rule Object` - structure reorganized to handle advanced rules- `Validation Rule Assignment Object` - added object describing a relation between rules and linked promotions- `Validation Rules` - modified data modelThe mechanics and details of Validation Rules builder are described in the Help Center. |
| Webhooks v2024-01-01 | In [v20231205](https://support.voucherify.io/article/23-whats-new-in-voucherify#v20231205) release, a new version of webhooks was introduced. The new webhooks are available for distribution and the events listed in Project settings. There, you can switch from the old v2018-01-01 webhook version to the new one. The accounts created after the v20231205 release can use only the new version. |

Expand Down
Loading