NAV

Introduction

We help you to calculate and report your business metrics. For us to do that accurately, you have to keep Probe updated about all the changes that may affect your revenue.

Should you face any difficulties while using our API or find that something is unclear - we would really appriciate your feedback. Just email Alex at support@getprobe.io.

Authorization

Authorization to Probe API is handled by supplying each API request with an HTTP Authorization: Bearer <API TOKEN> header.

Please write to Alex at support@getprobe.io to obtain your Probe API token.

Pagination

For APIs that return a list of objects you have to use pagination to get all objects.

We use cursor-based pagination. There is a special parameter, next that you will receive in a response. Pass the value to a subsequent request as a query parameter to access next page of JSON objects. Repeat this process until next is null which indicates you hit the last page.

Currently the number of objects returned for each request is 100 and it is not possible to change it.

Response format for list API

{
  "items": [
    {
      "id": "sub_1",
      # ...
    },
    {
      "id": "sub_2",
      # ...
    },
  ]
  "next": "eyJ2ZXJzaW9uIjoxLCJkYXRhIjp7Imxhc3RfaWQiOjIxfX0"
}
Attribute Description
items List of JSON objects you are paginating through
next String representing pagination token you should pass to next request to iterate further. Last page will have "next": null

Getting Started

We use the Subscription model to track usage of your product for each customer. Each time something changes - the customer starts paying you or stops having access to your product - you have to update Probe with this information. We will keep a full history of changes for each Subscription. You can get access to this history via the API.

Below is an example of a typical Subscription’s lifecycle and updates that needed to be made to Probe.

Create trial subscription

Creating a new subscription when the customer signs up for a Trial.

curl -d \
  '{
    "customer_id": "abc",
    "id": "sub_1",
    "started_at": "2019-09-06T13:00:00",
    "items": [{
      "product_key":"starter",
      "type":"trial",
      "trial_started_at":"2019-09-06T13:00:00",
      "trial_ended_at":"2019-09-13T13:00:00"
    }]
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/subscriptions/upsert

Returns

{
   "created_at": "2019-10-23T13:29:48Z",
   "customer_id": "abc",
   "id": "sub_1",
   "started_at": "2019-09-06T13:00:00Z",
   "ended_at": null,
   "items": [
      {
         "type": "trial",
         "product_key": "starter",
         "trial_started_at": "2019-09-06T13:00:00Z",
         "trial_ended_at": "2019-09-13T13:00:00Z"
      }
   ]
}

When a customer creates a new Trial account in your system, you would usually create a subscription in Probe.

The new subscription will be created with id = sub_1. We will use this id for reporting all future changes that may happen for this subscription. We rely on the id to understand if a new subscription should be created or an existing one should be updated. I. e. if we don’t find a subscription with the provided id we will create a new one. If you do not provide id we will generate it for you.

Create recurring subscription

Notice type=recurring to report a recurring customer

curl -d \
  '{
    "currency": "usd",
    "id": "sub_1",
    "started_at": "2019-09-11T13:00:00",
    "monthly_amount": "100.45",
    "items": [{
      "product_key":"starter",
      "type":"recurring"
    }]
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/subscriptions/upsert

Returns

{
  "created_at": "2019-10-23T14:06:33Z",
  "currency": "usd",
  "customer_id": "abc",
  "id": "sub_1",
  "started_at": "2019-09-11T13:00:00Z",
  "ended_at": null,
  "monthly_amount": "100.45",
  "items":[
     {
       "type": "recurring",
       "product_key": "starter",
       "trial_started_at": "2019-09-06T13:00:00Z",
       "trial_ended_at": "2019-09-13T13:00:00Z"
     }
  ]
}

When the customer starts paying you, you need to update the subscription with a monthly amount that will be counted into your revenue.

In the example on the right, the customer starts paying for a product called starter. Notice we post a new item with type=recurring under the subscription items, providing the currency used and a monthly_amount, as well as setting started_at to a timestamp indicating when the state of the subscription has changed.

Update subscription amount

There is no need to provide items because they did not change

curl -d \
  '{
    "id": "sub_1",
    "started_at": "2019-10-10T13:00:00",
    "monthly_amount": "250.50"
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/subscriptions/upsert

Returns

{
  "created_at": "2019-10-23T14:25:02Z",
  "currency": "usd",
  "customer_id": "abc",
  "id": "sub_1",
  "started_at": "2019-10-10T13:00:00Z",
  "ended_at": null,
  "monthly_amount": "250.5",
  "items":[
    {
      "type": "recurring",
      "product_key": "starter",
      "trial_started_at": "2019-09-06T13:00:00Z",
      "trial_ended_at": "2019-09-13T13:00:00Z"
    }
  ]
}

When a customer starts to pay you more or less due to an increase/decrease in their product usage, you need to update the subscription's monthly_amount.

In this example the customer starts to pay you 250.50 USD beginning on the 10th of October. Notice, that we do not provide subscription items here. That is because it is not mandatory to provide values for fields that have not changed.

Add new product

curl -d \
  '{
    "id": "sub_1",
    "started_at": "2019-10-30T13:00:00",
    "monthly_amount": "290.99",
    "items":[
      {"product_key":"starter"},
      {"product_key":"expansion-pack", "type":"recurring"}
    ]
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/subscriptions/upsert

Returns

{
  "created_at": "2019-10-24T14:16:56Z",
  "currency": "usd",
  "customer_id": "abc",
  "id": "sub_1",
  "started_at": "2019-10-30T13:00:00Z",
  "ended_at": null,
  "monthly_amount": "290.99",
  "items":[
    {
      "type": "trial",
      "product_key": "starter",
      "trial_started_at": "2019-09-06T13:00:00Z",
      "trial_ended_at": "2019-09-13T13:00:00Z"
    },
    {
      "type": "recurring",
      "product_key": "expansion-pack",
      "trial_started_at":null,
      "trial_ended_at":null
    }
  ]
}

In the example above the customer has bought a new product - expansion-pack, we also updated the monthly_amount. When you want to update subscription items you always have to send all the products that are currently active for the customer. In the example above if you didn't provide the starter item, it would be removed from the subscription. The customer would be left with only the expansion-pack product.

You can remove or add products for the customer in a similar fashion.

Cancel subscription

curl -d \
  '{
    "id": "sub_1",
    "started_at": "2019-12-30T13:00:00",
    "ended_at": "2019-12-30T13:00:00"
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/subscriptions/upsert

Returns

{
  "created_at": "2019-10-23T14:34:31Z",
  "currency": "usd",
  "customer_id": "abc",
  "id": "sub_1",
  "started_at": "2019-12-30T13:00:00Z",
  "ended_at": "2019-12-30T13:00:00Z",
  "monthly_amount": "290.99",
  "items":[
    {
      "type": "trial",
      "product_key": "starter",
      "trial_started_at": "2019-09-06T13:00:00Z",
      "trial_ended_at": "2019-09-13T13:00:00Z"
    },
    {
      "type": "recurring",
      "product_key": "expansion-pack",
      "trial_started_at":null,
      "trial_ended_at":null
    }
  ]
}

When the customer is not using your product any longer, you have to let us know by setting the ended_at field on the subscription.

In this example, the subscription will end on the 30th of December and won't be counted into your MRR from that moment on. Notice that both starter and expansion-pack will be ended. If you want to remove only one of them from the subscription, you can do that by updating the subscription items section as described in Add new product.

Subscriptions

Subscription object

This is the JSON representation of the subscription object

{
   "created_at": "2019-10-22T12:08:05Z",
   "currency": "usd",
   "customer_id": "customer_1",
   "id": "sub_1",
   "started_at": "2019-10-22T11:07:24Z",
   "ended_at": "2019-11-22T11:07:24Z",
   "monthly_amount": "55.5",
   "items":[
      {
         "type": "recurring",
         "product_key": "starter"
      }
   ]
}

The subscription object represents how much each customer is contributing to your MRR.

Attributes

Attribute Description
created_at String in ISO-8601 date format. DateTime when the subscription was created within Probe.
currency String. ISO currency code in which you receive the payment. Ex. "usd"
customer_id String. Unique identifier of the customer within your system.
ended_at String in ISO-8601 date format. DateTime when the subscription has or will end.
id Unique identifier of the subscription object.
started_at String in ISO-8601 date format. Date when the current subscription change became active for the customer.
monthly_amount A string with decimals separated by dot. Ex. "45.12". The monthly amount counted into your MRR.
items Array. List of subscription item objects.

Subscription Item object

Attribute Description
type Possible values: trial, freemium, recurring, one_time, metered
Use trial if the customer is trialing a given product. Use freemium if you have a freemium model for a given product. Use recurring if the customer is paying for a product. Use one_time to note a one-time payment that doesn't contribute to SaaS metrics. Use metered to note a recurring payment but with usage-based pricing.
product_key String containing only letters and numbers. Key of the product the customer subscribed for.
trial_started_at String in ISO-8601 date format. If a customer is trialing a product, the date when the trial has started.
trial_ended_at String in ISO-8601 date format. If a customer is trialing product, the date when the trial will end. This can be null in case you are giving freemium access to your product.

Upserting new subscription

Each time the state of a subscription changes within your system, or a new subscription is created, you have to report this state change to Probe. In this way, Probe is able to accurately report your MRR.

You can use the Upsert API to report any such state change.

HTTP Request

PUT https://api.getprobe.io/v4/subscriptions/upsert

Query params

Param Description
currency required
String. ISO currency code in which you receive the payment. E.g. "usd".
The behavior depends on the monthly_amount param. You have to provide a currency if you are providing a monthly_amount.
customer_id required
Unique identifier of the customer within your system. This param is required when you are reporting a new subscription for a given customer.
ended_at optional
String in ISO-8601 date format. DateTime when the subscription has or will end.
id optional
Unique string identifier of the subscription object provided by you or generated by Probe if none was supplied. We suggest that you provide this param and that its value correspond to the id you use in your system for this subscription.
started_at required
String in ISO-8601 date format. Date when the current subscription change became active for the customer.
monthly_amount required
A string with decimals separated by dot. Ex. "45.12". The monthly amount counted into your MRR. The behavior depends on the type of subscription item you creating. If there are paying items, monthly_amount is required.
items required
List of subscription item objects (see below). At least one item must be present when reporting a new subscription for the first time.

Subscription Item object

Attribute Description
type required
Possible values: trial, freemium, recurring, one_time, metered
Use trial if the customer is trialing a giving product. Use freemium if you have a freemium model for a given product. Use recurring if the customer is paying for a product. Use one_time to note a one-time payment that doesn't contribute to SaaS metrics. This param is required when reporting an item for the first time. At later stages you can just use product_key to report that the item is still part of the subscription. Use metered to note a recurring payment but with usage-based pricing.
product_key required
String containing only letters and numbers. Key of the product the customer subscribed for.
trial_started_at required
String in ISO-8601 date format. This param is required when creating an item with type=trial or type=freemium. The timestamp when customer created trial or freemium account within your system.
trial_ended_at required
String in ISO-8601 date format. If a customer is trialing a product, the date when the trial will end. Required when type=trial. This can be null in case you are giving freemium access to your product.

Returns

Returns the new state of the Subscription object.

Listing subscriptions

curl \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X GET https://api.getprobe.io/v4/subscriptions

Returns

{
  "items":[
    {
      "created_at": "2019-10-23T14:34:31Z",
      "currency": "usd",
      "customer_id": "abc",
      "id": "sub_1",
      "started_at": "2019-12-30T13:00:00Z",
      "ended_at": "2019-12-30T13:00:00Z",
      "monthly_amount": "290.99",
      "items":[
        {
          "type": "trial",
          "product_key": "starter",
          "trial_started_at": "2019-09-06T13:00:00Z",
          "trial_ended_at": "2019-09-13T13:00:00Z"
        },
        {
          "type": "recurring",
          "product_key": "expansion-pack",
          "trial_started_at":null,
          "trial_ended_at":null
        }
      ]
    }
  ],
  "next": "eyJ2ZXJzaW9uIjoxLCJkYXRhIjp7Imxhc3RfaWQiOjIxfX0"
}

Use this endpoint to list all subscriptions present in the system. It returns the latest state of each subscription.

This endpoint is paginated.

HTTP Request

GET https://api.getprobe.io/v4/subscriptions

Query params

Param Description
next optional
String representing pagination token.

Response body

Attribute Description
items List of subscriptions. See Subscription Object.
next String with pagination token to attach to next request. If null, it's the last page.

Returns

Latest state of Subscription objects.

Destroying subscription

curl \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X DELETE https://api.getprobe.io/v4/subscriptions/:id

Returns

204 No Content

You can remove all data for a specific subscription by destroying it, which will completely remove the subscription from our system. Later on you can add the same subscription if you wish.

HTTP Request

DELETE https://api.getprobe.io/v4/subscriptions/:id

Query params

Param Description
id required
ID of the subscription to be destroyed.

Returns

This API returns no content.

Subscription histories

Subscription history object

This is the JSON representation of the subscription history object

{
  "id": "subh_4bRliAkezdnE",
  "user_id": "user_QBu0pPpK1HbI",
  "customer_id": "cus_IyJWtuDx3Bll",
  "subscription_id": "sub_I7DkuettCSQnzb",
  "started_at": "2021-03-30T07:00:00.000Z",
  "ended_at": "2021-09-30T07:00:00.000Z",
  "duration_in_months": 6,
  "original_total_value": "30000.0",
  "original_monthly_amount": "5000.0",
  "original_currency": "usd",
  "total_value": "30000.0",
  "monthly_amount": "5000.0",
  "currency": "usd",
  "items": [
    {
      "type": "recurring",
      "product_key": "BasicPlan"
    }
  ],
  "created_at": "2021-03-30T13:26:00.000Z"
}

Subscription history represents a payment related to a subscription of a customer.

Attributes

Attribute Description
id String. Unique identifier of the subscription history object.
user_id String. ID of the user object who created this subscription history.
customer_id String. ID of the customer object that this history refers to.
subscription_id String. ID of the subscription object that this payment refers to.
started_at String in ISO-8601 date format. DateTime when the payment started.
ended_at String in ISO-8601 date format. DateTime when the payment ended.
duration_in_months Number. Represents the duration in months of the payment.
total_value String. Total amount paid, that is duration_in_months * monthly_amount. Represented in your account currency.
monthly_amount String. Monthly amount for this payment. Represented in your account currency.
currency String. ISO code of your account currency.
original_total_value String. Total amount paid, that is duration_in_months * monthly_amount.
original_monthly_amount String. Monthly amount for this payment.
original_currency String. ISO code of currency.
items Array. List of items related to that payment.
created_at String in ISO-8601 date format. DateTime when this object was created within Probe.

Subscription history item object

Param Description
type String. One of recurring (recurring revenue), metered, (recurring revenue for usage-based products), or one_time for one-time payments
product_key String. Name of the product.

Both recurring and metered types are counted towards metrics like MRR, Churn, Contraction etc.

The one_time type represents a one-time payment that is counted towards your Revenue / Cash flow. It does not contribute to SaaS-related metrics.

Currently we don't support more than one item per history. If you have such case, please split each item into separate subscription history.

Upserting a subscription history

This API creates or updates an existing subscription history by id. When the subscription history is created, the customer and subscription related to it are also created based on customer_id and subscription_id attribute. If the subscription_id attribute is not provided when creating a history, it will be auto-generated.

When updating an existing subscription history the relation to customer or subscription isn't changed. Moreover, if you provide customer_id or subscription_id attributes and the history already exists, we will check that the attributes match the existing state and return error if they don't.

curl -d \
  '{
    "subscription_id": "acme-deal-2021",
    "customer_id": "acme",
    "currency": "PLN",
    "monthly_amount": "95.90",
    "started_at": "2021-12-05T15:00:00Z",
    "ended_at": "2022-12-05T15:00:00Z",
    "items": [{"product_key": "basic", "type": "recurring"}]
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/subscriptions/history/upsert/invoice_12_2021

HTTP Request

POST https://api.getprobe.io/v4/subscriptions/history/upsert/:id

Params

Param Description
id required
ID of the subscription history.
customer_id required
String. ID of the customer object that this history refers to.
subscription_id String. ID of the subscription object that this history refers to. Auto-generated if not provided.
started_at required
String in ISO-8601 date format. DateTime when the subscription history started.
ended_at required
String in ISO-8601 date format. DateTime when the subscription history ended.
monthly_amount required
String. Monthly amount of this payment in original currency.
currency required
String. ISO code of payment's currency.

Response body

See Subscription History Object.

Returns

Subscription history object.

Returns

{
  "id": "subh_4bRliAkezdnE",
  "user_id": "user_QBu0pPpK1HbI",
  "customer_id": "cus_IyJWtuDx3Bll",
  "subscription_id": "sub_I7DkuettCSQnzb",
  "started_at": "2021-03-30T07:00:00.000Z",
  "ended_at": "2021-09-30T07:00:00.000Z",
  "duration_in_months": 6,
  "original_total_value": "30000.0",
  "original_monthly_amount": "5000.0",
  "original_currency": "usd",
  "total_value": "30000.0",
  "monthly_amount": "5000.0",
  "currency": "usd",
  "items": [
    {
      "type": "recurring",
      "product_key": "BasicPlan"
    }
  ],
  "created_at": "2021-03-30T13:26:00.000Z"
}

Customers

Customer object

This is the JSON representation of the customer object

{
  "id": "my-id-42",
  "segments": [
    {
      "name": "industry",
      "value": "software"
    }
  ],
  "added_at": "2019-11-22T11:07:24Z",
  "updated_at": "2019-11-22T11:07:24Z"
}

The customer object represents your customer. It is related to your internal system by id attribute and can have segments attached to it.

Attributes

Attribute Description
id String. Unique identifier of the customer within your system.
segments Array. List of segment objects.
added_at String in ISO-8601 date format. DateTime when the subscription was created within Probe.
updated_at String in ISO-8601 date format. Date when the current subscription change became active for the customer.

Segment object

Param Description
name String. Name of the segment.
value String. Value of the segment.

Getting customer

Show current information about customer, including segments they are in.

curl \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X GET https://api.getprobe.io/v4/customers/my-id-42

HTTP Request

GET https://api.getprobe.io/v4/customers/:id

Query params

Param Description
id required
ID of the customer within your system.

Response body

See Customer Object.

Returns

Customer object.

Returns

{
  "id": "my-id-42",
  "segments": [
    {
      "name": "industry",
      "value": "software"
    }
  ],
  "added_at": "2020-05-21T15:07:15Z",
  "updated_at": "2020-05-21T15:07:15Z"
}

Updating customer segments

Segments are simple key-value pairs which can be used to segment your metrics. Each segment has a name which is a String, and a value which is also a String.

To add or overwrite a segment value on a customer simply include it in segments array with its name and value. Notice that other existing segments remain unchanged by this operation.

To remove an existing segment include a name of the segment with a value set to null.

Segments have a unique name so including two segments with the same name in the segments array will result in an error.

# adding (or updating) "industry" = "hardware" to the existing segments
curl -d \
  '{
     "segments": [
       {
         "name": "industry",
         "value": "hardware"
       }
     ]
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/customers/my-id-42

# removing an existing "industry" segment while keeping other
# segments unchanged
curl -d \
  '{
     "segments": [
       {
         "name": "industry",
         "value": null
       }
     ]
  }' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -X PUT https://api.getprobe.io/v4/customers/my-id-42

HTTP Request

PUT https://api.getprobe.io/v4/customers/:id

Query params

Param Description
id required
ID of the customer within your system.
segments Array. List of segment objects.

Segment object

Param Description
name required
String. Name of the segment.
value required
String or null. Value of the segment or null to remove segment.

Response body

See Customer Object.

Returns

{
  "id": "my-id-42",
  "segments": [
    {
      "name": "industry",
      "value": "hardware"
    }
  ],
  "added_at": "2020-05-21T15:07:15Z",
  "updated_at": "2020-05-21T15:08:03Z"
}

Errors

Probe uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified subscription could not be found.
500 Internal Server Error -- We had a problem with our server. We are working to fix it but feel free to get in touch with more details.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Help

If you encounter any difficulties just email us at support@getprobe.io.