ProfitWell API v2

ProfitWell profitwellapiv2
Help

Apiary Powered Documentation

Sign in with Apiary account.

ProfitWell API v2

Introduction

The ProfitWell APIs allow you to get the most out of your account by programmatically adding and retrieving data.

(Note: If you are looking for the v1 docs, you can find them here)

Reference

Authentication


Authentication is done via an API token that you can find by clicking the ProfitWell API data connection card in the Account Settings -> Integrations tab of your ProfitWell account. This token is unique to your company and should be kept secret.

To authenticate, set an Authorization request header equal to the value of your token on each request. Invalid or missing tokens will return a 401 Unauthorized response.

Note on API Tokens: In the Account Settings -> Integrations tab of your Profitwell account, you'll find two tokens:

  • Your private token is required for all Profitwell API endpoints except for the Customer Events endpoint
  • Your public token is required for the Customer Events API endpoint, as well as authentication with the Profitwell.js script

Request Rate Limit


The Profitwell API employs several safeguards against bursts of incoming traffic to help maximize its stability. If a user sends many requests in quick succession they may see error responses that show up as "Request was throttled."

We have different limiters in the API:

All API requests, regardless of endpoint, have a base limit of 25 requests every 5 seconds. That is to say, an average limit of 5 requests per second, with bursts of up to 25.

We also have other rate limits that changes based on the type of request:

  • We limit plan updates to 1000/day. This involves list plans, create plans, retrieve plans, or update plans.

  • We limit metrics updates to 3000/day. This involves monthly and daily metrics or company settings.

  • We limit customer exclusions to 10/minute.

  • We limit the anonymization requests to 20/minute.

  • We limit customer traits requests to 20/minute.

API Status


Get the API Status

Get the API Status

This endpoint returns a status code of 200 if the API is operational and if you've properly authenticated. If you haven't authenticated properly, the endpoint returns a status code of 401.

Manually-added Customers


The Manually-Added Customers API allows you to manually add subscriptions to your ProfitWell account. Metrics for those subscriptions are automatically calculated and incorporated into all of the app views, except Cash Flow.

Creating Subscriptions

Create a subscription

Create a new subscription. Can be for a new user, or a user who already has another subscription. It is important that you store either the subscription_alias that you use to create this subscription, or the subscription_id that ProfitWell returns in the response, so that you can update/churn this subscription at a later date.

IMPORTANT: If you are creating multiple subscriptions for the same user, it is important that you wait for a response from the API after creating the first subscription before creating subsequent subscriptions.

Request body

  • user_id (string, optional) - The user ID. Do not include this field if you are creating a user's first subscription. The user_id is automatically generated by ProfitWell for any new users. Only include this field if you are referencing an existing user for whom you need to create an additional subscription.

  • user_alias (string, optional) - If you wish, you can include your own identifier here so that you have a handle by which to refer to this user in subsequent requests. An advantage of using your own identifier is that you do not have to store the ProfitWell-generated user_ids in your database. If you are creating a second subscription for a user, you will need to use either the user_id or user_alias fields when making this request so that we know which user you're referring to.

  • subscription_alias (string, optional) - If you wish, you can include your own identifier here so that you have a handle by which to refer to this subscription in subsequent requests. An advantage of using your own identifier is that you do not have to store the ProfitWell-generated subscription_ids in your database. In the future, if you need to update this subscription, you will need to use either the subscription_id or subscription_alias fields when making the update request so that we know which subscription you're referring to. Note that the subscription_alias must be unique across all users in your company, if you decide to provide one. Also note that this string cannot contain more than 36 characters.

  • email (string) - The email address of the user. (This can actually be any sort of text, not necessarily an email address. Some prefer to store a name here instead.) This will be the display text that is used on the Customers tab. This field does not uniquely identify a user.

  • plan_id (string) - The ID of the plan that the user is on. For the sake of consistency (and the ability to later segment your data), this name should be consistent across everyone who is on this plan.

  • plan_interval (string) - The billing cycle for this plan. The two options are "month" and "year".

  • plan_currency (string, optional) - The currency in which users of this plan are charged. The default currency is usd (United States Dollars). We accept the following ISO 4217 Currency Codes: aed, afn, all, amd, ang, aoa, ars, aud, awg, azn, bam, bbd, bdt, bgn, bhd, bif, bmd, bnd, bob, brl, bsd, btc, btn, bwp, bzd, cad, cdf, chf, clf, clp, cny, cop, crc, cup, cve, czk, djf, dkk, dop, dzd, egp, ern, etb, eur, fjd, fkp, gbp, gel, ghs, gip, gmd, gnf, gtq, gyd, hkd, hnl, hrk, htg, huf, idr, ils, inr, iqd, irr, isk, jep, jmd, jod, jpy, kes, kgs, khr, kmf, kpw, krw, kwd, kyd, kzt, lak, lbp, lkr, lrd, lsl, lyd, mad, mdl, mga, mkd, mmk, mnt, mop, mru, mur, mvr, mwk, mxn, myr, mzn, nad, ngn, nio, nok, npr, nzd, omr, pab, pen, pgk, php, pkr, pln, pyg, qar, ron, rsd, rub, rwf, sar, sbd, scr, sdg, sek, sgd, shp, sll, sos, srd, std, svc, syp, szl, thb, tjs, tmt, tnd, top, try, ttd, twd, tzs, uah, ugx, usd, uyu, uzs, vef, vnd, vuv, wst, xaf, xag, xau, xcd, xdr, xof, xpf, yer, zar, zmw, zwl.

  • status (string, optional) - The status of the subscription. Currently, the acceptable values for new subscriptions are "active" and "trialing". Down the line, we would like to add more statuses. If you do not provide a status, it will be assumed to be "active". Subscriptions that are trialing must have a status of "trialing" and a value of 0. All positive, nonzero values will be "active" subscriptions — negative values are not accepted. (Note that the API may return statuses other than "active" and "trialing" when retrieving a customer's subscription history, such as "churned_voluntary" and "churned_delinquent".)

  • value (number) - The amount that you bill your user, per billing period, in cents. Keep the value of annual plans unmodified, meaning a $120.00 / year plan should have a value of 12000.

  • effective_date (number) - The date that the subscription starts, in UNIX timestamp format. (E.g. For 2018-01-01, the value would be 1514764800).

  • data_provider_user_id (string, optional) - At some point down the line, we will use this to associate a manually-added user with a user from your account's data provider. For example, if you use Stripe, and you would like to record a second subscription for a Stripe user that is managed outside of Stripe itself, you could provide that Stripe User ID in this field (e.g. cus_A75fBhseE80). Note that we do not currently use this field.

Updating Subscriptions

Upgrade/Downgrade a subscription

Upgrade/downgrade an existing subscription.

Request body

  • plan_id (string) - The ID of the plan that the user is switching to. If the user has not switched plans, but has added or subtracted seats on their current plan, you should use the same plan_id as before.

  • plan_interval (string) - The billing cycle for this plan. The two options are "month" and "year".

  • value (number) - The new amount that you bill your user, per billing period, in cents. Keep the value of annual plans unmodified, meaning a $120.00 / year plan should have a value of 12000. Note: This should always be the full value of the plan, even if the user changes plans mid-billing cycle and is charged/credited a prorated amount.

  • status (string, optional) - The status of the subscription. Currently, the only valid status when upgrading/downgrading a subscription is "active". Down the line, we would like to add more statuses. (Note that the API may return statuses other than "active" when retrieving a customer's subscription history, such as "trialing", "churned_voluntary" and "churned_delinquent".)

  • effective_date (number) - The date that this update takes effect, in UNIX timestamp format. (E.g. For 2018-01-1 00:00:00, the value would be 1514764800).

URI Parameters
subscription_id_OR_subscription_alias

Either the subscription_id or the subscription_alias of the subscription

Churn a subscription

Churn a subscription

Note: This request's fields are query parameters in the URL. There is no body to this request.

URI Parameters
effective_dateUNIX timestamp of when the subscription churns
churn_type

Acceptable values are voluntary or delinquent. Default is voluntary.

subscription_id_OR_subscription_alias

Either the subscription_id or the subscription_alias of the subscription

Un-churning Subscriptions

Un-churn a subscription

Remove the churn event associated with a subscription. This rewrites history for the subscription, making it appear as thought the subscription never churned to begin with. You may do this for a subscription that has already churned, or that is set to churn in the future.

URI Parameters
subscription_id_OR_subscription_alias

Either the subscription_id or the subscription_alias of the subscription you'd like to un-churn.

Users

URI Parameters
user_id_OR_user_alias

Either the user_id or the user_alias of the user

Get subscription history for a user

Get the history of subscription updates you've made to a user.

Update a user

Update a user's email address.

Request body

  • email (string) - The new email address of the user. (This can actually be any sort of text, not necessarily an email address. Some prefer to store a name here instead.) This will be the display text that is used on the Customers tab.

Delete a user

Completely delete a user and their subscription history.

Plans - List/Create

List All Manually-Added Plans

List all manually-added plans.

Create a New Plan

Create a new, manually-added plan. You may create a new plan using this endpoint. Alternatively, if you create a manually-added subscription and place that subscription on a plan that has never been referenced before, that plan will automatically be created. If you try to create a plan that already exists, this endpoint will return an error.

Request body

  • id (string) - The ID of the new plan. This ID may not conflict with any other manually-added plan or plan coming from your connected data provider (e.g. Stripe).

  • name (string) - The name of the plan.

Plans - Retrieve/Update

URI Parameters
id

The ID of the manually-added plan you wish to retrieve or update

Retrieve a Plan

Retrieve a single manually-added plan by ID.

Update a Plan

Update the name of an existing manually-added plan.

Request body

  • name (string) - The new name of the plan

Customers


The Customers API lets you pull customer data out of ProfitWell.

There are two endpoints: one to retrieve an individual customer by their customer_id, and the other to search for customers.

Retrieving a Customer by ID

Retrieve a Customer by ID

Error Codes

404: If the customer cannot be found, we will return a response with a 404 status code.

URI Parameters
customer_id

The data-provider specific customer ID.

Searching for Customers

Search for customers

There are two use cases for this endpoint: The first is to search for a customer by their email address. The second is to iterate through all customers that have been updated since a given date.

If you are trying to iterate through all of the customers updated since a given date, keep in mind that there is a maximum allowable value to the page parameter that you provide, and it is based on the per_page parameter (100,000 / per_page). If you need to exceed that value, the solution is to move the start_date parameter forward in time. In fact, moving the start_date forward results in faster responses than using high page numbers.

Error Codes

400: If one of the query parameters is invalid, we will return a response with a 400 status code.

URI Parameters
start_date

Get customers who have been updated on start_date or later. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"

end_date

Get customers who have been updated before end_date. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"

emailThe customer email.
page

The page number. Max value: 100000 / per_page. Default value: 1.

per_page

The number of customers per page. Max value: 250. Default value: 250.

direction

Order the data by either ascending or descending. Valid values: "asc" or "desc". Default value: "asc".

GDPR Anonymize Customers


The General Data Protection Regulation (GDPR) Anonymize Customers API allows you to anonymize your customers.

There are two endpoints: one to anonymize a customer by their customer_id, and the other to anonymize a customer by their email.

Anonymizing a Customer by ID

Anonymize a Customer by ID

Error Codes

400: If the customer has already been anonymized, we will return a response with a 400 satus code.

404: If the customer cannot be found, we will return a response with a 404 status code.

URI Parameters
customer_id

The data-provider specific customer ID.

Anonymizing a Customer by email

Anonymize a Customer by email

Error Codes

404: If the customer cannot be found, or the customer has already been anonymized, we will return a response with a 404 status code.

Note that, if a customer has already been anonymized, we have no way of knowing that customer was once associated with that email. That is why we are unable to distinguish between a missing customer and one that has already been anonymized, and we return a 404 response in either case.

URI Parameters
emailThe customer email.

Metrics


The Metrics API gives you access to the same data we use to power the metrics and visualizations in the ProfitWell app.

Monthly Metrics

Get Monthly Metrics

Retrieve all monthly financial metrics for your company. Optionally scope to an individual metric and/or plan.

In the response, the data key contains an object whose keys are the metrics trend names, and whose values are an array of records containing the date and value of the given trend for each month. The dates are all in the format YYYY-MM (e.g. 2018-05). The values are all numbers, with precision up to two places after the decimal point. When relating to amounts (e.g. recurring_revenue), the values are in the currency listed in your ProfitWell account's settings. When relating to rates (e.g. growth_rate), the values are in percentages (i.e. the fractional rate multiplied by 100). So if your company grew 8.3% from one month to the next, the value would be 8.3. Note: Rate values can sometimes be null. If, for instance, you grew from $0 in MRR one month to $100 in MRR the next, your growth rate will be null, to avoid division by 0.

Some metrics are available only when you are retrieving data for ALL plans. And there are a couple of metrics that are only available when filtering by individual plans. See the All Plans and Individual Plan columns in the table below to determine which fields will be returned, and when.

The following are a list of metrics you may filter by:

Metric Meaning All Plans Individual Plan
active_customers Number of paying customers Yes Yes
active_trialing_customers Number of trialing customers Yes No
average_revenue_per_user ARPU Yes Yes
churned_customers Number of paying customers who churned Yes Yes
churned_customers_cancellations Number of customers who churned by cancelling their subscription(s) Yes No
churned_customers_delinquent Number of customers who churned because they failed to pay you Yes No
churned_recurring_revenue Revenue lost to churn (voluntary and delinquent) Yes Yes
churned_recurring_revenue_cancellations Revenue lost to customers who churned by cancelling their subscription(s) Yes No
churned_recurring_revenue_delinquent Revenue lost to customers who churned delinquent Yes Yes
churned_trialing_customers Number of trialling customers who churned Yes No
converted_customers Number of customers who converted from trialing to active Yes No
converted_recurring_revenue How much MRR comes from users who converted from trialing to active Yes No
customer_conversion_rate Percent of trialing customers who converted Yes No
customers_retention_rate Percent of customers active last month who are still active this month Yes No
downgrade_rate Downgrade revenue as a percent of existing revenue Yes No
downgraded_customers Number of existing customers who net downgraded Yes No
downgraded_recurring_revenue How much downgrades and plan length decreases affect your MRR Yes No
existing_customers Number of paying customers you had at the start of the given month Yes Yes
existing_recurring_revenue Your company's MRR at the start of the given month Yes Yes
existing_trialing_customers Number of trialing customers who existed at the start of the month Yes No
growth_rate Rate at which your company's MRR has grown over the previous month Yes Yes
lifetime_value Average LTV, as calculated at the end of the given period Yes Yes
new_customers Number of new, paying customers you have Yes Yes
new_recurring_revenue MRR from new users Yes Yes
new_trialing_customers Number of new trialing customers Yes No
reactivated_customers Number of customers who have reactivated Yes Yes
reactivated_recurring_revenue How much MRR comes from reactivated customers Yes Yes
recurring_revenue Your company's MRR Yes Yes
customers_churn_rate Percentage of paying customers who churned Yes Yes
customers_churn_cancellations_rate Percentage of paying customers who churned by cancelling their subscription(s) Yes No
customers_churn_delinquent_rate Percentage of paying customers who churned because they failed to pay you Yes No
revenue_churn_cancellations_rate Voluntary churn revenue as a percent of the month's starting revenue Yes No
revenue_churn_delinquent_rate Delinquent churn revenue as a percent of the month's starting revenue Yes Yes
revenue_churn_rate Revenue lost to churn as a percentage of existing revenue Yes Yes
revenue_retention_rate Percent of revenue coming from existing customers that was retained by the end of the month Yes Yes
upgrade_rate Upgrade revenue as a percent of existing revenue Yes No
upgraded_customers Number of existing customers who net upgraded Yes No
upgraded_recurring_revenue How much upgrades and plan length increases affect your MRR Yes No
plan_changed_recurring_revenue Net change in revenue for this plan No Yes
plan_change_rate Net change in revenue as a percentage of existing revenue No Yes

Error Codes

400: If your request contains invalid metrics trend names for the metrics parameter, or if it contains unknown query paramters, we will return a response with a 400 status code.

URI Parameters
plan_id

Optionally only return the metrics for this plan_id.

metrics

An optional, comma-separated list of metrics trends to return (the default is to return all metrics).

Request
object
  • metrics
    string, optional
    existing_recurring_revenue,existing_customers

Daily Metrics

Get Daily Metrics

Retrieve financial metrics broken down by day for either the current month or the last. Optionally scope to an individual metric and/or plan.

In the response, the data key contains an object whose keys are the metrics trend names, and whose values are an array of records containing the date and value of the given trend for each day. The dates are all in the format YYYY-MM-DD (e.g. 2018-05-15). The values are all numbers, with precision up to two places after the decimal point. When relating to amounts (e.g. recurring_revenue), the values are in the currency listed in your ProfitWell account's settings.

Some metrics are available only when you are retrieving data for ALL plans. See the Segment by Individual Plan column in the table below to determine which trends can be segmented by plan.

Metric Meaning Segment by Individual Plan
active_customers Number of paying customers No
churned_customers Number of paying customers who churned No
churned_recurring_revenue MRR lost to churn (voluntary and delinquent) Yes
cumulative_net_new_mrr New + Upgrades - Downgrades - Churn MRR, cumulative for the month up through the given day Yes
cumulative_new_trialing_customers Number of new trialing customers, cumulative for the month up through the given day Yes
downgraded_customers Number of existing customers who net downgraded No
downgraded_recurring_revenue How much downgrades and plan length decreases affect your MRR No
future_churn_mrr MRR that will be lost when users who are currently cancelled actually churn Yes
new_customers Number of new, paying customers you have No
new_recurring_revenue MRR from new users Yes
reactivated_customers Number of customers who have reactivated No
reactivated_recurring_revenue How much MRR comes from reactivated customers Yes
recurring_revenue Your company's MRR Yes
upgraded_customers Number of existing customers who net upgraded No
upgraded_recurring_revenue How much upgrades and plan length increases affect your MRR No

Error Codes

400: If your request contains an invalid month for the month parameter, invalid metrics trend names for the metrics parameter, or if it contains unknown query paramters, we will return a response with a 400 status code.

URI Parameters
month

Return daily metrics trends for this month. Can only be the current or previous month. Format should be YYYY-MM (e.g. 2018-09).

plan_id

Optionally only return the metrics for this plan_id.

metrics

An optional, comma-separated list of metrics trends to return (the default is to return all metrics).

Request
object
  • month
    string
    2018-09
  • metrics
    string, optional
    recurring_revenue

Plan IDs

Get Plan IDs

Retrieve your company's active plan IDs, sorted by MRR. Will only return plan IDs for which there are currently active customers, and will return at most 150.

URI Parameters
limit

Optionally return up to this many plan IDs (max and default are 150)

Exclude Customer from Metrics

Exclude Customer

Exclude user's data from the calculation of all metrics.

URI Parameters
customer_id

The id of the customer to exclude.

Retain


Stop Retain

Stop Retain for a customer

Stop any possible action Retain could be taking over a given customer. This includes: sending emails to the customer, retrying with the same payment method, sending in app notifications or SMS, if applicable.

Request body

  • customer_id (string) - The customer ID.

  • intervention_types (list of string) - A comma-separated list of the interventions you want to stop for the given customer. The possible values are retain, term_optimization and reactivation.

  • forever (bool, optional) - Indicates whether we have to exclude the user from the given interventions or not. By default, the value is False.

Error Codes

400: If there isn't any open payment for the given customer, we will return a response with a 400 status code.

Unsubscribed customers

Customers unsubscribed from Retain intervention emails

Retrieve customers that unsubscribed from Retain Term Optimization or Reactivation emails.

If you are trying to iterate through all of the customers that unsubscribed after a given date, keep in mind that there is a maximum allowable value to the page parameter that you provide, and it is based on the per_page parameter (100,000 / per_page). If you need to exceed that value, the solution is to move the start_date or end_date parameters forward or backward in time to reduce the size of the returned set of customers.

Error Codes

400: If one of the url or query parameters is invalid, we will return a response with a 400 status code.

URI Parameters
intervention_type

Must be either "term_optimization" or "reactivation"

start_date

Get customers who unsubscribed on start_date or later. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"

end_date

Get customers who unsubscribed on end_date or before. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"

page

The page number. Max value: 100000 / per_page. Default value: 1.

per_page

The number of customers per page. Max value: 250. Default value: 250.

Company


Company Settings

Get Your Company's Account Settings

Get your company's ProfitWell account settings. These include your company ID, name, timezone, and the currency in which your metrics are displayed.

Customer Traits


Traits

Create or Update a Trait on a Customer

This is a create or update to a trait attached to a particular customer by customer id. Each customer can only have one trait per category. If a subsequent request for the same customer comes with a different trait for the same category, the trait will be updated.

Customers Without a Trait for a Category

We recognize that some of your custom traits may not apply to all of your customers and extrapolation doesn't make much sense. For example, you have a segment of customers that are enterprise customers and have dedicated account managers. The bulk of your self-serve customers don't have account managers assigned to them. In these cases, we recommend assigning an n/a trait to these customers. If customers are unlabeled, ProfitWell will extrapolate existing data onto those customers.

Formatting

Customer Traits are case IN-sensitive. All traits will be stored and presented in lower-case, regardless of the case provided in a request. This means the category: "super hero" for all intents and purposes will be considered the same as "Super Hero".

Validation

The following will receive a 400 response:

Blank, None and #N/A values for either category or trait are invalid. The following actions are invalid:

  • Adding a trait to customer that already has the exact category, trait combination

  • Removing a trait that the customer does not have

  • Using any of the following provided category names in either form or case:

    • "account_age_category", "Activity Level"
    • "age_category", "Age Range"
    • "country", "Location"
    • "employer_industry", "Company Industry"
    • "employer_size", "Company Size"
    • "engagement_quartile", "Activity Level"
    • "gender", "Gender"
    • "job_category", "Job Category"
    • "mrr_quartile", "MRR Quartile"
    • "twitter_followers_category", "Twitter Followers"

You can however, upload categories with related names as the above (i.e., "Geography" instead of "Country").

Adding Traits by Email

You can add traits by email address which will apply the trait to all customers with the specified email. In the request body, use email as the key:

{
    "email": "bruce@waynecorp.com",
    "category": "super power",
    "trait": "gadgets"
}

Removing a Trait

Customers

Get Customer's Traits

Returns a customer's traits in the form of: {category: trait, ...}.

Categories

Removing a Category

Removing a category will remove it from every customer that has a trait for the specified category. This action is irreversible. Any subsequent request that contains the category will create a new category from scratch.

Hiding a Category

On the UI, you can also "hide" categories, which will temporarily remove it from the segmentation drawer. This action is reversible, so consider this before removing a category.

Trait Limit

Categories can have at most 100 unique traits. You won't be able to add more than 100 different traits to the same category.

Engagement


Customer Events

Create a customer event

Create a customer event when a customer logs into your system. If it is not possible to integrate the profitwell.js or Paddle.js scripts in your system, you can send customer login events using this endpoint.

Note: This endpoint requires your public token to be passed in the Authorization header. This token can be found in the Account Settings -> Integrations tab of your Profitwell account.

Request

POST https://api.profitwell-events.com/dotjs/v1/customer/event/
Headers
Authorization: 0be1442a82158361c77f851457af6625
Content-Type: application/json
Body
{
    "user_id": "cus_1234",
}

Response

204 No Content

Error Codes

  • 400: If the body's JSON is invalidly formatted or customer can't be found. The error field in the response will contain the reason.

  • 415: If the content type is unsupported. This endpoint supports application/json content.