Locking validation session

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. A lock for a redeemable is released when one of the following happens:

Expiration time passes
Redemption is registered for the session
Manual release for a voucher with Release Validation Session. This unlocks only the voucher in the path, even if other redeemables share the same session key
Manual release in the Dashboard:
- On a redeemable’s details Validations tab, Release session unlocks only that redeemable
- In Redemptions > Sessions, you can unlock the session for every redeemable that still holds that session key

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.

How to lock code usage

Step 1: Validate code with session key

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

Example validation request

{
  "customer": {
    "source_id": "[email protected]"
  },
  "options": {
    "include_orders": true,
    "extended_redemptions": false
  },
  "redeemables": [
    {
      "object": "voucher",
      "id": "dBj56oqJ",
      "gift": {
        "credits": 100
      }
    },
    {
      "object": "voucher",
      "id": "39vnjyS8"
    },
    {
      "object": "promotion_tier",
      "id": "promo_wtS1aPOs3k2majiBJv3yfbSM"
    }
  ],
  "order": {
    "amount": 200000
  },
  "session": {
        "type": "LOCK"
    }
}

{
    "valid": true,
    "redeemables": [
        {
            "status": "APPLICABLE",
            "id": "wTzxDoOk",
            "object": "voucher",
            "order": {
                "amount": 200000,
                "discount_amount": 40000,
                "total_discount_amount": 40000,
                "total_amount": 160000,
                "applied_discount_amount": 40000,
                "total_applied_discount_amount": 40000,
                "customer_id": null,
                "referrer_id": null,
                "object": "order"
            },
            "applicable_to": {
                "data": [],
                "total": 0,
                "data_ref": "data",
                "object": "list"
            },
            "inapplicable_to": {
                "data": [],
                "total": 0,
                "data_ref": "data",
                "object": "list"
            },
            "result": {
                "discount": {
                    "type": "PERCENT",
                    "effect": "APPLY_TO_ORDER",
                    "percent_off": 20
                }
            }
        }
    ],
    "order": {
        "amount": 200000,
        "discount_amount": 40000,
        "total_discount_amount": 40000,
        "total_amount": 160000,
        "applied_discount_amount": 40000,
        "total_applied_discount_amount": 40000,
        "customer_id": null,
        "referrer_id": null,
        "object": "order"
    },
    "tracking_id": "track_e6YkMFU+7zj7ra2btFgSm1T9pRSZw/LawvdybWhgdmY=",
    "session": {
        "key": "ssn_jSzpiExs0LUPN3NuKFxXsZeKMhUJ01iJ",
        "type": "LOCK",
        "ttl": 7,
        "ttl_unit": "DAYS"
    }
}

If you do not establish a session time frame 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

Usage of the code is locked and allowed only with the returned session key that identifies the session. Note that multiple requests with the same key will always override existing session values. When redeeming the code, the session object needs to define session.type and session.key.

{
    "customer": {
        "source_id": "[email protected]"
    },
    "options": {
        "include_orders": true,
        "extended_redemptions": false
    },
    "redeemables": [
        {
            "object": "voucher",
            "id": "wTzxDoOk"
        }
    ],
    "order": {
        "amount": 200000
    },
    "session": {
        "type": "LOCK",
        "key": "ssn_jSzpiExs0LUPN3NuKFxXsZeKMhUJ01iJ"
    }
}

{
    "redemptions": [
        {
            "id": "r_ChvVmYqjr8pPHBg5qx0nLycF",
            "customer_id": "cust_FRA887OGB6GMJ6zW6U0QibZV",
            "tracking_id": "track_e6YkMFU+7zj7ra2btFgSm1T9pRSZw/LawvdybWhgdmY=",
            "date": "2022-01-17T08:03:25.029Z",
            "order": {
                "id": "ord_XGcGm0SnaM97urUv12afKucX",
                "source_id": null,
                "status": "PAID",
                "customer_id": "cust_FRA887OGB6GMJ6zW6U0QibZV",
                "referrer_id": null,
                "amount": 200000,
                "discount_amount": 40000,
                "applied_discount_amount": 40000,
                "total_discount_amount": 40000,
                "total_applied_discount_amount": 40000,
                "total_amount": 160000,
                "object": "order"
            },
            "customer": {
                "id": "cust_FRA887OGB6GMJ6zW6U0QibZV",
                "name": null,
                "email": null,
                "source_id": "[email protected]",
                "object": "customer"
            },
            "result": "SUCCESS",
            "voucher": {
                "id": "v_cgZj8kWiKTk12NnEsNN0LILHrUM16due",
                "code": "wTzxDoOk",
                "discount": {
                    "type": "PERCENT",
                    "percent_off": 20,
                    "effect": "APPLY_TO_ORDER"
                },
                "type": "DISCOUNT_VOUCHER",
                "campaign": "20% off",
                "campaign_id": "camp_6IkkrYF2s6Bv8EunjjVT8ETm",
                "is_referral_code": false,
                "holder_id": "cust_DqubjWlroec0v7te2fVBPcby"
            }
        }
    ],
    "order": {
        "id": "ord_XGcGm0SnaM97urUv12afKucX",
        "source_id": null,
        "created_at": "2022-01-17T08:03:24.908Z",
        "updated_at": null,
        "status": "PAID",
        "amount": 200000,
        "discount_amount": 40000,
        "total_discount_amount": 40000,
        "total_amount": 160000,
        "applied_discount_amount": 40000,
        "total_applied_discount_amount": 40000,
        "customer": {
            "id": "cust_FRA887OGB6GMJ6zW6U0QibZV",
            "object": "customer"
        },
        "customer_id": "cust_FRA887OGB6GMJ6zW6U0QibZV",
        "referrer_id": null,
        "object": "order",
        "redemptions": {
            "r_ChvVmYqjr8pPHBg5qx0nLycF": {
                "date": "2022-01-17T08:03:25.029Z",
                "related_object_type": "voucher",
                "related_object_id": "v_cgZj8kWiKTk12NnEsNN0LILHrUM16due",
                "related_object_parent_id": "camp_6IkkrYF2s6Bv8EunjjVT8ETm"
            }
        }
    }
}

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 you need to unlock a voucher manually, use Release Validation Session. In a stackable validation, several vouchers can share one session key. Releasing the session for one voucher unlocks only that voucher. Other vouchers that still hold the same key stay locked, and only that voucher gets a session-released event in the Activity tab. Calling the endpoint again for a voucher that is no longer locked still returns 204 and does not create another session-released event.

Registering a session will record a temporary usage for the specified time frame. 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
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 unlock a voucher’s session lock with Release Validation Session. To unlock every redeemable still tied to the same session key, use Redemptions > Sessions in the Dashboard.

Go to Voucherify Postman Collection, where you can test the Locking Validation Session mechanism.

Develop

Incentivize

Explore

Integrate

Locking validation session

How to lock code usage

Step 1: Validate code with session key

Example validation request

Step 2: Redeem the code with the session key

Step 3: Track redemption

Session keys

​How to lock code usage

​Step 1: Validate code with session key

​Example validation request

​Step 2: Redeem the code with the session key

​Step 3: Track redemption

​Session keys

How to lock code usage

Step 1: Validate code with session key

Example validation request

Step 2: Redeem the code with the session key

Step 3: Track redemption

Session keys