API

This documentation is aimed at developers to define the requirements of technical implementation of the Pion Student Beans code tracking API. More information on the definition of each field and what those fields should be populated with can be found in the knowledge base section.

[POST] /code-tracking/transaction

POST https://sb-api.studentbeans.com/code-tracking/transaction

This endpoint allows you to record the use of a Student Beans voucher code from a transaction.

Body Params

Field	Type	Description
brandUid [required]	string	A unique ID attached to your brand issued by Pion. The brandUid is unique per country.
code [required]	string	The code supplied by your brand and issued from a Student Beans platform that is then applied at checkout.
transactionValue [required]	float	The value of the transaction up to two decimal places as a float. For example, if the transaction value is £10.00, you would enter 10.0 or 10.00 and not "£10", 10 or "10.0".
qualifyingAmount [required]	float	The value of the transactionValue that is eligible to be discounted, up to two decimal places as a float. For example, if the qualifying amount is £1.50, you would enter 1.5 or 1.50 and not "£1.50", or "1.5".
currency [required]	string	The ISO 4217 currency code for the locale of the transaction.
timestamp [required]	integer	The timestamp of the transaction between the customer and your brand, in UTC, as Unix Epoch time in seconds.
newUser	boolean	Boolean value that determines whether the transaction is a new user.
productsOrderedSku	array of strings	An array of string SKU's for the products purchased as part of the transaction.
productsOrderedName	array of strings	An array of string product names purchased as part of the transaction.
userAgent	string	The user agent the transaction has been completed from.

Example Request Body:

{
  "brandUid": "20406f16-7f0f-11ee-b962-0242ac120002",
  "code": "AFSB20UK-fcf43t",
  "transactionValue": 20.25,
  "qualifyingAmount": 5.25,
  "currency": "GDP",
  "timestamp": 1577836800,
  "newUser": true,
  "productsOrderedSku": ["sk1", "sk2"],
  "productsOrderedName": ["Product Name 1", "Product Name 2"],
  "userAgent": "iOS Safari"
}

Headers

Content-Type	application-json
User-Agent	<product>/<product_version> <comment>
api-key	<generated-by-student-beans>
brand-uid	<generated-by-student-beans>

Example Responses

200 OK

{
  "data": {
    "type": "transaction",
    "id": "20406f16-7f0f-11ee-b962-0242ac120002",
    "attributes": {
      "brandUid": "20406f16-7f0f-11ee-b962-0242ac120002",
      "code": "AFSB20UK-fcf43t",
      "transactionValue": 20.25,
      "qualifyingAmount": 5.25,
      "currency": "GBP",
      "timestamp": 1577836800,
      "newUser": true,
      "productsOrderedSku": ["sk1", "sk2"],
      "productsOrderedName": ["Product Name 1", "Product Name 2"],
      "userAgent": "iOS Safari"
    }
  }
}

400 Bad Request

{
  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "Reason for failed request will be displayed here"
    }
  ]
}

Implementation Examples

Curl Example

curl -X POST \
  https://sb-api.studentbeans.com/code-tracking/transaction \
  -H 'Content-Type: application/json' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'User-Agent: <YOUR_USER_AGENT>' \
  -d '{
    "brandUid": "20406f16-7f0f-11ee-b962-0242ac120002",
    "code": "AFSB20UK-fcf43t",
    "transactionValue": 20.25,
    "qualifyingAmount": 5.25,
    "currency": "GBP",
    "timestamp": 1577836800
}'

Ruby Example

require 'net/http'
require 'uri'
require 'json'

url = 'https://sb-api.studentbeans.com/code-tracking/transaction'
api_key= 'YOUR_API_KEY'
user_agent = 'YOUR_USER_AGENT'

request_body = {
    "brandUid": "20406f16-7f0f-11ee-b962-0242ac120002",
     "code": "AFSB20UK-fcf43t",
     "transactionValue": 20.25,
     "qualifyingAmount": 5.25,
     "currency": "GBP",
     "timestamp": 1577836800
}.to_json

uri = URI(url)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request["api-key"] = api_key
request["User-Agent"] = user_agent
request['Content-Type'] = 'application/json'
request.body = request_body

response = http.request(request) puts response.body

Node Example

const axios = require('axios')

const sbTrackingUrl = 'https://sb-api.studentbeans.com/code-tracking/transaction'
const apiKey = 'YOUR_API_KEY'
const userAgent = 'YOUR_USER_AGENT'

const requestBody = {
  brandUid: '20406f16-7f0f-11ee-b962-0242ac120002',
  code: 'AFSB20UK-fcf43t',
  transactionValue: 20.25,
  qualifyingAmount: 5.25,
  currency: 'GBP',
  timestamp: 1577836800
}

const headers = {
  'api-key': apiKey,
  'Content-Type': 'application/json',
  'User-Agent': userAgent
}

axios
  .post(sbTrackingUrl, requestBody, { headers })
  .then((response) => {
    console.log(response.data)
  })
  .catch((error) => {
    console.error(error)
  })