How to generate Pay-Thru vouchers

Using the API for the first time can be hard sometimes. We hope the following help will guide you through creating of your first Pay-Thru vouchers.

Obtaining the User ID and Brand ID

Almost every endpoint in the SOCIFI Public API needs User ID and Brand ID. Knowing those IDs is crucial as they tell to whom the Vouchers and other resource belong.

The most simple way of getting your User ID is to call the /users/me endpoint.

It's quite common, that every user has many brands. To get the list of all your brands, call the /users/{userId}/brands with the User ID from the endpoint above. I.e. GET /users/1337/brands.

Knowing the Pay-Thru plan ID to which the vouchers will be attached

Since we already know the User ID and Brand ID, we can call the GET /users/{userId}/pay-thru?brandId={brandId} endpoint. This will list all Pay-Thru plans that are set on given brand. Pick one plan that we will use for the voucher set.

If you are not familiar with the Pay-Thru or need help to set it up, please refer to the dedicated documentation.

Generating the vouchers

We know all the required variables now and we are ready to generate our first voucher set.

Vouchers are generated in sets. Those sets offer great flexibility and simplify the codes management. Each set defines the look of the codes like length, type, or prefix.

To generate the vouchers, we will use POST /users/{userId}/pay-thru/vouchers endpoint.

Expires at and date format note

Please note the date used for expiresAt must be in ISO 8601 format.

Example

Imagine you want to generate 1 000 voucher codes with 30% discount, a length of 10 characters and prefixed with PIZZA. The Pay-Thru plan ID is 2549 and belongs to user ID 844. To achieve this, you will use following parameters:

Parameter	Example value	Note
payThruPlanId	2549	The Pay-Thru plan ID we obtained earlier.
multiDevice	true	We want the voucher to include the Multi-Device option.
prefix	PIZZA	Every voucher code will have the prefix of PIZZA. The prefix is not counted towards the voucher length.
discount	30	Will result in the discount of 30%.
count	1000	We want to get 1 000 codes.
length	10	Length of each code will be 10 characters + the prefix.
type	alpha	The voucher codes will contain only alphabetical characters.
expiresAt	2017-05-31T23:59:59Z	The codes will be valid (usable) until the first half of the year 2017.

If all the parameters were accepted and codes generated, you will be presented with a JSON response containing ID of the generated voucher set.

Listing codes in voucher set

To list all codes in the just generated voucher set, call the GET /users/{userId}/pay-thru/vouchers/{voucherSetId} endpoint. You can also pass the query parameter status with a value of unused to list only vouchers that have not yet been used.

To help you better understand the output, please see the table below.

Each code in given set consists of the following:

Field	Description
id	Id of the voucher code. This is unique to every record.
voucherSetId	ID of the voucher set.
code	Generated voucher code including the prefix. E.g. PIZZA-COIAIJCYOS.
visitorId	ID of the visitor who used the code. If null, the code way not yet used.
email	Email of the visitor. Filled if the code was already used.
mac	MAC of the visitor's device. Filled if the code was already used.
hotspotId	ID of the hotspot on which the code was used. Filled if the code was already used.
brandId	Brand ID that belongs to the hotspot. Filled if the code was already used.
usedAt	When the code was used. In ISO 8601 format. Filled if the code was already used.