Validate Voucher (client-side)

To verify a voucher code given by customer, you can use this method. It is designed for client side integration which means that is accessible only through public keys. This method is designed to be run directly either in web browsers or mobile apps.

Set customer identity (optional)

Voucherify can help you track anonymous customers. Once you integrate Voucherify.js into your web app and call validate method, Voucherify will return a tracking ID and the script will store it in a cookie. Every next validate call will be using the same tracking ID.

We are tracking users who are validating vouchers with those who consume them by a tracking_id. For that, we are setting up an identity for the user. We will generate a tracking_id on the server side unless you specify it on your own. In both cases, you will receive it in the validation response.

The returned tracking_id field should be used as customer source_id in subsequent redemption requests. The tracking_id returned from Validation API is encoded. Voucherify will recognize both values for identifying customer - the one before encryption send as a query parameter to GET validate request, and the version encrypted and returned as part of the validation request.

Sample workflow

Customer tracking workflow in a nutshell:

Client-side:

  • A customer visits your website.
  • A customer validates a voucher code. That triggers a validate request to Voucherify. In request, you pass tracking_id or customer.source_id. As a result, it returns encoded tracking_id.

Backend:

  • Once the customer finishes the checkout process, your website passes the tracking_id to your backend during a redemption. It is sent as a property source_id in a customer object.
  • A customer object is created and within the redemption response, you get a customer.id.
  • You can use the customer.id or customer.source_id to fetch or modify the customer details.

A customer is created (upserted) automatically with a redemption call. Alternatively, you can create a new profile by creating a customer via a dedicated API method. Take a look at the customer object to understand the entity's structure.

📘

Customer identifier

Source id of the customer may be either already hashed version of tracking id you received in a response from a validation request or a custom ID you predefined (email address). Nevertheless, we recommend using identifiers delivered by Voucherify API.

curl -X GET \
  -H "X-Client-Application-Id: 011240bf-d5fc-4ef1-9e82-11eb68c43bf5" \
  -H "X-Client-Token: 9e2230c5-71fb-460a-91c6-fbee64707a20" \
  -H "Content-Type: application/json" \
  -H "origin: yourdomain.com" \
  'https://api.voucherify.io/client/v1/validate?code=5OFF5&amount=1500&item[0][sku_id]=sku_13SWYzm3tuMXSP&item[0][quantity]=2&item[1][product_id]=prod_DSFGCz3IFxpkiL&item[1][quantity]=2'
JSFiddle example

<script type="text/javascript" src="https://cdn.rawgit.com/rspective/voucherify.js/v1.4.5/dist/voucherify-1.4.5.js"></script>

<script type="text/javascript">
  function init() {
    Voucherify.initialize(
      "011240bf-d5fc-4ef1-9e82-11eb68c43bf5", //YOUR-CLIENT-APPLICATION-ID-FROM-SETTINGS
      "9e2230c5-71fb-460a-91c6-fbee64707a20" //YOUR-CLIENT-TOKEN-FROM-SETTINGS
    );
  };
  init();
  
  //-- [Optional] If you want us to track your customers' activity, then you should invoke the following function to set identity. You have to do it only once. If the identity parameter is not passed, then we will generate it for you.
  Voucherify.setIdentity("your-customer-uniq-id");
  Voucherify.validate("Testing7fjWdr", function callback (response) {
    console.log(response);
  });
</script>

Examples

Example Request

Shortcut - customer query param instead of customer[source_id]

https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=customer_id

Pass customer's and redemption's context metadata in query parameters

https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=sure_he_is_new&metadata[shop]=1&customer[metadata][propsy]=2&metadata[test]=true

Use tracking_id instead of source_id

https://api.voucherify.io/client/v1/validate?code=IKU-mvS-JOG&amount=10100&tracking_id=sure_he_is_new_5&metadata[shop]=1&metadata[test]=true

Returns

This operation returns information about validity of the code. Moreover it returns hashed source identifier which can be used as tracking id in future calls.

If a validation session is established then the session details will be returned as well. Read more about sessions: Validation Session .

Voucher validation might fail because of one of these reasons:

  • voucher not found - voucher doesn't exist or was deleted
  • voucher expired - voucher is out of [start date - expiration date] time frame
  • voucher is disabled - learn more disable voucher
  • customer does not match segment rules - learn more customer tracking
  • order does not match validation rules - learn more about validation rules
Language
Response
Click Try It! to start a request and see the response here!