Knowledge Base

This section of the documentation aims to give a non-technical overview of what is required for the Student Beans code tracking API. The technical documentation can be found in the API Documentation section.

Single Use Unique Codes vs Generic/Multi-use Codes

Unique Codes vs. Generic Codes

Imagine you're giving out coupons for a free pizza.

Unique Codes:

Each coupon has a special, one-time-use code. Only one person can use that code to get their free pizza.

Generic Codes:

Everyone gets the same code. Many people can use that code to get a free pizza.

Code Track Pro and Unique Codes

Code Track Pro is designed to work best with unique codes. It can track who used each code and where they came from.

Using Generic Codes with Code Track Pro

We can make Code Track Pro work with generic codes, but there are some things to keep in mind:

• More Time Required: We'll need to check other information to make sure everything is working right meaning more time to get you set up correctly.
• Less Information: You won't get as much detail about who is using the codes in the Pion portal. Information specifically around user demographics will no longer be available.
• Limited Reporting: You won't be able to see as much information about who used the codes, like if they were new or returning customers.

Summary

While Code Track Pro can handle generic codes, unique codes are the best option for getting the most out of the tool.

Transaction Endpoint

Body Params

Brand UID

The brand uid is a unique ID that is attached to your brand by Pion. Your Brand UID is unique per each country you're active in. This is a required field.

Code

The code is supplied by your brand and is issued from a Student Beans platform, this is then applied at checkout, this must be unique so that Student Beans can link this to a specific issuance. This is a required field.

Transaction Value

This is the value of the total transaction. This is a required field.

Qualifying Amount

The qualifying amount represents the proportion of the total basket that is eligible for a discount offered by a brand, here are a a couple of scenarios to consider.

To be clear the qualifying amount is not the percentage value of the discount itself (i.e. 10%). Qualifying Amount is a required field.

Scenario 1: The entire portion of the basket is discounted:

Your discount code works on all products or services your business offers. In this case, the entirety of any transaction made with that code is eligible to be discounted. In this scenario, the transactionValue and qualifyingAmount will be identical.

Scenario 2: A portion of the basket is discounted:

Your discount code only works for certain products or services offered by your business. In this case, the value of those products or services which are eligible to be discounted is what should be entered as the qualifyingAmount.

It is common for the qualifying amount to be different for individual users. Here are a couple of examples of where you might need to pragmatically calculate the qualify amount from the transaction value.

Example A: A transaction is made for £100, meaning the transactionalValue is 100.0. The discount code used with this transaction is only applicable to products whose value ads up to £50. Therefore the qualifyingAmount is 50.0.

Example B: A brand might only offer a 10% discount on a subset of their products, i.e. Bikes but not Scooters. However, the basket contains a bike worth £150 and a scooter worth £50. While the transactionValue is £200 only £150 is eligible for discount, therefor the qualifying amount is 150.0.

note

Note If you have a static cost per acquisition (CPA) rate, eg. £5.25 per lead, you are required to enter that static CPA value in this field instead. In the case of this example that would be 5.25

Currency

This field will represent the ISO 4217 currency code, this can be found at https://www.newbridgefx.com/currency-codes-symbols/. This is a required field.

tip

£ = GBP
$ = USD
€ = EUR

Timestamp

The timestamp of the transaction between the customer and your brand, in UTC, as Unix Epoch time in seconds.

info

Ideally, transactions are sent instantaneously. If sending transactions in a batch (e.g., at the end of the month), the timestamp field must be time the transaction occurred between the customer and your brand.

New User

A true/false value that determines whether the transaction is a new user.

Products Ordered SKU

A comma-separated list of SKUs for the products purchased as part of the transaction.

Products Ordered Name

A comma-separated list of string product names was purchased as part of the transaction.

User Agent

The user agent the transaction has been completed from.

Basket Examples

Example A: The entire portion of the basket is discounted

The example below is a demonstration of what a basket might look like where all of the items are discounted via Student Beans codes.

Product	Price	Discounted?	Note
T-Shirt	£10	Yes	This item is discounted via Student Beans so the price should be included in the qualifying amount.
Jeans	£20	Yes	This item is discounted via Student Beans so the price should be included in the qualifying amount.
Shoes	£30	Yes	This item is discounted via Student Beans so the price should be included in the qualifying amount.

In the payload that you send to Pion, as all items are discounted, the transaction value and the qualifying amount will be the sum of all the products, £60.

Example B: A portion of the basket is discounted

The example below is a demonstration of what a basket might look like where only some of the items are discounted via Student Beans codes.

Product	Price	Discounted?	Note
T-Shirt	£10	Yes	This item is discounted via Student Beans so the price should be included in the qualifying amount.
Jeans	£20	No	This item is not discounted via Student Beans so the price should not be included in the qualifying amount.
Shoes	£30	Yes	This item is discounted via Student Beans so the price should be included in the qualifying amount.
Socks	£5	Yes, but not via Student Beans	This item while discounted, is not discounted via Student Beans so the price should not be included in the qualifying amount.

In the payload that you send to Pion, the qualifying amount should be the sum total of only the items that are valid for a Student Beans discount. i.e. the sum of the T-Shirt and Shoes, £40. The transaction value should still be the total value of the basket, £65.

Headers

API Key

Your API key will be issued to you by Student Beans, this is used to authorize requests to the code tracking API.

User Agent

In some cases, you may also need to send a user agent field if you are still receiving an unauthorized error with the correct credentials.

Glossary

This section contains terminology that might be ambiguous.

Single Use Unique Code

There are a couple of different code types at Student Beans. Specifically, to utilize CodeTrackPro to its fullest you'll need a single-use unique code. This is a code that is unique per user and redeems an offer through a Student Beans product. This may look something like: "SB01-abc", "SB02-def", "SB03-ghi".

Generic/Multiuse Code

Another type of code that can be offered through Student Beans is a code that can be used multiple times by different users, this might look something like "10OFFBRAND". This type of code has limitations but can be used with CodeTrackPro.