Introduction
Baremetrics offers simple integration with popular payment providers such as Stripe, Recurly and Braintree. If you are using one of those providers, go ahead and sign up and connect them right now!
If you're using a non-supported payment provider, or you're managing your own subscriptions, the Baremetrics API might be a great fit for you. With just a little dev work on your part, you can create customers and manage their subscriptions to unlock the full Baremetrics feature set.
You'll need a Baremetrics account to use the API. Your API keys are available in the Settings area.
Authentication
Authentication to the Baremetrics API is performed using a bearer token. To use this, send the following with your request:
Our API uses Bearer Authentication for access to all endpoints. You can either supply an API key found in your API settings, or you can use an Access Token obtained via oAuth.
-H "Authorization: Bearer APIKEY"
All requests must be sent over HTTPS
{
"error": "Unauthorized. Token not found"
}
oAuth
We offer access to our API via oAuth, allowing you to connect with Baremetrics users easily.
To begin, you will need to request access to our oAuth system. You can do so by reaching out to support, briefly explaining what you will be using our API for.
Once you have your Client ID and Client Secret, you can follow the standard oAuth 2.0 specification flow.
The first step is to send the user from your application to Baremetrics, using the following URL format.
You will need to specify response_type=code
as a query param.
The scopes we offer are read
and write
. To allow both, use a space separated string.
https://app.baremetrics.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&scope=SCOPES&response_type=code
Once the user has authenticated, they will be redirect back to your application with a code
query parameter. You should use this code to request an access token for that user, for example:
RestClient.post("https://app.baremetrics.com/oauth/token", {
'code' => code,
'client_id' => CLIENT_ID,
'client_secret' => CLIENT_SECRET,
'grant_type' => 'authorization_code',
'redirect_uri' => REDIRECT_URL
})
This will return you an Access Token that should then be passed into the Bearer Authentication header.
Sandbox
To help you build your integration, we have setup a full sandbox environment for you.
Please only use the sandbox for testing your code implementation, it's not designed for importing all your data. You will be limited to a low number of Subscriptions.
You can view your sandbox API key here
You can use the Sandbox API by using: https://api-sandbox.baremetrics.com
You can access the Sandbox Dashboard here.
Pagination
All endpoints return 30 objects by default. You can override this by passing the query param of per_page
. The maximum objects per page is 200 at this time. You can specify the page by supplying the query param of page
.
The following objects will be returned in all paginated responses:
{
"meta": {
"pagination": {
"has_more": false,
"page": 0,
"per_page": 30
}
}
}
Rate Limit
You can check your rate limit by looking at the X-RateLimit-Limit
header in every response.
If you need to temporarily increase this, please contact us.
We will return the following headers to help you manage this:
X-RateLimit-Limit
X-RateLimit-Remaining
Quick Start Guide
Learn how to create your first plan, customer and subscription in Baremetrics.
Getting your first customer into Baremetrics requires three steps! The steps must be completed in order, however. For example, you can't create a subscription without first creating a customer and a plan.
You only need to create a plan once! It can be used over and over again for multiple customers and subscriptions.
Before you begin, snag the Source ID for the provider Baremetrics. You will need this anytime you create, modify or interact with plans, customers, subscriptions or charges through the API.
Let's create a $10/mo. plan called *Basic Plan. Here's what that looks like.
The amount is in cents. So for our $10/mo. plan we will use an amount of 1000
.
RestClient.post "https://api.baremetrics.com/v1/:source_id/plans", {
oid: 'basic_plan',
name: 'Basic',
currency: 'usd',
amount: 1000,
interval: 'month',
interval_count: 1
}
If you did everything right, you'll get a 200 response with your new plan details!
{
"plan": {
"oid": "basic_plan",
"source_id": "123",
"source": "baremetrics",
"name": "Basic",
"interval": "month",
"interval_count": 1,
"trial_duration": null,
"trial_duration_unit": null,
"created": null,
"active": true,
"setup_fees": 0,
"amounts": [
{
"currency": "USD",
"symbol": "$",
"symbol_right": false,
"amount": 1000
}
]
}
}
Once you have at least one plan you can start creating customers.
You only need to provide us a unique ID to create a customer. However to get the best experience, we recommend sending Baremetrics as much data as possible!
RestClient.post "https://api.baremetrics.com/v1/:source_id/customers", {
oid: '123123123', # Provide a unique ID for the customer
name: 'Josh Pigford',
notes: 'Salesperson: Kaegan Donnelly', # This will populate the notes field in the customer profile
email: 'josh@baremetrics.com', # We use the email address to retrieve social data about your customer such as a picture and location
created: 1471343207 # The unix date "created" date for a customer. We add this to the customer profile as well.
}
If everything goes as planned, we'll return a 200 response with more details about the customer that you've created!
{
"customer": {
"oid": "123123123",
"source_id": "source_1",
"source": "stripe",
"created": 1471343207,
"email": "josh@baremetrics.com",
"name": "Josh Pigford",
"display_image": "https://logo.clearbit.com/baremetrics.com",
"display_name": "Customer 1",
"notes": 'Salesperson: Kaegan Donnelly',
"ltv": 0,
"is_active": false,
"is_canceled": false,
"current_mrr": 0,
"current_plans": []
}
}
Alright, you're most of the way there! If you look at your Baremetrics dashboard though you won't see a whole lot. Since Baremetrics is all about tracking your subscriptions, this final step is crucial to getting your key metrics and insights!
You can get really fancy with subscriptions with things like addons and quantities, but we're going to keep this first one really simple.
RestClient.post "https://api.baremetrics.com/v1/:source_id/subscriptions", {
oid: 'abcdabcd', # A unique ID for the subscription
started_at: 1471887288, # The date the subscription begins
canceled_at: nil, # The date the subscription ends, if applicable
plan_oid: 'basic_plan', # The ID of the plan you created earlier
customer_oid: '123123123', # The ID of the customer you created earlier
}
Metrics generally update about once every 30 minutes, but it can take a couple of hours at times. Check the "Last Updated" date at the top right of your dashboard to see when we last calculated your metrics.
Here's what your finished subscription customer will look like in Baremetrics!
Reporting Issues
If you come across any issues, please reach out to support, including the following:
- A brief description of what you are trying to do, what you were expecting, and what actually happened
- Include the
request-id
(notx-request-id
) header returned by our API for any requests you have made.
List Sources
Each Plan, Customer, Subscription and Charge belongs to a source. A source can be Payment Provider or the Baremetrics API.
When you want to interact with any of these objects, you must supply the Source in the URL. For example: GET /v1/:source_id/subscriptions
You can get your source_id
from the Sources endpoint
Please note that while you can read data from your Payment Provider sources, you can only modify data that has been added via the API.
Create Plan
Trials
When creating a subscription with a plan that has a trial, only the first plan will trigger a trial.
For example, if you create a subscription on Plan A, which has a 7 day trial, and then on day 2 you switch them to Plan B, the trial will continue until day 7, at which point they will become a paying customer on Plan B.
Update Customer
This endpoint allows you to update the basic information stored on a Customer, such as first name, last name and notes
Create Customer
This endpoint allows you to create a customer record. After you create the record, you will be able to create a Subscription
It may take a little while for us to fetch all of the profile information for the customer.
Delete Customer
You must delete all subscriptions for this customer before you can remove them.
Update Subscription
This allows you to update a Subscription, such as changing plans and addons.
Passing an empty "addons" array will remove all addons from this subscription.
It may take a while for your updates to appear in your metrics. There may also be a delay in the data being fully displayed in the GET /subscriptions endpoint.
Cancel Subscription
This endpoint allows you to cancel a subscription.
It may take a while for your cancellations to appear in your metrics.
To update the canceled_at time on a subscription, you may send subsequent canceled events. However, you cannot set the date further forward than it currently is set.
Create Subscription
This endpoint allows you to create a Subscription.
It may take a while for your subscriptions to appear in your metrics. There may also be a delay in the data being fully displayed in the GET /subscriptions endpoint.
How and why do I use addons?
Addons are used to add additional charges to a base plan. They allow you to create a variety of different combinations of features without creating a separate plan for each possible combination.
Let's look at a hypothetical way of charging for Baremetrics.
We could have a base subscription of $25/mo. Additional features like dunning, customer profiles, etc. could be treated as an addon.
$25/mo. base charge + $25 addon for Dunning = $50/mo.
We will automatically create charges for your subscriptions. If you don't want this to happen, then please contact us.
Delete Subscription
It may take a while for your subscriptions to disappear from your metrics.
Create Charge
Create "One-Off" charges that are not linked to a subscription.
These charges do not affect MRR. They only impact Net Revenue and Other Revenue.
If you are managing subscription charges manually, please note that this will not impact the subscription state or MRR. For example, if you stop sending charges, the subscription will stay active until you cancel it. This feature is purely designed to allow people to control the timing of charges, and for people who have custom proration methods.
If you want to manually manage subscription charges, then please contact support.
Otherwise, we will automatically create charges.
Delete Charge
Delete "One-Off" charges that are not linked to a subscription.
You can only remove charges that were created via the API directly. Charges created automatically from Subscriptions cannot be removed via this endpoint.
Create Refund
Create "One-Off" refunds that are not linked to a subscription.
These refunds do not affect MRR. They only impact Net Revenue and Other Revenue.
Delete Refund
Delete "One-Off" refunds that are not linked to a subscription.
You can only remove refunds that were created via the API directly. Refunds created automatically from Subscriptions cannot be removed via this endpoint.
Available Metrics
The following metrics are available through our Read API.
- active_customers
- active_subscriptions
- active_trials
- arpu
- arr
- cancellations
- churned_customers
- converted_trials
- coupons
- downgrades
- failed_charges
- fees
- ltv
- mrr
- mrr_growth_rate
- net_revenue
- net_revenue_churn
- new_customers
- new_subscriptions
- new_trials
- other_revenue
- plan_quantities
- quick_ratio
- reactivations
- refunds
- revenue_churn
- trial_conversion
- trial_time_to_cancelation
- trial_time_to_conversion
- upgrades
- user_churn
Show Customers
Returns a list of customers that make up this metric. For example, the upgrades metric will return all customers who have upgraded within the selected range. You can also see their MRR contribution.
List Fields
Returns the fields that can be used to create/search a segment. The key is the category, and a category contains multiple fields.
Set Attributes
Create or update properties on customers. This will work across all sources.
If you have multiple customers with the same OID (across multiple Sources) then this will update them all.
You must specify an oid, or email.
Array fields should have a comma separated list value