Apiary Powered Documentation
Sign in with Apiary account.
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)
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
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.
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.
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.
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.
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.
Upgrade/downgrade an existing subscription.
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).
subscription_id | Either the |
---|
Churn a subscription
Note: This request's fields are query parameters in the URL. There is no body to this request.
effective_date | UNIX timestamp of when the subscription churns |
---|---|
churn_type | Acceptable values are |
subscription_id | Either the |
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.
subscription_id | Either the |
---|
user_id_OR_user | Either the |
---|
Get the history of subscription updates you've made to a user.
Update a user's email address.
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.Completely delete a user and their subscription history.
List all manually-added plans.
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.
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.
id | The ID of the manually-added plan you wish to retrieve or update |
---|
Retrieve a single manually-added plan by ID.
Update the name of an existing manually-added plan.
name
(string) - The new name of the planThe 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.
404: If the customer cannot be found, we will return a response with a 404 status code.
customer_id | The data-provider specific customer ID. |
---|
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.
400: If one of the query parameters is invalid, we will return a response with a 400 status code.
start_date | Get customers who have been updated on |
---|---|
end_date | Get customers who have been updated before |
The customer email. | |
page | The page number. Max value: 100000 / |
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". |
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
.
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.
customer_id | The data-provider specific customer ID. |
---|
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.
The customer email. |
The Metrics API gives you access to the same data we use to power the metrics and visualizations in the ProfitWell app.
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 |
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.
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). |
existing_recurring_revenue,existing_customers
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 |
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.
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). |
2018-09
recurring_revenue
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.
limit | Optionally return up to this many plan IDs (max and default are 150) |
---|
Exclude user's data from the calculation of all metrics.
customer_id | The |
---|
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.
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
.
400: If there isn't any open payment for the given customer, we will return a response with a 400 status code.
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.
400: If one of the url or query parameters is invalid, we will return a response with a 400 status code.
intervention_ty | Must be either "term_optimizat |
---|---|
start_date | Get customers who unsubscribed on |
end_date | Get customers who unsubscribed on |
page | The page number. Max value: 100000 / |
per_page | The number of customers per page. Max value: 250. Default value: 250. |
Get your company's ProfitWell account settings. These include your company ID, name, timezone, and the currency in which your metrics are displayed.
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.
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.
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"
.
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"
).
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"
}
Returns a customer's traits in the form of: {category: trait, ...}
.
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.
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.
Categories can have at most 100 unique traits. You won't be able to add more than 100 different traits to the same category.
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.
POST https://api.profitwell-events.com/dotjs/v1/customer/event/
Authorization: 0be1442a82158361c77f851457af6625
Content-Type: application/json
{
"user_id": "cus_1234",
}
204 No Content
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.