Subscription API

The Cubed Subscription API allows you to upload subscription data to Cubed. This data can be used to supplement your reporting and provide a more complete view of your customer's journey.

Note that - in its current implementation - the Cubed Subscription API is designed for server-to-server communication only. It does not accept requests made directly from web browsers. If this is something you require, please contact your account manager.

Overview

The API follows a RESTful design and uses JSON for request and response payloads. The API is secured using an API key, which is provided by Cubed. The API key should be included in the X-API-Key header of each request. You can obtain your API key by contacting your account manager.

Rate Limiting

The API enforces rate limits to ensure high availability and fair usage for all users. Each client is allowed 10 requests per second. Currently we have a burst limit of 1, which means that the client can only send 10 requests in a single second. Additionally, there is hard monthly limit of 1,000,000 requests.

If you believe you need a higher rate limit, please contact your account manager and we will be happy to discuss your requirements. Exceeding these limits will result in a 429 Too Many Requests response.

To optimise your usage:

• Utilize the data parameter to send multiple subscription events in a single request. This approach helps in staying within the rate limits by reducing the total number of requests.
• A maximum of 30 objects can be included in the data parameter per request. Attempts to exceed this limit will be met with an error response.

For best performance and to avoid rate limit errors, we recommend introducing a short delay (e.g., 1 second) between consecutive requests to ensure a smooth and uninterrupted service experience.

Response Codes

A non exhaustive list of response codes is provided below:

Status Code	Description	Response Body
200	The request was successfully simulated.	{"message": "Subscription simulated successfully.", "validationErrors": null}
201	The request was successfully stored in the database.	{"message": "Subscription created successfully.", "validationErrors": null}
400	The request was malformed.	{"message": "Malformed JSON.", "validationErrors": "<exception message>"}
403	The request was not authenticated.	{"message": "Forbidden", "validationErrors": null}
429	The request was rate limited.	{{"message":"Too Many Requests"}}
500	The request was not successful for some server-side reason.	{"message": "Internal server error.", "validationErrors": "<exception message>"}
504	The request timed out.	{"message": "Endpoint request timed out"}

Base URL and Endpoints

The base URL for the Cubed Subscription API is https://api.withcubed.com and all requests should be made to this URL. The following endpoints are available:

Endpoint	Description
POST /subscription	Upload subscription data to Cubed.

Uploading Subscription Data

To upload subscription data to Cubed, you should make a POST request to the /subscription endpoint. The request body should contain a JSON object with the following structure:

{
  "aid": "c-a-<client_name>-<location>",
  "data": [
    {
      "tid": "transaction_id_one",
      "subid": "subscription_id_one",
      "cid": "customer_id_one",
      "evt": "newsletter",
      "rvn": 100
    },
    {
      "tid": "12346",
      "subid": "12346",
      "cid": "12346",
      "evt": "newsletter",
      "rvn": 100
    }
  ],
  "simulate": true // OPTIONAL (default is false)
}

Below is a more detailed description of each field in the request body:

Parameter	Description	Primitive	Example	Required	Limits
aid	str	The aid is the Cubed account token for the client, please ask for yours.	c-a-<client_name>-<location>	Yes	N/A
data	array	The data parameter is a JSON object that contains the subscription data to be stored in the client database.	[{ "tid": "<str>", "subid": "<str>", "cid": "<str>", "evt": "<str>", "rvn": "<int>" }]	Yes	30 objects
simulate	bool	The simulate parameter is a boolean value that determines whether the request is a simulation or not. i.e. whether the request is actually stored in the database or not.	true	No	N/A

The data parameter is an array of JSON objects that contain the subscription data to be stored in the client database. Each JSON object in the array can contain the following parameters:

Parameter	Description	Primitive	Example	Required
tid	str	The tid is the transaction ID for the subscription event. It is used to keep sales unique in our system. Cubed also uses this to join a Subscription sale that started on a web page, but was approved later.	transaction_id_one	Yes
subid	str	This is the unique Id from your internal system so we can track a Subscription repeating. This can be the same or different from the Transaction Id. If you don't tag your subscriptions with a unique Id, then simply repeat the transaction Id in this field.	subscription_id_one	Yes
cid	str	We can use Customer Ids in the Cubed system to help link external and internal data, similar to using Transaction Id. It is not needed as we usually join on Transaction Id, but does give us more data for the Subscription hits we receive.	customer_id_one	No
evt	str	The evt is the event type for the subscription event, this could be a newsletter or any other type of subscription event.	newsletter	Yes
rvn	int	Revenue is collected as British pence in Integer format. See our Tag for further information on this. If left blank, we will default the revenue to zero.	100	No

Simulate

The simulate parameter is a boolean value that determines whether the request is a simulation or not. If simulate is set to true, the request will not be stored in the database. This is useful for testing the API without affecting the data in the client database. If simulate is not provided in the request body, it will default to false.

Timeouts

This API is implemented as an AWS Lambda function and has been configured with a timeout of 5 seconds. If the request takes longer than 5 seconds to process, the API will return a 504 Gateway Timeout response.

If you are experiencing timeouts, you may need to reduce the number of objects in the data parameter or contact your account manager to discuss increasing the timeout limit.

If a timeout occurs, the data sent in the response will NOT be stored in the database. Each request is inserted via a database transaction and if the transaction fails, the data is not stored. This is to ensure data integrity.

Examples

Python

import requests
import json

# The URL of the Lambda function endpoint
url = "https://api.withcubed.com/subscription"

data = {
    "simulate": True,  # OPTIONAL. If set to True, the request will not be stored in the database.
    "aid": "example_account_id",
    "data": [
        {
            "tid": "example_transaction_id",
            "subid": "example_subscription_id",
            "cid": "example_customer_id",
            "evt": "example_event",
            "rvn": 10
        }
    ],
}

# Convert the Python dictionary to a JSON string
data_json = json.dumps(data)

# Set the appropriate headers for a JSON request
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<your-api-key>",
}

response = requests.post(url, data=data_json, headers=headers)

Node.js

const axios = require("axios");

// The URL of the Lambda function endpoint
const url = "https://api.withcubed.com/subscription";

const data = {
  simulate: true, // OPTIONAL. If set to true, the request will not be stored in the database.
  aid: "example_account_id",
  data: [
    {
      tid: "example_transaction_id",
      subid: "example_subscription_id",
      cid: "example_customer_id",
      evt: "example_event",
      rvn: 10
    },
  ],
};

// Set the appropriate headers for a JSON request
const headers = {
  "Content-Type": "application/json",
  "X-API-Key": "<your-api-key>",
};

axios
  .post(url, data, { headers })
  .then((response) => {
    // Handle the response
  })
  .catch((error) => {
    // Handle the error
  });