API docs by Redocly

Paigo API (v1.10)

For developer documentation of the platform, please visit https://docs.paigo.tech.

Authentication

Paigo API supports bearer token as the authentication method. Steps to set up authentication:

  1. Sign up with Paigo platform and get client id and client secret.

  2. Make a POST request to the auth endpoint https://auth.paigo.tech/oauth/token with the following body:

    {
     audience: 'https://qnonyh1pc7.execute-api.us-east-1.amazonaws.com',
     grant_type: 'client_credentials',
     client_id: <your client id>,
     client_secret: <your client secret>
}

    Additionally verify that the following headers are set by the client you are using: 

    {
 "Content-Type": "application/json"
}

  3. Use the access token in the response to make requests to the Paigo API. Here is an example of the response: 

    {
         access_token: <your access token>,
         expires_in: 86400,
         token_type: 'Bearer'  
}

  4. To use Paigo API, add in the header of your request:

    {
     Authorization: "Bearer <your access token>"
}

API Endpoints

Paigo API has the following endpoint:

  • Production Environment API: https://api.prod.paigo.tech

Usage

Measure and collect usage data.

Collect usage data

Collect usage data by API-based method. See Measure and Collect Usage Data At Production Scale for full documentation on Paigo Usage Measurement and Collection.

Authorizations:
bearer
query Parameters
invoice
boolean
Example: invoice=true

The invoice query parameter is used to create an invoice for the usage data body. It can only be used with dimensions that have an upfront payment schedule and last aggregation method. If the dimension does not have these properties, the invoice will not be created and a 400 status code will be returned. Additionally, the customer for the usage must be actively enrolled in an offering in order to make use of the automated invoice, otherwise a 400 error will be returned. The body will not be loaded into the database on any 400 error.

The invoice created is independent of any tiers, or entitlement associated with the dimension, and will be created for the exact usage data sent in.

The invoice will be created for the difference between the usage data sent in, and the most recent usage data for the dimension. If the usage data sent in is less than the most recent usage data, a zero quantity line item will be created. For example if the most recent usage data for a dimension is 5, and the usage data sent in is 3, a zero quantity line item will be created. If the usage data sent in is 7, a 2 quantity line item will be created.

Request Body schema: application/json
dimensionId
required
string

The unique identifier of the dimension this usage record is associated with.

Example: 'da9611bd-e0f3-4c0d-a754-fda5be730872'

timestamp
required
string

The timestamp of usage record in RFC3339 format with a 4-digit year. This is the time the usage occurred, or the end of the usage period.

Example: "2023-02-08T19:24:10Z"

customerId
required
string

The unique identifier of the customer this usage record attributes to.

Example: "e8366954-6f36-47e9-8431-ac95f88b5cc7"

recordValue
required
string

The amount of the usage on this record. Numerical values are represented as strings to avoid precision loss.

Example: "0.87"

metadata
object

An optional key-value map of additional metadata to associate with this usage record. Additional metadata to be stored on the usage record, such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Metadata can be used for analytics purpose.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe"}

Responses

Request samples

Content type
application/json
{
  • "dimensionId": "string",
  • "timestamp": "string",
  • "customerId": "string",
  • "recordValue": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Dimensions

Manage dimensions in Paigo.

Get all dimensions

List all dimensions created in this account

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Create a dimension

Create a dimension

See an example dimension for pay as you go pricing here

Authorizations:
bearer
Request Body schema: application/json
dimensionName
required
string

A friendly, human-readable name for the dimension.

Example "API Call"

required
CountBasedConsumptionUnit (object) or TimeBasedConsumptionUnit (object) or DatabasedConsumptionUnit (object)

Consumption unit of the dimension. Paigo supports three types of consumption units: count-based, time-based, and data-based. Supported values for each consumption unit type are listed below.

  • count: "count-based"
  • time-based: "second", "minute", "hour", "day"
  • data-based: "byte", "kilobyte", "megabyte", "gigabyte"

This field accepts a JSON object with the following schema: 

{ "type": "typeName", "unit": "unitName" }



Example:
{ "type": "count", "unit": "count-based" }
{ "type": "time", "unit": "hour" }
{ "type": "data", "unit": "byte" }

usageIncrement
required
string

The minimum increment for usage amount. As an example, if usage increment is 1 Hour job execution time, then 1 Hour and 5 Minutes execution time may be calculated as 1 Hour or 2 Hours, depending on the rounding algorithm field of the dimension.

Example 1

See how usage increment is used in the billing process
number or string

Used with Subscription Tier Offering type.
SaaS customers subscribed to a subscription tier are entitled to use the amount of product with regard to the dimension up to the value specified in this field. For example, a subscription tier may entitle subscribers to make up to 1,000,000 API requests.

aggregationInterval
string
Default: "hour"
Enum: "none" "hour" "day" "month"

Time interval to aggregate dimension usage data for billing.

See how aggregation interval is used in the billing process
aggregationMethod
string
Default: "max"
Enum: "sum" "max" "min" "count" "average" "last"

The algorithm to aggregate raw usage data for billing.

See how aggregation method is used in the billing process
measurementId
string

The unique identifier of the measurement attached to the dimension.

rounding
required
string
Enum: "round" "floor" "ceiling"

The rounding algorithm that is used to calculate the amount of usage increment. Ceiling algorithm rounds up, floor algorithm rounds down, the round algrogrithm rounds to the nearest whole integer rounding half away from zero. As an example, if usage increment is 1 Hour job execution time, then 1 Hour and 5 Minutes execution time may be calculated as 2 Hours for ceiling algorithm, 1 Hour for floor algorithm, and 1 Hour for round algorithm. depending on the rounding algorithm field of the dimension.

overageAllowed
string
Enum: "true" "false"

Used with Subscription Tier Offering type.
When the usage entitlement is specified, this field decides if allowing SaaS customers to use more than entitled amount of the product dimension.

consumptionPrice
string

The unit price of dimension. Numerical values are represented as strings to avoid precision loss.

sampleType
string
Enum: "gauge" "continious"

The sample type used for the data. Gauge is a value that can go up or down.
Currently set to gauge by default on all dimensions.

paymentSchedule
string
Enum: "upfront" "arrear"

The payment schedule for the dimension. Determines when billing should occur for a dimension. upfront will occur the moment a customer is enrolled in an offering containing the dimension. arrear will occur at the end of the billing cycle. upfront is used for dimensions like purchasing a subscription, or seats for a plan. Where as arrear is used for dimensions like usage based billing. Dimensions can be comingled in an offering, so you can have a dimension that is billed upfront and another that is billed arrear. Optional, if not included will be arrear by default.

metadata
object

An optional key-value map of additional metadata to associate with the dimensions. such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Additionally, if null is passed for any value in the metadata object it will be removed. To entirely remove the metadata object, pass null to the metadata field.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}

In the above example, the workspaceId metadata key will be removed from the dimension. To remove all fields pass the following.

Example "metadata": null

Array of objects (DimensionTierDto)

Used to more granularly define the price of a dimension. For example if you want to charge a customer $1 for the first 1000 API calls and $0.50 for every API call after that you would define two tiers, the first tier with an upperLimit of "1000" and tierPosition of "1" with a unitPrice of "1" and a second tier with an upperLimit of "inf", tierPosition of "2" and unitPrice of "0.50". Exclusive with standard consumptionPrice, entitlement and overageAllowed fields.

Array of objects (DimensionTiersGroupByMetadataDto)

Used to group tiers by metadata, meaning instead of grouping by the dimensionId for usage Paigo will group requests with the metadata passed in on the usage request. Exclusive with standard consumptionPrice, entitlement, overageAllowed and tiers fields.

Responses

Request samples

Content type
application/json
{
  • "dimensionName": "API Call",
  • "consumptionUnit": {
    },
  • "usageIncrement": "24",
  • "usageEntitlement": "inf",
  • "aggregationInterval": "hour",
  • "aggregationMethod": "sum",
  • "measurementId": "5f7d1e3a-3b2d-4b0a-8b9a-5b9b5c9b5c9b",
  • "rounding": "round",
  • "overageAllowed": "true",
  • "consumptionPrice": "20.00",
  • "sampleType": "gauge",
  • "paymentSchedule": "upfront",
  • "metadata": { },
  • "tiers": [
    ],
  • "tiersGroupByMetadata": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "dimensionId": "fcb1fa34-8f11-4832-80f2-464cbc7a8546"
}

Get a dimension by ID

Fine a dimension

Authorizations:
bearer
path Parameters
dimensionId
required
string

The unique identifier assigned by Paigo.

Example: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Update a dimension

Update a dimension

Authorizations:
bearer
path Parameters
dimensionId
required
string

The unique identifier assigned by Paigo.

Example: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6

Request Body schema: application/json
dimensionName
string

A friendly, human-readable name for the dimension.

Example "API Call"

CountBasedConsumptionUnit (object) or TimeBasedConsumptionUnit (object) or DatabasedConsumptionUnit (object)

Consumption unit of the dimension. Paigo supports three types of consumption units: count-based, time-based, and data-based. Supported values for each consumption unit type are listed below.

  • count: "count-based"
  • time-based: "second", "minute", "hour", "day"
  • data-based: "byte", "kilobyte", "megabyte", "gigabyte"

This field accepts a JSON object with the following schema: 

{ "type": "typeName", "unit": "unitName" }



Example:
{ "type": "count", "unit": "count-based" }
{ "type": "time", "unit": "hour" }
{ "type": "data", "unit": "byte" }

usageIncrement
string

The minimum increment for usage amount. As an example, if usage increment is 1 Hour job execution time, then 1 Hour and 5 Minutes execution time may be calculated as 1 Hour or 2 Hours, depending on the rounding algorithm field of the dimension.

Example 1

See how usage increment is used in the billing process
number or string

Used with Subscription Tier Offering type.
SaaS customers subscribed to a subscription tier are entitled to use the amount of product with regard to the dimension up to the value specified in this field. For example, a subscription tier may entitle subscribers to make up to 1,000,000 API requests.

aggregationInterval
string
Default: "hour"
Enum: "none" "hour" "day" "month"

Time interval to aggregate dimension usage data for billing.

See how aggregation interval is used in the billing process
aggregationMethod
string
Default: "max"
Enum: "sum" "max" "min" "count" "average" "last"

The algorithm to aggregate raw usage data for billing.

See how aggregation method is used in the billing process
measurementId
string

The unique identifier of the measurement attached to the dimension.

Array of objects (DimensionTierDto)

In order to remove tiers from a dimension, set the tiers array to null. The value passed to the tiers array will completely replace the existing tiers array.

rounding
string
Enum: "round" "floor" "ceiling"

The rounding algorithm that is used to calculate the amount of usage increment. Ceiling algorithm rounds up, floor algorithm rounds down, the round algrogrithm rounds to the nearest whole integer rounding half away from zero. As an example, if usage increment is 1 Hour job execution time, then 1 Hour and 5 Minutes execution time may be calculated as 2 Hours for ceiling algorithm, 1 Hour for floor algorithm, and 1 Hour for round algorithm. depending on the rounding algorithm field of the dimension.

overageAllowed
string
Enum: "true" "false"

Used with Subscription Tier Offering type.
When the usage entitlement is specified, this field decides if allowing SaaS customers to use more than entitled amount of the product dimension.

consumptionPrice
string

The unit price of dimension. Numerical values are represented as strings to avoid precision loss.

sampleType
string
Enum: "gauge" "continious"

The sample type used for the data. Gauge is a value that can go up or down.
Currently set to gauge by default on all dimensions.

paymentSchedule
string
Enum: "upfront" "arrear"

The payment schedule for the dimension. Determines when billing should occur for a dimension. upfront will occur the moment a customer is enrolled in an offering containing the dimension. arrear will occur at the end of the billing cycle. upfront is used for dimensions like purchasing a subscription, or seats for a plan. Where as arrear is used for dimensions like usage based billing. Dimensions can be comingled in an offering, so you can have a dimension that is billed upfront and another that is billed arrear. Optional, if not included will be arrear by default.

metadata
object

An optional key-value map of additional metadata to associate with the dimensions. such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Additionally, if null is passed for any value in the metadata object it will be removed. To entirely remove the metadata object, pass null to the metadata field.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}

In the above example, the workspaceId metadata key will be removed from the dimension. To remove all fields pass the following.

Example "metadata": null

Array of objects (DimensionTiersGroupByMetadataDto)

Used to group tiers by metadata, meaning instead of grouping by the dimensionId for usage Paigo will group requests with the metadata passed in on the usage request. Exclusive with standard consumptionPrice, entitlement, overageAllowed and tiers fields.

Responses

Request samples

Content type
application/json
{
  • "dimensionName": "API Call",
  • "consumptionUnit": {
    },
  • "usageIncrement": "24",
  • "usageEntitlement": "inf",
  • "aggregationInterval": "hour",
  • "aggregationMethod": "sum",
  • "measurementId": "5f7d1e3a-3b2d-4b0a-8b9a-5b9b5c9b5c9b",
  • "tiers": [
    ],
  • "rounding": "round",
  • "overageAllowed": "true",
  • "consumptionPrice": "20.00",
  • "sampleType": "gauge",
  • "paymentSchedule": "upfront",
  • "metadata": { },
  • "tiersGroupByMetadata": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "dimensionId": "fcb1fa34-8f11-4832-80f2-464cbc7a8546"
}

Delete a dimension

Delete a dimension

Authorizations:
bearer
path Parameters
dimensionId
required
string

The unique identifier assigned by Paigo.

Example: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Offerings

Manage offerings in Paigo.

Get all Offerings

List all offerings created in this account

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Create an offering

Create an offering

Authorizations:
bearer
Request Body schema: application/json
offeringVisibility
string
Default: "public"
Enum: "private" "public"

The visibility of the offering, specifically if its private or public. Public offerings are designed to be shared among customers. Private offerings are typically used for enterprise deals which contain discounts or prepaid credits.

Example: "private"

offeringType
string
Default: "usage-based"
Enum: "usage-based" "subscription"

The type of offering.
• usage-based - The offering is a pure usage-based offering, or pay-as-you-go. Customers on this plan will be billed precisely based on consumption.
• subscription - The offering is a fixed subscription. Customer will be billed on a fixed price.

Example "subscription"

Read more about the different offering types
billingCycle
string
Default: "monthly"
Enum: "monthly" "annualToDate" "topUp"

The time frame when an automatic bill should be sent leave empty for no automated billing

Example "monthly"

currency
string
Enum: "USD" "EUR" "CNY"

The supported currency for the offering. USD is currently supported. Customers can override the currency for their account. However all offerings are denoted in USD.

Example "USD"

Array of objects (DimensionOverridesDto)

Overrides for the offering. Applies specific overrides to the dimensions associated with the offering. These effect the price of each dimension on the offering.

prepaidCredit
string

Prepaid credit amount to be deducted as part of the bill payments. Only numerical string is allowed.

Example: "20.00" for $20.00.

minimumCharge
string or null

A minimum charge to be billed to the customer in the event that the customer's bill is less than the minimum charge. Only on usage based offerings. Only numerical strings are allowed, must be greater than zero.

Example: "32.00" for $32.00.

topUpAmount
string

The amount to top up the account by. Only positive number string is allowed. Required if billingCycle is topUp.

Example: "20.00" for $20.00.

topUpThreshold
string

The threshold at which the account should be topped up. Only positive number string is allowed. Between 0 and 1. If not provided the default value will be 0.2 or 20%. Meaning that when the account balance reaches 20% of the the top up amount, the account will be topped up, and the end customer charged.

Example: "0.2" for 20%.

subscriptionPrice
number

The price of the subscription. Only positive number string is allowed. Only required if offeringType is subscription.

Example: 20.00 for $20.00.

freeTrialLength
string

The length of time for a free trial. This is a number of days. Only positive number string is allowed.

Example: "1" for 1 day or 1 billing cycle depending on the offeringType.

offeringName
required
string

A friendly, human-readable name for the offering.

Example "Entperise Plan"

dimensionIds
Array of strings

Array of the identifier of the dimensions that this offering contains. Dimensions specify the type of usage that is being billed for.

Example ["092f9444-851a-43fb-9503-2228dc01b1b", "4fcafdec-eeb9-4a7f-9caf-61387102b6fa"]

metadata
object

An optional key-value map of additional metadata to associate with the offerings. such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Additionally, if null is passed for any value in the metadata object it will be removed. To entirely remove the metadata object, pass null to the metadata field.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}

In the above example, the workspaceId metadata key will be removed from the dimension. To remove all fields pass the following.

Example "metadata": null

Responses

Request samples

Content type
application/json
{
  • "offeringVisibility": "private",
  • "offeringType": "subscription",
  • "billingCycle": "monthly",
  • "currency": "USD",
  • "dimensionOverrides": [
    ],
  • "prepaidCredit": "20.00",
  • "minimumCharge": "32.00",
  • "topUpAmount": "20.00",
  • "topUpThreshold": "0.2",
  • "subscriptionPrice": 20,
  • "freeTrialLength": "1",
  • "offeringName": "Entperise Plan",
  • "dimensionIds": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "offeringId": "fcb1fa34-8f11-4832-80f2-464cbc7a8546"
}

Get an offering by ID

Find an offering

Authorizations:
bearer
path Parameters
offeringId
required
string

The unique identifier assigned by Paigo.

Example: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Update an offering

Update an offering

Authorizations:
bearer
path Parameters
offeringId
required
string

The unique identifier assigned by Paigo.

Example: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6

Request Body schema: application/json
offeringVisibility
string
Default: "public"
Enum: "private" "public"

The visibility of the offering, specifically if its private or public. Public offerings are designed to be shared among customers. Private offerings are typically used for enterprise deals which contain discounts or prepaid credits.

Example: "private"

offeringType
string
Default: "usage-based"
Enum: "usage-based" "subscription"

The type of offering.
• usage-based - The offering is a pure usage-based offering, or pay-as-you-go. Customers on this plan will be billed precisely based on consumption.
• subscription - The offering is a fixed subscription. Customer will be billed on a fixed price.

Example "subscription"

Read more about the different offering types
billingCycle
string
Default: "monthly"
Enum: "monthly" "annualToDate" "topUp"

The time frame when an automatic bill should be sent leave empty for no automated billing

Example "monthly"

currency
string
Enum: "USD" "EUR" "CNY"

The supported currency for the offering. USD is currently supported. Customers can override the currency for their account. However all offerings are denoted in USD.

Example "USD"

Array of objects (DimensionOverridesDto)

Overrides for the offering. Applies specific overrides to the dimensions associated with the offering. These effect the price of each dimension on the offering.

prepaidCredit
string

Prepaid credit amount to be deducted as part of the bill payments. Only numerical string is allowed.

Example: "20.00" for $20.00.

minimumCharge
string or null

A minimum charge to be billed to the customer in the event that the customer's bill is less than the minimum charge. Only on usage based offerings. Only numerical strings are allowed, must be greater than zero.

Example: "32.00" for $32.00.

topUpAmount
string

The amount to top up the account by. Only positive number string is allowed. Required if billingCycle is topUp.

Example: "20.00" for $20.00.

topUpThreshold
string

The threshold at which the account should be topped up. Only positive number string is allowed. Between 0 and 1. If not provided the default value will be 0.2 or 20%. Meaning that when the account balance reaches 20% of the the top up amount, the account will be topped up, and the end customer charged.

Example: "0.2" for 20%.

subscriptionPrice
number

The price of the subscription. Only positive number string is allowed. Only required if offeringType is subscription.

Example: 20.00 for $20.00.

freeTrialLength
string

The length of time for a free trial. This is a number of days. Only positive number string is allowed.

Example: "1" for 1 day or 1 billing cycle depending on the offeringType.

offeringName
string

A friendly, human-readable name for the offering.

Example "Entperise Plan"

dimensionIds
Array of strings

Array of the identifier of the dimensions that this offering contains. Dimensions specify the type of usage that is being billed for.

Example ["092f9444-851a-43fb-9503-2228dc01b1b", "4fcafdec-eeb9-4a7f-9caf-61387102b6fa"]

metadata
object

An optional key-value map of additional metadata to associate with the offerings. such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Additionally, if null is passed for any value in the metadata object it will be removed. To entirely remove the metadata object, pass null to the metadata field.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}

In the above example, the workspaceId metadata key will be removed from the dimension. To remove all fields pass the following.

Example "metadata": null

Responses

Request samples

Content type
application/json
{
  • "offeringVisibility": "private",
  • "offeringType": "subscription",
  • "billingCycle": "monthly",
  • "currency": "USD",
  • "dimensionOverrides": [
    ],
  • "prepaidCredit": "20.00",
  • "minimumCharge": "32.00",
  • "topUpAmount": "20.00",
  • "topUpThreshold": "0.2",
  • "subscriptionPrice": 20,
  • "freeTrialLength": "1",
  • "offeringName": "Entperise Plan",
  • "dimensionIds": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "offeringId": "fcb1fa34-8f11-4832-80f2-464cbc7a8546"
}

Delete an offering

Delete an offering

Authorizations:
bearer
path Parameters
offeringId
required
string

The unique identifier assigned by Paigo.

Example: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "offeringId": "539b7f74-3832-474e-a955-6d69c5df12d0"
}

Customers

Manage customers in Paigo.

Get all Customers

List all customers created in this account

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Create a customer

Create a customer

Authorizations:
bearer
Request Body schema: application/json
currency
string
Enum: "USD" "EUR" "CNY"

The customer's preferred currency. Only ISO 4217 currency codes are allowed. Overrides the currency on an offering. If not specified, the currency on the offering will be used. If no currency is specified on the offering, the default currency of "USD" will be used.

Example "USD"

taxExempt
string
Default: "none"
Enum: "exempt" "none"

Whether the customer is exempt from paying taxes

Example: "none"

customerId
string

Unique identifier for a customer. If one is not passed in Paigo will assign a unique UUID for the customer. If one is passed in and it already exists an error will be returned.

Example: "e345f409-daca-4144-91d2-0a0f87c96581"

offeringId
string

The unique identifier for the offering associated with a customer

Example: "eea7347bd-a2d8-4390-ae09-68f9b8e4ed6c"

offeringEnrollmentDate
string

The date time when the user was enrolled in the offering. If not set the current date time will be used. Must be a valid RFC3339 date time string. Must be in the past UTC time.

Example: "2020-01-01T00:00:00Z"

customerName
required
string

The friendly, human-readable name for the customer profile

Example: "John Doe"

customerVatId
string

The VAT ID of the customer. Every VAT identification number must begin with the code of the country concerned and followed by a block of digits or characters.

Example "GB VAT 123456789"

email
required
string

Customer email address

Example: "noreply@paigo.tech"

paymentChannel
required
string
Enum: "Stripe" "manual"

The payment channel associated with a customer

Example: "Stripe"

object

Configuration options for the payment channel. For Stripe payment, stripeCustomerId is required for existing Stripe customers. If stripeCustomerId is not provided, a new Stripe customer will be created. See example below.

Example {"stripeCustomerId": "cus_xxxxxxxxxxxxxx"}

object

The address of the customer

metadata
object

An optional key-value map of additional metadata to associate with the customer. such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Additionally, if null is passed for any value in the metadata object it will be removed. To entirely remove the metadata object, pass null to the metadata field.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}

In the above example, the workspaceId metadata key will be removed from the dimension. To remove all fields pass the following.

Example "metadata": null

Array of objects (UsageForCustomerEnrollment)

Optionally, usage can be initally applied for a customer when they are enrolling in an offering. This is used for dimensions which have a paymentSchedule of upfront and need to have some usage for the intial enrollment. For example, a customer purchases 3 seats then on the enrollment a usage recordValue of 3 must be sent in for the time of purchase. Multiple usage records can be sent in, regardless of dimension. If usage records are sent in for a dimension that is not on the current offering, they will be loaded into paigo, but ignored on the invoice.

Example: [{ "dimensionId": "539b7f74-3832-474e-a955-6d69c5df12d0", "customerId":"f918b6f4-2ad6-48c4-8b62-ac23adada9ae", "recordValue": 3, timestamp: "2021-01-01T00:00:00Z" }]

Responses

Request samples

Content type
application/json
{
  • "currency": "USD",
  • "taxExempt": "none",
  • "customerId": "e345f409-daca-4144-91d2-0a0f87c96581",
  • "offeringId": "eea7347bd-a2d8-4390-ae09-68f9b8e4ed6c",
  • "offeringEnrollmentDate": "2020-01-01T00:00:00Z",
  • "customerName": "John Doe",
  • "customerVatId": "GB VAT 123456789",
  • "email": "noreply@paigo.tech",
  • "paymentChannel": "Stripe",
  • "paymentChannelOptions": {
    },
  • "address": {
    },
  • "metadata": { },
  • "usage": "[{ \"dimensionId\": \"539b7f74-3832-474e-a955-6d69c5df12d0\", \"customerId\":\"f918b6f4-2ad6-48c4-8b62-ac23adada9ae\", \"recordValue\": 3, timestamp: \"2021-01-01T00:00:00Z\" }]"
}

Response samples

Content type
application/json
{}

Assign a child to a customer

Assign a child to a customer

Authorizations:
bearer
Request Body schema: application/json
billParent
string
Default: "separate"
Enum: "aggregated" "separate"

This determines if the parent should be billed for invoices of the child. Defaults to separate.

Example: "aggregated"

Responses

Request samples

Content type
application/json
{
  • "billParent": "aggregated"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Remove a child from a customer

Remove a child from parent

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Update a child to a customer

Update child relationship

Authorizations:
bearer
Request Body schema: application/json
billParent
string
Default: "separate"
Enum: "aggregated" "separate"

This determines if the parent should be billed for invoices of the child. Defaults to separate.

Example: "aggregated"

Responses

Request samples

Content type
application/json
{
  • "billParent": "aggregated"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Get a customer by ID

Find one customer

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Update a customer

Update a customer

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Request Body schema: application/json
currency
string
Enum: "USD" "EUR" "CNY"

The customer's preferred currency. Only ISO 4217 currency codes are allowed. Overrides the currency on an offering. If not specified, the currency on the offering will be used. If no currency is specified on the offering, the default currency of "USD" will be used. Cannot be Updated if a customer has an active balance of credits

Example "USD"

taxExempt
string
Default: "none"
Enum: "exempt" "none"

Whether the customer is exempt from paying taxes

Example: "none"

freeTrialEndDate
string

Free Trial End Date is the date time when a free trial is over for the customer. Must be in the future and a valid RFC 3999 date time.

Example: "2199-02-01T11:00:00Z"

removePriorOffering
boolean

An optional flag to remove the prior offering from the customer. If set to true, the customer will be removed from all of their prior offerings. This may generate an invoice, in cases where relevant. Such as if the "offeringType" is a usage-based offering. If set to false, the customer will remain enrolled in the same offering.

Example: true

unenrollOffering
string

Used to specifically unenroll a customer from a singular offering. This may generate an invoice, in cases where relevant. Such as if the "offeringType" is a usage-based offering. Cannot be used in conjunction with removePriorOffering or enrolling a customer in a new offering with theofferingId field. A 400 error will be returned if this is the case.

Example: "177735fe-5d06-49a7-a8fb-f5da11773345"

offeringId
string

The unique identifier for the offering associated with a customer

Example: "eea7347bd-a2d8-4390-ae09-68f9b8e4ed6c"

customerName
string

The friendly, human-readable name for the customer profile

Example: "John Doe"

customerVatId
string

The VAT ID of the customer. Every VAT identification number must begin with the code of the country concerned and followed by a block of digits or characters.

Example "GB VAT 123456789"

email
string

Customer email address

Example: "noreply@paigo.tech"

paymentChannel
string
Enum: "Stripe" "manual"

The payment channel associated with a customer

Example: "Stripe"

object

Configuration options for the payment channel. For Stripe payment, stripeCustomerId is required for existing Stripe customers. If stripeCustomerId is not provided, a new Stripe customer will be created. See example below.

Example {"stripeCustomerId": "cus_xxxxxxxxxxxxxx"}

object

The address of the customer

metadata
object

An optional key-value map of additional metadata to associate with the customer. such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Additionally, if null is passed for any value in the metadata object it will be removed. To entirely remove the metadata object, pass null to the metadata field.

Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}

In the above example, the workspaceId metadata key will be removed from the dimension. To remove all fields pass the following.

Example "metadata": null

Array of objects (UsageForCustomerEnrollment)

Optionally, usage can be initally applied for a customer when they are enrolling in an offering. This is used for dimensions which have a paymentSchedule of upfront and need to have some usage for the intial enrollment. For example, a customer purchases 3 seats then on the enrollment a usage recordValue of 3 must be sent in for the time of purchase. Multiple usage records can be sent in, regardless of dimension. If usage records are sent in for a dimension that is not on the current offering, they will be loaded into paigo, but ignored on the invoice.

Example: [{ "dimensionId": "539b7f74-3832-474e-a955-6d69c5df12d0", "customerId":"f918b6f4-2ad6-48c4-8b62-ac23adada9ae", "recordValue": 3, timestamp: "2021-01-01T00:00:00Z" }]

Responses

Request samples

Content type
application/json
{
  • "currency": "USD",
  • "taxExempt": "none",
  • "freeTrialEndDate": "2199-02-01T11:00:00Z",
  • "removePriorOffering": true,
  • "unenrollOffering": "177735fe-5d06-49a7-a8fb-f5da11773345",
  • "offeringId": "eea7347bd-a2d8-4390-ae09-68f9b8e4ed6c",
  • "customerName": "John Doe",
  • "customerVatId": "GB VAT 123456789",
  • "email": "noreply@paigo.tech",
  • "paymentChannel": "Stripe",
  • "paymentChannelOptions": {
    },
  • "address": {
    },
  • "metadata": { },
  • "usage": "[{ \"dimensionId\": \"539b7f74-3832-474e-a955-6d69c5df12d0\", \"customerId\":\"f918b6f4-2ad6-48c4-8b62-ac23adada9ae\", \"recordValue\": 3, timestamp: \"2021-01-01T00:00:00Z\" }]"
}

Response samples

Content type
application/json
{
  • "currency": "USD",
  • "taxExempt": "none",
  • "customerId": "e345f409-daca-4144-91d2-0a0f87c96581",
  • "offeringId": "eea7347bd-a2d8-4390-ae09-68f9b8e4ed6c",
  • "offeringEnrollmentDate": "2020-01-01T00:00:00Z",
  • "customerName": "John Doe",
  • "customerVatId": "GB VAT 123456789",
  • "email": "noreply@paigo.tech",
  • "paymentChannel": "Stripe",
  • "paymentChannelOptions": {
    },
  • "address": {
    },
  • "metadata": { },
  • "usage": "[{ \"dimensionId\": \"539b7f74-3832-474e-a955-6d69c5df12d0\", \"customerId\":\"f918b6f4-2ad6-48c4-8b62-ac23adada9ae\", \"recordValue\": 3, timestamp: \"2021-01-01T00:00:00Z\" }]"
}

Delete a customer

Delete a customer

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "customerId": "e345f409-daca-4144-91d2-0a0f87c96581"
}

Create a refund for customer

Create Customer Refund

NOTE: This endpoint currently only supports Stripe for a refund channel. Customers with manual payments will cause an 400 error response.

Authorizations:
bearer
Request Body schema: application/json
reason
string
Default: "requested_by_customer"
Enum: "duplicate" "fraudulent" "requested_by_customer"

A stripe platform specific reason enum. Not required, will be defaulted to "requested_by_customer"

Example "duplicate"

https://stripe.com/docs/api/refunds/create#create_refund-reason
amount
string

The refund amount to be delivered to the customer. Currency is determined by the currency Only numerical string is allowed. If no amount is specified the full amount of the payment will be refunded.

Example: "10.00" for $10.00.

required
object

Configuration options for the refund channel. See example below.

Example {"paymentIntentId": "pi_1Gszkg2eZvKYlo2C6ZLlAL7u"}

metadata
object

An optional key-value map of additional metadata to associate with this refund. This metadata will be passed to the final refund channel to correlate information between invoices, customers and other platform specific keys.

Example {"environment": "staging", "purpose": "Outage reported", "owner": "John Doe", "invoiceId": "123-abc-456"}

Responses

Request samples

Content type
application/json
{
  • "reason": "duplicate",
  • "amount": "10.00",
  • "refundChannelOptions": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Get a refund for customer

Get customer refunds

NOTE: This endpoint currently only supports Stripe for a refund channel. Customers with manual payments will cause an 400 error response.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Get a Customer Enrollment

Get a Customer Enrollment

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Update Customer Offering Enrollment

Update Customer Enrollment

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Request Body schema: application/json
object

Overrides for the offering. Applies Customer specific overrides to the offering. Such as a discount or free trial or dimension specific overrides.

offeringId
string

Unique identifier for an offering assigned by Paigo. Including a new "offeringId" will "enroll" the customer in the specified offering. This may generate an invoice, in cases where relevant. Such as if the "offeringType" is a subscription offering.

To unenroll customers from an offering. Pass in null. This will remove the offering from the customer. This may generate an invoice, in cases where relevant. Such as if the "offeringType" is a usage-based offering.

Including the same "offeringId" multiple times in a row will not change the state of the customer, nor generate an invoice. If an "offeringId" is not included, the customer will remain enrolled in the same offering. Including a new "offeringId" while a customer is enrolled in an offering, is considered a change of plan or "upgrade". In specific cases of upgrades some credit might be issued for the remainder of their plan.



Example: 539b7f74-3832-474e-a955-6d69c5df12d0

removePriorOffering
boolean

An optional flag to remove the prior offering from the customer. If set to true, the customer will be removed from all of their prior offerings. This may generate an invoice, in cases where relevant. Such as if the "offeringType" is a usage-based offering. If set to false, the customer will remain enrolled in the same offering.

Example: true

unenrollOffering
string

Used to specifically unenroll a customer from a singular offering. This may generate an invoice, in cases where relevant. Such as if the "offeringType" is a usage-based offering. Cannot be used in conjunction with removePriorOffering or enrolling a customer in a new offering with theofferingId field. A 400 error will be returned if this is the case.

Example: "177735fe-5d06-49a7-a8fb-f5da11773345"

Array of objects (UsageForCustomerEnrollment)

Optionally, usage can be initally applied for a customer when they are enrolling in an offering. This is used for dimensions which have a paymentSchedule of upfront and need to have some usage for the intial enrollment. For example, a customer purchases 3 seats then on the enrollment a usage recordValue of 3 must be sent in for the time of purchase. Multiple usage records can be sent in, regardless of dimension. If usage records are sent in for a dimension that is not on the current offering, they will be loaded into paigo, but ignored on the invoice. Additionally, records must be unique in the sense that they cannot have the same dimensionId. Duplicates will cause the request to be rejected.

Example: [{ "dimensionId": "539b7f74-3832-474e-a955-6d69c5df12d0", "recordValue": 3, timestamp: "2021-01-01T00:00:00Z" }]

Responses

Request samples

Content type
application/json
{
  • "overrides": {
    },
  • "offeringId": "539b7f74-3832-474e-a955-6d69c5df12d0",
  • "removePriorOffering": true,
  • "unenrollOffering": "177735fe-5d06-49a7-a8fb-f5da11773345",
  • "usage": "[{ \"dimensionId\": \"539b7f74-3832-474e-a955-6d69c5df12d0\", \"recordValue\": 3, timestamp: \"2021-01-01T00:00:00Z\" }]"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Get payments for customer

Get customer payments

NOTE: This endpoint currently only supports Stripe for a payment channel. Customers with manual payments will cause an 400 error response.

Authorizations:
bearer
query Parameters
invoiceId
string
Example: invoiceId=476b84a0-bba7-4e05-9040-59cffdff493a

The Paigo invoiceId associated with the stripe payment. Can be undefined. This operation instructs paigo to search for payments with the given invoiceId in the metadata of the payment intent.

Example: "476b84a0-bba7-4e05-9040-59cffdff493a"

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Get Stripe Portal for customer

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{}

Update free trial

Update a free trial of a customer

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Request Body schema: application/json
offeringId
string
freeTrialEndDate
required
string

The end date of the free trial. Must be in the future and must be an RFC3339 date string.

Example: "2021-01-01T00:00:00Z"

freeTrialStartDate
string

The start date of the free trial. Must be in the future and must be an RFC3339 date string. Optional to set, determines the free trial start date for a customer. This is used during billing calculations to determine the proration amount for their free trial invoice.

Example: "2021-01-01T00:00:00Z"

Responses

Request samples

Content type
application/json
{
  • "offeringId": "string",
  • "freeTrialEndDate": "2021-01-01T00:00:00Z",
  • "freeTrialStartDate": "2017-01-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "customerId": "e345f409-daca-4144-91d2-0a0f87c96581"
}

Get usage data for a customer

Get usage data for a customer

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

query Parameters
aggregationInterval
string
Enum: "none" "hour" "day" "month"

The aggregation interval to use for the query.

Default: the aggregation interval defined in the dimension definition.

ignoreEnrollmentDate
string

If the current offering enrollment date should be ignored for the response data. Enables looking at usage prior to the enrollment date.

Default: false

aggregationPurpose
string
Enum: "billing" "metering"

The aggregation purpose to use for the query. Enum: "billing", "metering"

Default: "billing"

endTime
string

The end time of the time range to query. The time range is inclusive of the start time and exclusive of the end time. The end time must be after the start time. The end time must be before the current time. The end time must be in RFC3339 format.

Example: "2020-01-01T00:00:00Z"

startTime
string

The end time of the time range to query. The time range is inclusive of the start time and exclusive of the end time. The end time must be after the start time. The end time must be before the current time. The end time must be in RFC3339 format.

Example: "2020-01-01T00:00:00Z"

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": {
    }
}

Get a customer auth token

Get a token to allow SaaS customers to view their billing data in paigo securely

Authorizations:
bearer
path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: 248fc14e-9934-4d3c-a39f-ce43cbb3f7b2

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Create a wallet transaction

Commit a transaction to the ledger for a customer. This will update thier credit balances

path Parameters
customerId
required
string
Request Body schema: application/json
transactionAmount
required
string [ -1000000000 .. 1000000000 ]

The amount to credit the customer. Can be positive or negative. Customers cannot have a negative balance set via the API.

Example: "100.00"

timestamp
string

The timestamp of the credit. Optional. Will be set to right now UTC if not provided.

Example: "2021-01-01T00:00:00.000Z"

metadata
object

The metadata to attach to the credit. Optional

Example: {"key": "value"}

Responses

Request samples

Content type
application/json
{
  • "transactionAmount": "100.00",
  • "timestamp": "2021-01-01T00:00:00.000Z",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}

Get customer credit ledger

Get the ledger of wallet transactions applied to a customer

path Parameters
customerId
required
string

The unique identifier assigned by Paigo.

Example: f8e8c18c-0a59-40f4-bf72-356090366355

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Invoices

Manage invoices in Paigo.

Get an Invoice by ID

Find an Invoice

Download links for invoices are valid for 7 days.

Authorizations:
bearer
path Parameters
invoiceId
required
string
Example: 7c71590b-3368-4d53-b9cb-5203605b4946

The invoice ID assigned by Paigo

query Parameters
download
string
Example: download=true

Get a download link for the invoice in the response

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Create

Authorizations:
bearer
Request Body schema: application/json
customerId
required
string

The client ID assocaited with the Business Entity, this is the name for the business which will be used in the invoce

Example: "Khols"

items
required
Array of objects

The Itemized collection of elements to be billed. These could be instance compute hours, or number of users

Example: [{ "name": "MyService", "quantity": 1, "unitCost": 100.09 }]

invoiceDate
string

The date the invoice is to be generated for

Example: "2020-09-18T17:34:02.666Z"

currency
string
Enum: "USD" "EUR" "CNY"

The currency the invoice is to be generated in. If no Currency is passed in the currency used by the customer will be used.

Example: "EUR"

invoicePaymentTerm
string
Enum: "30" "60" ""

The Payment Term for the invoice. This is the number of days until the invoice is considered past due. Default is "none". String "" represents "none".

Example: "30"

storePaymentAsCredit
boolean

If storePaymentAsCredit is true then the payment on the invoice will ADD to the customers credit balance. By default it is false, meaning that the payment of an invoice inside of paigo will first, deduct from the credit balance and then charge the payment method on file.

Example: true

Responses

Request samples

Content type
application/json
{
  • "customerId": "Khols",
  • "items": [
    ],
  • "invoiceDate": "2020-09-18T17:34:02.666Z",
  • "currency": "EUR",
  • "invoicePaymentTerm": "30",
  • "storePaymentAsCredit": true
}

Response samples

Content type
application/json
{ }

Measurements

Manage measurements in Paigo.

See Measure and Collect Usage Data at Production Scale for more information.

Get all measurements

List all measurements created

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Create a measurement

Create a measurement

Authorizations:
bearer
Request Body schema: application/json
measurementMode
required
string
Enum: "infrastructureBased" "agentBased" "datastoreBased"

The measurement method. See Measure and Collect Usage Data at Production Scale for more information.

Example "agentBased"

required
InfrastructureAccessInformation (object) or AgentAccessInformation (object) or DatastoreAccessInformation (object)

Configuration for the measurement method.

measurementName
string

The human readable name of the measurement

Example "EBS Usage"

Responses

Request samples

Content type
application/json
{
  • "measurementMode": "infrastructureBased",
  • "measurementConfiguration": {
    },
  • "measurementName": "EBS Usage"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "externalId": "1234567890abc",
  • "measurementId": "a65ae317-e940-44cc-b570-cc74d1897c36",
  • "iamRoleArn": "arn:aws:iam::123456789012:role/paigo-datastore-role",
  • "ingestion": "s3://paigo-datastore-dump-bucket/",
  • "dlq": "s3://paigo-datastore-dlq-bucket/"
}

Get a measurement by ID

Find a measurement

Authorizations:
bearer
path Parameters
measurementId
required
string

The unique identifier assigned by Paigo.

Example: a65ae317-e940-44cc-b570-cc74d1897c36

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Update a measurement

Update a measurement

Authorizations:
bearer
path Parameters
measurementId
required
string

The unique identifier assigned by Paigo.

Example: a65ae317-e940-44cc-b570-cc74d1897c36

Request Body schema: application/json
measurementMode
required
string
Enum: "infrastructureBased" "agentBased" "datastoreBased"
UpdateInfrastructureAccessInformation (object) or UpdateAgentAccessInformation (object) or UpdateDatastoreAccessInformation (object)

Configuration for the measurement method.

measurementName
required
string

A friendly, human-readable name of the measurement.

Responses

Request samples

Content type
application/json
{
  • "measurementMode": "infrastructure",
  • "measurementConfiguration": {
    },
  • "measurementName": "string"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "externalId": "1234567890abc",
  • "measurementId": "a65ae317-e940-44cc-b570-cc74d1897c36",
  • "iamRoleArn": "arn:aws:iam::123456789012:role/paigo-datastore-role",
  • "ingestion": "s3://paigo-datastore-dump-bucket/",
  • "dlq": "s3://paigo-datastore-dlq-bucket/"
}

Delete a measurement

Delete a measurement

Authorizations:
bearer
path Parameters
measurementId
required
string

The unique identifier assigned by Paigo.

Example: a65ae317-e940-44cc-b570-cc74d1897c36

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "measurementId": "193b6967-1783-434f-85cb-a6fc4e1e385b"
}

Webhooks

Test Webhook Connection

Authorizations:
bearer

Responses

Test Webhook Invoices

Authorizations:
bearer
query Parameters
status
required
string

Responses

Response samples

Content type
application/json
null

Test Webhook Invoices

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Test Webhook Entitlement Breached

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find All Webhooks

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find One Webhook

Authorizations:
bearer
path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "hookUrl": "https://example.com/webhook",
  • "id": "fcb1fa34-8f11-4832-80f2-464cbc7a8546",
  • "webhookType": "INVOICE_CREATED",
  • "securityKey": "1234567890"
}

Unsubscribe a Webhook

Authorizations:
bearer
path Parameters
webhookId
required
string
query Parameters
environment
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "id": "string",
  • "webhookId": "string",
  • "environment": "string"
}

Subscribe a Webhook

Authorizations:
bearer
Request Body schema: application/json
hookUrl
required
string

The URL Paigo will callback to when the webhook type event occurs.

Example: "https://example.com/webhook"

securityKey
string

The security key used to authenticate the webhook. This is used to ensure the webhook is coming from Paigo. The key will be sent in the X-Paigo-Security header.

Example: "1234567890"

environment
string

The environment the webhook is for. This is used to differentiate between sandbox and production. Optional, will default to production if not provided.

Example: "sandbox"

webhookType
required
string
Enum: "INVOICE_CREATED" "INVOICE_PAID" "STRIPE_PAYMENT_FAILED" "CUSTOMER_CREATED" "CUSTOMER_UPDATED" "ENTITLEMENT" "INVOICE_SENT"

The type of webhook event to listen for. This will determine when the webhook is triggered.

Example: "INVOICE_CREATED"

offeringId
string

The offering the webhook is for. This is used to differentiate between different offerings. Only used for ENTITLEMENT webhooks.

Example: "539b7f74-3832-474e-a955-6d69c5df12d0"

Responses

Request samples

Content type
application/json
{
  • "hookUrl": "https://example.com/webhook",
  • "securityKey": "1234567890",
  • "environment": "sandbox",
  • "webhookType": "INVOICE_CREATED",
  • "offeringId": "539b7f74-3832-474e-a955-6d69c5df12d0"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "id": "string",
  • "webhookId": "string",
  • "environment": "string"
}

Settings

Update Business Profile Settings

Update Business Info and Logo.

Authorizations:
bearer
Request Body schema: application/json
sendInvoiceEmail
string
Enum: "true" "false"

Whether Paigo should send invoices to customers.

Example: "true"

businessName
string

The Name for the Business Entity using Paigo

Example: "My Smart Business Name"

addressLine1
string

Street number and name (address line 1)

Example: "123 Success Street"

addressLine2
string

Apartment or unit and its number (address line 2)

Example: "Suite 100"

city
string

City of Business Entity's Location

Example: "San Francisco"

state
string

State of Business Entity's Location

Example: "CA"

country
string

Country of Business Entity's Location

Example: "USA"

postalCode
string

Postal code of Business Entity's Location

Example: "94188"

supportEmail
string

Email address utilized by the Business Entity for customer support

Example: "support@mybusiness.com"

redirectionUrl
string

The URL to redirect to after relevant requests, such as completion of a connection.

Example: "https://mybusiness.com/redirect"

Responses

Request samples

Content type
application/json
{
  • "sendInvoiceEmail": true,
  • "businessName": "My Smart Business Name",
  • "addressLine1": "123 Success Street",
  • "addressLine2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "country": "USA",
  • "postalCode": "94188",
  • "supportEmail": "support@mybusiness.com",
  • "redirectionUrl": "https://mybusiness.com/redirect"
}

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior",
  • "data": [
    ]
}

Get Business Profile Settings

Get Business Info.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "businessName": "My Smart Business Name",
  • "addressLine1": "123 Success Street",
  • "addressLine2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "country": "USA",
  • "postalCode": "94188",
  • "supportEmail": "support@mybusiness.com",
  • "sendInvoiceEmail": true,
  • "stripeAccountId": "acct_1J2k3l4m5n6o7p8q9r0s",
  • "redirectionUrl": "string"
}

Upload Invoice Image

Upload Business Logo, file format supported: png,jpg,jpeg; max file size supported: 30Mb.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "message": "This is a sample API message. The exact message may vary based on the API behavior"
}