Getting Started with Paigo

This chapter describes a hands-on guide for getting started with Paigo platform. The chapter will guide through a typical case of SaaS billing setup and get ready to bill customers with usage-based pricing strategy. Guidance on further exploring additional features are also provided at the end of the chapter.
Overview
There are three major steps to get started with Paigo.
Billing Setup
Report usage data
Use the data
First, create an account with Paigo by connecting with sales team, or sign up for Free Trial Plan. With account credentials, navigate to Paigo dashboard and login.
Billing Setup
There are a few resources to be created for setting up billing: a dimension, an offering and a customer.
Dimension
Dimension defines a product metric that is used for billing purpose. Navigate to Dimension tab and click on New Dimension. In the form, first provide a dimension name, such as Data Processed. In the Usage Measurement dropdown, choose Skip / API-based Measurement, then click Continue. Set value for the following fields with value suggested, and leave everything else as default. Click Submit on the top right corner to save.
Field
Value
Consumption Unit
Gigabyte (Data)
Consumption Price
$0.08
This dimension keeps track of the amount of data processed for a particular customer in terms of gigabytes. The dimension also defines how bills are calculated with those fields related to aggregations etc. See screenshot below for an example.
Offering
Offering defines a pricing plan that customers subscribe to. Navigate to Offering tab and click on New Offering. In the form, provide an Offering Name, such as Pay-as-you-go. Under the Usage Dimension dropdown, select the dimension just created above. Click Submit on the top right corner to save. See screenshot below for an example.
Customer
Customer defines the identity that will be billed. Navigate to Customer tab and click on New Customer. In the form, fill in all the required fields, and leave other fields with default values. Note the following fields:
Stripe Payment Account ID: it should be the account ID found in Stripe Dashboard, in the form of  usually located at the bottom right corner of the Stripe Settings page. Note that in this step, we are taking the SaaS customer's Stripe account, which will be used to make payment. For demonstration purpose, you can use a fake Stripe account ID such as acct_1MV2hfFMNNPXLiB. 
Offering: select the offering Pay-as-you-go created above from the dropdown. By selecting this offering, this customer's usage will be billed based on the pricing detailed defined in the offering.
Click Submit on the top right corner to save. See screenshot below for an example.
Now we have set up all the necessary resources for billing. Next we are going to get some sample data to mock the usage of customer Dumm AI Corp!
Collect Usage
Paigo provides a powerful usage measurement and collection engine to measure SaaS customer's usage of software in real-time and collect them to Paigo backend. In this guide, we are going to use Paigo dashboard to create usage record and also use a sample script for sending mocked usage data to Paigo. Recall in the above steps, we have created a dimension called Data Processed. So in this step, we are going to send the data size processed continuously with some interval to mock the behavior of a hypothetical application.
Using Dashboard
From Paigo Dashboard, usage data can be recorded without writing code. Navigate to Customer tab and select the customer Dumm AI Corp from the table. In the customer view, scroll down to Usage Monitoring and click on the Record Usage button. In the Record Usage form, the fields of Customer ID and Dimension ID, are all prefilled. Set value for the following fields with suggested value:
Field
Value
Record Value
0.8
Timestamp
Leave as default (current time)
Record Metadata (Key)
Foo
Record Metadata (Value)
Bar
Click on Add Metadata to add the key-value pair to metadata. See screenshot below for an example.
In the Preview Record Code Snippet section down below, the code to create the same usage record is provided. Click on the Copy button on the top right corner of Preview Record Code Snippet to copy the code. Click Submit button to submit the usage record.
At this point, we have already posted exactly one usage record for the service specified. Now let's explore more automated way to continuously collect usage data.
Using Script
Paigo API can be used to measure and collect usage data for SaaS application. In this guide, we are using a sample script to demonstrate how it works with Paigo's API-based Method. There are more intelligent methods of usage measurement documented in Measure and Collect Usage Data at Scale chapter. Download the below script to a local machine as ingestToPaigo.js and modify the 4 lines marked with TODO as the instruction below.
Javascript (Node JS)
Python
1
// npm i cross-fetch --save
2
const fetch = require("cross-fetch");
3
​
4
const sleep = time => new Promise(res => setTimeout(res, time, "done sleeping"));
5
​
6
const ingestToPaigo = async () => {
7
    const authResponse = await fetch('https://auth.paigo.tech/oauth/token', {
8
        method: 'POST',
9
        headers: {
10
            'Accept': 'application/json',
11
            'Content-Type': 'application/json',
12
        },
13
        body: JSON.stringify({
14
            "audience": "https://qnonyh1pc7.execute-api.us-east-1.amazonaws.com",
15
            "grant_type": "client_credentials",
16
            "client_id": "client_id", // TODO
17
            "client_secret": "client_secret" // TODO
18
        })
19
    })
20
    const bearerToken = JSON.parse(await authResponse.text()).access_token;
21
    for (let i = 0; i < 120; i++) {
22
        await postUsageRecord(bearerToken);
23
        await sleep(1000);
24
    }
25
    console.log(bearerToken);
26
};
27
​
28
const postUsageRecord = async (bearerToken) => {
29
    const response = await fetch('https://api.prod.paigo.tech/usage', {
30
        method: 'POST',
31
        headers: {
32
            'Accept': 'application/json',
33
            'Content-Type': 'application/json',
34
            'Authorization': 'Bearer ' + bearerToken,
35
        },
36
        body: JSON.stringify({
37
            "timestamp": new Date().toISOString(),
38
            "customerId": "customerId", // TODO
39
            "dimensionId": "dimensionId", // TODO
40
            "recordValue": "1",
41
            "metadata": {}
42
        })
43
    })
44
    console.log(await response.text());
45
};
46
​
47
ingestToPaigo();
1
# python3 -m pip install requests
2
import requests
3
import json
4
from time import sleep
5
from datetime import datetime
6
   
7
def post_usage_record(bearer_token):
8
    current_time = datetime.utcnow().replace(microsecond=0).isoformat() + "Z"
9
    response = requests.post('https://api.prod.paigo.tech/usage', 
10
        headers={
11
            'Accept': 'application/json',
12
            'Content-Type': 'application/json',
13
            'Authorization': 'Bearer ' + bearer_token,
14
        },
15
        data=json.dumps({
16
            "timestamp": current_time,
17
            "customerId": "customerId", // TODO
18
            "dimensionId": "dimensionId" // TODO,
19
            "recordValue": "1",
20
            "metadata": {}
21
        })
22
    )
23
    print(response.text)
24
​
25
def ingest_to_paigo():
26
    auth_response = requests.post('https://auth.paigo.tech/oauth/token', 
27
        headers={
28
            'Accept': 'application/json',
29
            'Content-Type': 'application/json',
30
        },
31
        data=json.dumps({
32
            "audience": "https://qnonyh1pc7.execute-api.us-east-1.amazonaws.com",
33
            "grant_type": "client_credentials",
34
            "client_id": "client_id", // TODO
35
            "client_secret": "client_secret" // TODO
36
        })
37
    )
38
    bearer_token = json.loads(auth_response.text)['access_token']
39
    for _ in range(120):
40
        post_usage_record(bearer_token)
41
        sleep(1)
42
​
43
ingest_to_paigo()
Client ID: the client id used for authentication. Should be provided when signing up.
Client Secret: the client secret used for authentication. Should be provided when signing up.
Customer ID: navigate to Customer tab in Paigo dashboard and click in the table the Dumm AI Corp customer profile just created in the step above. In the customer view, copy the Customer ID in the customer information widget and paste it on the line marked with customerId. It should be in the form of UUID.
Dimension ID: navigate to Dimension tab in Paigo dashboard and click in the table the Data Processed dimension just created in the above step. In the dimension view, copy the Dimension ID and paste it on the line marked with dimensionId. It should be in the form of UUID.
Save the script and run locally with the following command:
node ingestToPaigo.js
This script first authenticates with Paigo API, then sends a number that mimics the amount of data processed every 1 second to Paigo server. The script will stop by itself after 120 seconds. 
Now we have some usage data collected, we are going to see how Paigo can leverage them for billing.
Usage Analytics and Invoicing
Once the usage data gets measured and collected to Paigo backend, they can be viewed and visualized as the usage history of a customer. Navigate to Customer tab and select the Dumm AI Corp from the table. From the customer profile view, the Usage Monitoring widget shows the live-streamed usage data that was just sent from the above step to Paigo backend. See below screenshot for an example.
Next, we are going to explore the usage data collected in aggregated form and raw form. In the same customer profile view, navigate to Usage Data widget on the page. By default, the raw usage data collected in the current month will be shown in the usage data table. See below screenshot for an example.
Alternatively, set Aggregation as Daily and click View. Now all of the usage data are grouped by day, and all data points in the same day are added together to calculate the sum, because in the dimension configuration, we have set the Aggregation Method as sum. See screenshot below for an example.
With usage data measured and collected by Paigo as such, at the end of a billing cycle, Paigo will automatically aggregate all the usage attributed to a customer, generate a tax-compliant invoice for review, and process payment for the bill. We are going to run an off-cycle invoice to bill customers based on their usage so far.
In the same customer profile view, click on the Off-cycle Invoice button in the Invoice widget. At the invoice creation form, you can choose to Manually Enter Line Items to invoice customers on, or just Select Billing Period for Paigo to bill customers based on the corresponding usage. The default dates for billing period is this current calendar month so far. Click the Submit button to create an off-cycle invoice for the usage occurred so far. See the screenshot below for an example.
Once an invoice is generated, select the invoice draft from the Invoice Table at the bottom of the Customer profile page, and click on Actions -> Download to view the invoice. You can also choose to perform other actions on the invoice from the same menu.
Other use case of the usage data ingested including usage-based cost analytics, margin analysis, pricing optimization, etc.
Next Steps
To explore Paigo's different ways of measuring and collecting usage of SaaS applications, read Measure and Collect Usage Data at Scale chapter for full documentation.
To explore more ways of modeling pricing strategies in Paigo, read Pricing Plan and Sale Deals chapter for full documentation.
To understand the key concepts in Paigo and how they work together, read Key Conceptspage for more details.
Field	Value
Consumption Unit	Gigabyte (Data)
Consumption Price	$0.08
Field	Value
Record Value	0.8
Timestamp	Leave as default (current time)
Record Metadata (Key)	Foo
Record Metadata (Value)	Bar
Last modified 12d ago