Skip to main content
Version: Current

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.

Headers​

API Key & Brand UID​

Your API key will be issued to you by Student Beans, this is used in conjunction with your brand uid 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.