ProfitWell API v2

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.

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.

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).

Churn a subscription

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

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.

Get the history of subscription updates you've made to 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.

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.

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.

Retrieve a single manually-added plan by ID.

Update the name of an existing manually-added plan.

Request body

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

Error Codes

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

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.

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.

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.

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:

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.

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.

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.

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.

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

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.

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.

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.

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"
}

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.

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.