The Baremetrics API Developer Hub

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.

The Baremetrics API is currently in alpha testing. If you would like to help us test it, please reach out.

    
Suggest Edits

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.

Suggest Edits

Authentication

Authentication to the Baremetrics API is performed using a bearer token. To use this, send the following with your request:

 
-H "Authorization: Bearer APIKEY"

You can view your API key here

All requests must be sent over HTTPS

Authentication Error

{
  "error": "Unauthorized. Token not found"
}

Test Authentication

You can call the following endpoint to confirm you are authenticated

RestClient.get 'https://api.baremetrics.com/v1/account'
 

To help you build your integration, we have setup a full sandbox environment for you.

We frequently clear the data in the sandbox API, so please do not store anything you need in here.

You can view your sandbox API key here

Sandbox API

You can use the Sandbox API by using: https://api-sandbox.baremetrics.com

Sandbox Dashboard

You can access the Sandbox Dashboard in your API Settings

You must access the sandbox from this link. Trying to access it directly will ask for a username/password, and your existing ones won't work for the sandbox.

Suggest Edits

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
    }
  }
}
Suggest Edits

Rate Limit

 

Our rate limit set to 1000 requests per hour. 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
Suggest Edits

Quick Start Guide

Learn how to create your first plan, customer and subscription in Baremetrics. Still need help? Join us in the #api channel in our Slack!

 

Getting your first customer into Baremetrics requires only 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.

Create a Plan

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,
  source_id: unique_id
}

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

Create a Customer

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.
  source_id: unique_id
}

If everything goes as planned, we'll return a 200 response with more details about the customer that you've created!

{
  "customer": {
    "email": "josh@baremetrics.com",
    "notes": 'Salesperson: Kaegan Donnelly',
    "created": 1471343207,
    "oid": "123123123",
    "name": "Josh Pigford",
    "display_name": "josh@baremetrics.com",
    "ltv": 0,
  }
}

Create a Subscription

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
  hw: unique_id
}

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!

Suggest Edits

Get Account

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/account
RestClient.get "https://api.baremetrics.com/v1/account"
{
  "account": {
    "id": 'account_id',
    "default_currency": {
      "id": "usd",
      "alternate_symbols": [
        "US$"
      ],
      "decimal_mark": ".",
      "disambiguate_symbol": "US$",
      "html_entity": "$",
      "iso_code": "USD",
      "iso_numeric": "840",
      "name": "United States Dollar",
      "priority": 1,
      "smallest_denomination": 1,
      "subunit": "Cent",
      "subunit_to_unit": 100,
      "symbol": "$",
      "symbol_first": true,
      "thousands_separator": ","
    },
    "company": "Example Company",
    "created_at": 123456789
  }
}
 
Suggest Edits

List Sources

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/sources
RestClient.get "https://api.baremetrics.com/v1/sources"
{
  "sources": [
    {
      "id": "source_id",
      "provider": "stripe",
      "provider_id": "<stripe_account_id>"
    },
    {
      "id": "source_id",
      "provider": "baremetrics",
      "provider_id": null
    }
  ]
}
 

Each Plan, Customer, Subscription and Charge belongs to a source. A source can be Stripe, Braintree, Recurly 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 Stripe, Braintree and Recurly sources, you can only modify data that has been added via the API.

Suggest Edits

List Plans

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/plans
RestClient.get "https://api.baremetrics.com/v1/:source_id/plans"
{
  "plans": [
    {
      "oid": "plan_1",
      "source_id": "123",
      "source": "baremetrics",
      "name": "Plan 1",
      "interval": "year",
      "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": 450000
        }
      ]
    },
    {
      "oid": "plan_2",
      "source_id": "123",
      "source": "baremetrics",
      "name": "Plan 2",
      "interval": "year",
      "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": 450000
        }
      ]
    }
  ]
}

Path Params

source_id
string
required

Please see Sources

Query Params

search
string

Allows you to search based on the name or oid fields

 
Suggest Edits

Show Plan

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/plans/oid
RestClient.get "https://api.baremetrics.com/v1/:source_id/plans/:oid"
{
  "plan": {
    "oid": "plan_2",
    "source_id": "123",
    "source": "baremetrics",
    "name": "Plan 2",
    "interval": "year",
    "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": 450000
      }
    ]
  }
}

Path Params

oid
string
required
source_id
string
required

Please see Sources

 
Suggest Edits

Update Plan

 

Query Auth

 Authentication is required for this endpoint.
put https://api.baremetrics.com/v1/source_id/plans/plan_oid
RestClient.put "https://api.baremetrics.com/v1/:source_id/plans/my_unique_id", {
  name: 'A new plan name',
}
{
  "plan": {
    "oid": "plan_2",
    "source_id": "123",
    "source": "baremetrics",
    "name": "Plan 2",
    "interval": "year",
    "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": 450000
      }
    ]
  }
}

Path Params

plan_oid
string
required

Your interval plan id

source_id
string
required

Please see Sources

Body Params

name
string
required

The new name of this plan

 
Suggest Edits

Create Plan

Create a plan for use when creating or updating subscriptions.

 

Query Auth

 Authentication is required for this endpoint.
post https://api.baremetrics.com/v1/source_id/plans
RestClient.post "https://api.baremetrics.com/v1/:source_id/plans", {
  oid: 'my_unique_id',
  name: 'My awesome plan!',
  currency: 'usd',
  amount: 100, 
  interval: 'month',
  interval_count: 1
}
{
  "plan": {
    "oid": "plan_2",
    "source_id": "123",
    "source": "baremetrics",
    "name": "Plan 2",
    "interval": "year",
    "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": 450000
      }
    ]
  }
}
{
	"error": "Error message here"
}

Path Params

source_id
string
required

Please see Sources

Body Params

oid
string
required

Your unique ID for the plan

name
string
required

Your internal name for this plan. This will be displayed in the Plan Breakout section

currency
string
required

The ISO code of the currency of this plan. E.G: usd

amount
int32
required

How much is this plan? (In cents)

interval
string
required

day, month or year

interval_count
int32
required
 
Suggest Edits

Delete Plan

 

Query Auth

 Authentication is required for this endpoint.
delete https://api.baremetrics.com/v1/source_id/plans/oid
RestClient.delete "https://api.baremetrics.com/v1/:source_id/plans/:oid"
Try the API to see results

Path Params

oid
string
required
source_id
string
required

Please see Sources

 

You must delete all subscriptions on this plan before you can remove it.

Suggest Edits

List Customers

Fetch a list of all customers on your account

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/customers
RestClient.get "https://api.baremetrics.com/v1/:source_id/customers"
{
  "customers": [
    {
      "email": "customer_1@baremetrics.com",
      "notes": null,
      "created": 1471343207,
      "oid": "customer_1",
      "name": null,
      "display_name": "customer_1@baremetrics.com",
      "ltv": 100
    },
    {
      "email": "customer_2@baremetrics.com",
      "notes": "Some notes",
      "created": 1471343207,
      "oid": "customer_2",
      "name": null,
      "display_name": "customer_2@baremetrics.com",
      "ltv": 100
    },
  ]
}

Path Params

source_id
string
required

Please see Sources

Query Params

search
string

Allows you to search for a customer based on: oid, email, first_name, last_name and notes

 
Suggest Edits

Show Customer

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/customers/oid
RestClient.get "https://api.baremetrics.com/v1/:source_id/customers/:oid"
{
  "customer": {
    "email": "customer_1@baremetrics.com",
    "notes": null,
    "created": 1471343207,
    "oid": "customer_1",
    "name": null,
    "display_name": "customer_1@baremetrics.com",
    "ltv": 100
  }
}

Path Params

oid
string
required
source_id
string
required

Please see Sources

 
Suggest Edits

List Customer Events

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/customers/oid/events
RestClient.get "https://api.baremetrics.com/v1/:source_id/customers/:oid/events"
{
  "events": [
    {
      "id": "id_1",
      "event_type": "new_customer",
      "source": "baremetrics",
      "source_id": "baremetrics_1",
      "timestamp": 1475452800
    },
    {
      "id": "id_2",
      "event_type": "charge",
      "source": "baremetrics",
      "source_id": "baremetrics_1",
      "timestamp": 1475452800
    }
  ]
}

Path Params

source_id
string
required

Please see Sources

oid
string
required
 
Suggest Edits

Update Customer

This endpoint allows you to update the basic information stored on a Customer, such as first name, last name and notes

 

Query Auth

 Authentication is required for this endpoint.
put https://api.baremetrics.com/v1/source_id/customers/customer_oid
RestClient.put "https://api.baremetrics.com/v1/:source_id/customers/my_unique_id", {
  notes: 'A totally awesome customer!',
}
{
  "customer": {
    "email": "johnny@baremetrics.com",
    "notes": 'A totally awesome customer!',
    "created": 1471343207,
    "oid": "my_unique_id",
    "name": "Johnny Smmith",
    "display_name": "johnny@baremetrics.com",
    "ltv": 100
  }
}
{
	"error": "Error message here"
}

Path Params

customer_oid
string
required

Your unique ID for the customer

source_id
string
required

Please see Sources

Body Params

name
string
notes
string
created
date-time

Unix timestamp of when this customer was created

email
string

Email for this customer

 
Suggest Edits

Create Customer

This endpoint allows you to create a customer record. After you create the record, you will be able to create a Subscription

 

Query Auth

 Authentication is required for this endpoint.
post https://api.baremetrics.com/v1/source_id/customers
RestClient.post "https://api.baremetrics.com/v1/:source_id/customers", {
  oid: 'my_unique_id',
  name: 'Johnny Smith',
  notes: 'An awesome customer!',
  email: 'johnny@baremetrics.com',
  created: 1471343207
}
{
  "customer": {
  	"email": "johnny@baremetrics.com",
    "notes": 'An awesome customer!',
    "created": 1471343207,
    "oid": "my_unique_id",
    "name": "Johnny Smmith",
    "display_name": "johnny@baremetrics.com",
    "ltv": 0
  }
}
{
	"error": "Error message here"
}

Path Params

source_id
string
required

Please see Sources

Body Params

name
string
notes
string

Your own notes for this customer. These will be displayed in the profile

email
string

An email address for this customer. This is used to lookup extra profile information

oid
string
required

Your unique ID for the customer

created
date-time

A unix timestamp of when this customer was created. Defaults to now.

 

It may take a little while for us to fetch all of the profile information for the customer.

Suggest Edits

Delete Customer

 

Query Auth

 Authentication is required for this endpoint.
delete https://api.baremetrics.com/v1/source_id/customers/oid
RestClient.delete "https://api.baremetrics.com/v1/:source_id/customers/:oid"
Try the API to see results

Path Params

oid
string
required
source_id
string
required

Please see Sources

 

You must delete all subscriptions for this customer before you can remove them.

Suggest Edits

List Subscriptions

Get all subscriptions linked to this API Key.

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/subscriptions
RestClient.get "https://api.baremetrics.com/v1/:source_id/subscriptions"
{
  "subscriptions": [
    {
      "oid": "sub_1",
      "customer": {
        "email": "customer_1@baremetrics.com",
        "notes": null,
        "created": 1471343207,
        "oid": "customer_1",
        "name": null,
        "display_name": "customer_1@baremetrics.com",
        "ltv": 100
      },
      "canceled_at": null,
      "started_at": 1465028473,
      "active": true,
      "last_event_received_at": 1465028473,
      "processed": true,
      "plan": {
        "oid": "plan_1",
        "source_id": "123",
        "source": "baremetrics",
        "name": "Plan 1",
        "interval": "year",
        "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": 450000
          }
        ]
      },
      "upcoming_plan_change": {
        "occurred_at": 1474588800,
        "plan": {
          "oid": "plan_1",
          "source_id": "123",
          "source": "baremetrics",
          "name": "Plan 1",
          "interval": "year",
          "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": 450000
            }
          ]
        }
      }
    },
    {
      "oid": "sub_2",
      "customer": {
        "email": "customer_2@baremetrics.com",
        "notes": null,
        "created": 1471343207,
        "oid": "customer_2",
        "name": null,
        "display_name": "customer_2@baremetrics.com",
        "ltv": 100
      },
      "canceled_at": null,
      "started_at": 1443309183,
      "active": false,
      "last_event_received_at": 1465028473,
      "processed": true,
      "upcoming_plan_change": null,
      "plan": {
        "oid": "plan_2",
        "source_id": "123",
        "source": "baremetrics",
        "name": "Plan 2",
        "interval": "year",
        "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": 450000
          }
        ]
      }
    }
  ]
}

Path Params

source_id
string
required

Please see Sources

Query Params

customer_oid
string

This allows you to return subscriptions for a given customer

 
Suggest Edits

Show Subscription

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/subscriptions/oid
RestClient.get "https://api.baremetrics.com/v1/:source_id/subscriptions/:oid"
{
  "subscription": {
    "oid": "sub_1",
    "customer": {
      "email": "customer_1@baremetrics.com",
      "notes": null,
      "created": 1471343207,
      "oid": "customer_1",
      "name": null,
      "display_name": "customer_1@baremetrics.com",
      "ltv": 100
    },
    "canceled_at": null,
    "started_at": 1465028473,
    "active": true,
    "last_event_received_at": 1465028473,
    "processed": true,
    "plan": {
      "oid": "plan_1",
      "source_id": "123",
      "source": "baremetrics",
      "name": "Plan 1",
      "interval": "year",
      "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": 450000
        }
      ]
    },
    "upcoming_plan_change": {
      "occurred_at": 1474588800,
      "plan": {
        "oid": "plan_1",
        "source_id": "123",
        "source": "baremetrics",
        "name": "Plan 1",
        "interval": "year",
        "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": 450000
          }
        ]
      }
    }
  }
}

Path Params

oid
string
required
source_id
string
required

Please see Sources

 
Suggest Edits

Update Subscription

This allows you to update a Subscription, such as changing plans and addons.

 

Query Auth

 Authentication is required for this endpoint.
put https://api.baremetrics.com/v1/source_id/subscriptions/subscription_oid
 RestClient.put "https://api.baremetrics.com/v1/:source_id/subscriptions/my_unique_id", {
  occurred_at: 1471343207,
  plan_oid: 'my_new_unique_plan_id',
  quantity: 1,
  addons: [{
    oid: 'my_unique_addon_1_id',
    amount: 100,
    quantity: 1
  }, {
    oid: 'my_unique_addon_2_id',
    amount: 50,
    quantity: 1
  }, {
    oid: 'my_unique_addon_3_id',
    amount: 25,
    quantity: 1
  }]
}
{
  "event": {
    "id": "48X4cZ3T25MKkL",
    "type": "subscription.updated",
    "info": {
      "plan_oid": "1476719008009",
      "occurred_at": 1480421495,
      "quantity": 1,
      "addons" : [
        {
          "oid": "addon_1",
          "amount": 100,
          "quantity": 1
        },
        {
          "oid": "addon_2",
          "amount": 50,
          "quantity": 1
        },
        {
          "oid": "addon_3",
          "amount": 25,
          "quantity": 1
        }
      ]
    },
    "occurred_at": 1480421495,
    "received_at": 1480421495
  }
}
{
	"error": "Error message here"
}

Path Params

subscription_oid
string
required

Your unique ID for the subscription

source_id
string
required

Please see Sources

Body Params

plan_oid
string
required

Your unique ID for the plan

occurred_at
date-time

A unix timestamp of when this change occurred. Defaults to now

addons
array

See Example. Note: passing an empty array will reset the addons on this subscriptions. Passing null will be ignored.

quantity
int32
 

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.

Example Addons Array

[ 
  { 
    oid: 'addon_1', # Your unique ID for the addon
    amount: 100, 
    quantity: 1 
  }, 
  { 
    oid: 'addon_2', # Your unique ID for the addon
    amount: 50, 
    quantity: 1 
  }  
]
Suggest Edits

Cancel Subscription

This endpoint allows you to cancel a subscription.

 

Query Auth

 Authentication is required for this endpoint.
put https://api.baremetrics.com/v1/source_id/subscriptions/subscription_oid/cancel
RestClient.put "https://api.baremetrics.com/v1/:source_id/subscriptions/:subscription_oid/cancel", {
  canceled_at: 1471343207
}
{
  "event": {
    "id": "48X3C1W4w5vCbx",
    "type": "subscription.canceled",
    "info": {
      "canceled_at": 1480421362,
      "addons": []
    },
    "occurred_at": 1480421362,
    "received_at": 1480421362
  }
}
{
	"error": "Error message here"
}

Path Params

subscription_oid
string
required

Your unique ID for the subscription

source_id
string
required

Please see Sources

Body Params

canceled_at
date-time
required

A unix timestamp of when this subscription was, or should be canceled.

 

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.

Suggest Edits

Create Subscription

This endpoint allows you to create a Subscription.

 

Query Auth

 Authentication is required for this endpoint.
post https://api.baremetrics.com/v1/source_id/subscriptions
RestClient.post "https://api.baremetrics.com/v1/:source_id/subscriptions", {
  oid: 'my_unique_id',
  started_at: 1471887288,
  canceled_at: nil,
  plan_oid: 'my_unique_plan_id',
  customer_oid: 'my_unique_customer_id',
  quantity: 1,
  addons: [{
    oid: 'my_unique_addon_1_id',
    amount: 100,
    quantity: 1
  }, {
    oid: 'my_unique_addon_2_id',
    amount: 50,
    quantity: 1
  }]
}
{
  "event": {
    "id": "48X1ZZHtRaBtfN",
    "type": "subscription.created",
    "info": {
      "oid": "subscription_51",
      "started_at": 1474381618,
      "plan_oid": "1476719008009",
      "customer_oid": "1476719006346",
      "auto_charge": true,
      "canceled_at": null,
      "quantity": 1,
      "addons" : [
        {
          "oid": "addon_1",
          "amount": 100,
          "quantity": 1
        },
        {
          "oid": "addon_2",
          "amount": 50,
          "quantity": 1
        }
      ]
    },
    "occurred_at": 1474381618,
    "received_at": 1480421211
  }
}
{
	"error": "Error message here"
}

Path Params

source_id
string
required

Please see Sources

Body Params

oid
string
required

Your unique ID for the subscription

started_at
date-time
required

A unix timestamp of when this subscription started

canceled_at
date-time

A unix timestamp of when this subscription was, or should be canceled. This cannot be changed, so only set this if you are certain you know when the subscription will end.

plan_oid
string
required

Your unique ID for the plan

customer_oid
string
required

Your unique ID for the customer

addons
array
quantity
int32
 

You will need to create a Customer and Plan before you can use this endpoint.

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.

Example Addons Array

[ 
  { 
    oid: 'addon_1', 
    amount: 100, 
    quantity: 1 
  }, 
  { 
    oid: 'addon_2', 
    amount: 50, 
    quantity: 1 
  }  
]

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.

Suggest Edits

Delete Subscription

 

Query Auth

 Authentication is required for this endpoint.
delete https://api.baremetrics.com/v1/source_id/subscriptions/oid
RestClient.delete "https://api.baremetrics.com/v1/:source_id/subscriptions/:oid"
Try the API to see results

Path Params

oid
string
required
source_id
string
required

Please see Sources

 

It may take a while for your subscriptions to disappear from your metrics.

Suggest Edits

List Annotations

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/annotations
RestClient.get "https://api.baremetrics.com/v1/annotations"
{
  "annotations": [
    {
      "id": "our_unique_id",
      "metric": "mrr",
      "annotation": "New Feature 1",
      "date": "2015-03-31",
      "global": true,
      "user": {
        "id": "user_id",
        "email": "user@baremetrics.com",
        "admin": true,
        "name": "User Name"
      }
    }
  ]
}
 
Suggest Edits

Show Annotation

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/annotations/id
RestClient.get "https://api.baremetrics.com/v1/annotations/:id"
{
  "annotation": {
    "id": "our_unique_id",
    "metric": "mrr",
    "annotation": "New Feature 1",
    "date": "2015-03-31",
    "global": true,
    "user": {
      "id": "user_id",
      "email": "user@baremetrics.com",
      "admin": true,
      "name": "User Name"
    }
  }
}

Path Params

id
string
required
 
Suggest Edits

Create Annotation

 

Query Auth

 Authentication is required for this endpoint.
post https://api.baremetrics.com/v1/annotations
RestClient.post "https://api.baremetrics.com/v1/annotations", {
  metric: 'mrr',
  annotation: 'Launched a Feature',
  date: '2015-01-01',
  globale: true,
  user_id: '1',
}
{
  "annotation": {
    "id": "our_unique_id",
    "metric": "mrr",
    "annotation": "New Feature 1",
    "date": "2015-03-31",
    "global": true,
    "user": {
      "id": "user_id",
      "email": "user@baremetrics.com",
      "admin": true,
      "name": "User Name"
    }
  }
}

Body Params

metric
string
required

Which metric is this for?

annotation
string
required

The annotation text

date
date
required

YYYY-MM-DD

global
boolean
required

Should this show on all graphs?

user_id
string
required

Who added this annotation?

 
Suggest Edits

Delete Annotation

 

Query Auth

 Authentication is required for this endpoint.
delete https://api.baremetrics.com/v1/annotations/id
RestClient.delete "https://api.baremetrics.com/v1/annotations/:id"
Try the API to see results

Path Params

id
string
required
 
Suggest Edits

List Goals

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/goals
RestClient.get "https://api.baremetrics.com/v1/goals"
{
  "goals": [
    {
      "id": "our_unique_id",
      "metric": "mrr",
      "end_amount": 2000,
      "start_amount": 1000,
      "end_date": "2016-06-30",
      "start_date": "2016-01-02",
      "name": "MRR Growth"
    }
  ]
}
 
Suggest Edits

Show Goal

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/goals/id
RestClient.get "https://api.baremetrics.com/v1/goals/:id"
{
  "goal": {
    "id": "our_unique_id",
    "metric": "mrr",
    "end_amount": 2000,
    "start_amount": 1000,
    "end_date": "2016-06-30",
    "start_date": "2016-01-02",
    "name": "MRR Growth"
  }
}

Path Params

id
string
required

Unique ID

 
Suggest Edits

Create Goal

 

Query Auth

 Authentication is required for this endpoint.
post https://api.baremetrics.com/v1/goals
RestClient.post "https://api.baremetrics.com/v1/goals", {
  metric: 'mrr',
  start_amount: 1000,
  end_amount: 2000,
  start_date: "2015-01-01",
  end_date: "2015-02-01",
  name: "Goal 1"
}
{
  "goal": {
    "id": "our_unique_id",
    "metric": "mrr",
    "end_amount": 2000,
    "start_amount": 1000,
    "end_date": "2016-06-30",
    "start_date": "2016-01-02",
    "name": "Goal 1"
  }
}

Body Params

metric
string
required
start_amount
int32
required

In cents

end_amount
int32
required

In cents

start_date
date
required
end_date
date
required
name
string
required

The goal name

 
Suggest Edits

Delete Goal

 

Query Auth

 Authentication is required for this endpoint.
delete https://api.baremetrics.com/v1/goals/id
RestClient.delete "https://api.baremetrics.com/v1/goals/:id"
Try the API to see results

Path Params

id
string
required
 
Suggest Edits

List Users

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/users
RestClient.get "https://api.baremetrics.com/v1/users"
{
  "users": [
    {
      "id": "our_unique_id",
      "email": "user@baremetrics.com",
      "admin": true,
      "name": "User Name"
    }
  ]
}
 
Suggest Edits

Show User

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/users/id
RestClient.get "https://api.baremetrics.com/v1/users/:id"
{
  "user": {
    "id": "our_unique_id",
    "email": "user@baremetrics.com",
    "admin": true,
    "name": "User Name"
  }
}

Path Params

id
string
required
 
Suggest Edits

List Charges

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/charges
RestClient.get "https://api.baremetrics.com/v1/:source_id/charges"
{
  "charges": [
    {
      "oid": "your_unique_id",
      "source_id": "source_id",
      "source": "baremetrics",
      "status": "paid",
      "created": 1475452800,
      "customer": {
        "email": "customer_2@baremetrics.com",
        "notes": "Some notes",
        "created": 1471343207,
        "oid": "customer_2",
        "name": null,
        "display_name": "customer_2@baremetrics.com",
        "ltv": 100
      },
      "amount": 450000
    }
  ]
}

Path Params

source_id
string
required

Please see Sources

 
Suggest Edits

Show Charge

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/charges/oid
RestClient.get "https://api.baremetrics.com/v1/:source_id/charges/:oid"
{
  "charge": {
    "oid": "your_unique_id",
    "source_id": "source_id",
    "source": "baremetrics",
    "status": "paid",
    "created": 1475452800,
    "customer": {
      "email": "customer_2@baremetrics.com",
      "notes": "Some notes",
      "created": 1471343207,
      "oid": "customer_2",
      "name": null,
      "display_name": "customer_2@baremetrics.com",
      "ltv": 100
    },
    "amount": 450000
  }
}

Path Params

source_id
string
required

Please see Sources

 
Suggest Edits

Create Charge

Create "One-Off" charges that are not linked to a subscription.

 

Query Auth

 Authentication is required for this endpoint.
post https://api.baremetrics.com/v1/source_id/charges
RestClient.post "https://api.baremetrics.com/v1/:source_id/charges", {
  oid: 'my_unique_id',
  amount: 100,
  currency: 'usd',
  customer_oid: 'my_unique_customer_oid'
}
{
  "charge": {
    "oid": "your_unique_id",
    "source_id": "source_id",
    "source": "baremetrics",
    "status": "paid",
    "created": 1475452800,
    "customer": {
      "email": "customer_2@baremetrics.com",
      "notes": "Some notes",
      "created": 1471343207,
      "oid": "customer_2",
      "name": null,
      "display_name": "customer_2@baremetrics.com",
      "ltv": 100
    },
    "amount": 450000
  }
}

Path Params

source_id
string
required

Please see Sources

Body Params

oid
string
required

Your unique reference for this charge

amount
int32
required

The charge amount (in cents)

currency
string
required

The ISO code of the currency of this plan. E.G: usd

customer_oid
string
required

Your unique ID for the customer

created
date-time

Unix timestamp of when this was created

status
string

The status of this charge. Can be paid or failed. Defaults to paid.

 

These charges do not affect MRR. They only impact Net Revenue and Other Revenue.

Suggest Edits

List Events

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/events
RestClient.get "https://api.baremetrics.com/v1/:source_id/events"
{
  "events": [
    {
      "id": "id_1",
      "event_type": "charge",
      "source": "baremetrics",
      "source_id": "baremetrics_1",
      "timestamp": 1475452800,
      "customer": {
        "oid": "1476719006346",
        "source_id": "baremetrics_1",
        "source": "baremetrics",
        "created": 1476719007,
        "email": "customer@example.com",
        "name": "Example",
        "display_image": "https://logo.clearbit.com/example.com",
        "display_name": "Example",
        "notes": null,
        "ltv": 100
      }
    },
    {
      "id": "id_2",
      "event_type": "new_customer",
      "source": "baremetrics",
      "source_id": "baremetrics_1",
      "timestamp": 1475452800,
      "customer": {
        "oid": "1476719006346",
        "source_id": "baremetrics_1",
        "source": "baremetrics",
        "created": 1476719007,
        "email": "customer@example.com",
        "name": "Example",
        "display_image": "https://logo.clearbit.com/example.com",
        "display_name": "Example",
        "notes": null,
        "ltv": 100
      }
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "page": 0,
      "per_page": 30
    }
  }
}

Path Params

source_id
string
required

Please see Sources

Query Params

live_stream
string

Set this to true to only return events that show up in the live stream

 
Suggest Edits

Show Event

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/source_id/events/id
RestClient.get "https://api.baremetrics.com/v1/:source_id/events/:id"
{
  "event": {
    "id": "id_1",
    "event_type": "charge",
    "source": "baremetrics",
    "source_id": "baremetrics_1",
    "timestamp": 1475452800,
    "customer": {
      "oid": "1476719006346",
      "source_id": "baremetrics_1",
      "source": "baremetrics",
      "created": 1476719007,
      "email": "customer@example.com",
      "name": "Example",
      "display_image": "https://logo.clearbit.com/example.com",
      "display_name": "Example",
      "notes": null,
      "ltv": 100
    }
  }
}

Path Params

source_id
string
required

Please see Sources

id
string
required
 
Suggest Edits

Available Metrics

 

The following metrics are available through our Read API.

- active_customers
- active_subscriptions
- add_on_mrr
- arpu
- arr
- cancellations
- coupons
- downgrades
- failed_charges
- fees
- ltv
- mrr
- net_revenue
- new_customers
- other_revenue
- reactivated_customers
- refunds
- revenue_churn
- trial_conversions
- upgrades
- user_churn
Suggest Edits

Show Summary

 

Query Auth

 Authentication is required for this endpoint.
get https://api.baremetrics.com/v1/metrics
RestClient.get "https://api.baremetrics.com/v1/metrics?start_date=2016-11-26&end_date=2016-11-29"
{
  "metrics": [
    {
      "human_date": "2016-11-26",
      "date": 1480118400,
      "active_customers": 642,
      "active_subscriptions": 642,
      "add_on_mrr": 0,
      "arpu": 9383,
      "arr": 72289044,
      "cancellations": 0,
      "coupons": 43300,
      "downgrades": 0,
      "failed_charges": 1,
      "fees": 7373,
      "ltv": 159039,
      "mrr": 6024087,
      "net_revenue": 233498,
      "new_customers": 0,
      "other_revenue": 0,
      "reactivated_customers": 0,
      "refunds": 0,
      "revenue_churn": 543,
      "trial_conversions": 0,
      "upgrades": 1,
      "user_churn": 590
    },
    {
      "human_date": "2016-11-27",
      "date": 1480204800,
      "active_customers": 640,
      "active_subscriptions": 640,
      "add_on_mrr": 0,
      "arpu": 9362,
      "arr": 71900916,
      "cancellations": 2,
      "coupons": 6677,
      "downgrades": 1,
      "failed_charges": 1,
      "fees": 4452,
      "ltv": 158949,
      "mrr": 5991743,
      "net_revenue": 129723,
      "new_customers": 0,
      "other_revenue": 0,
      "reactivated_customers": 0,
      "refunds": 0,
      "revenue_churn": 497,
      "trial_conversions": 0,
      "upgrades": 1,
      "user_churn": 589
    },
    {
      "human_date": "2016-11-28",
      "date": 1480291200,
      "active_customers": 640,
      "active_subscriptions": 640,
      "add_on_mrr": 0,
      "arpu": 9454,
      "arr": 72608820,
      "cancellations": 4,
      "coupons": 10336,
      "downgrades": 1,
      "failed_charges": 15,
      "fees": 9354,
      "ltv": 156011,
      "mrr": 6050735,
      "net_revenue": 293579,
      "new_customers": 2,
      "other_revenue": 0,
      "reactivated_customers": 0,
      "refunds": 0,
      "revenue_churn": 533,
      "trial_conversions": 0,
      "upgrades": 2,
      "user_churn": 606
    },
    {
      "human_date": "2016-11-29",
      "date": 1480377600,
      "active_customers": 643,
      "active_subscriptions": 643,
      "add_on_mrr": 0,
      "arpu": 9449,
      "arr": 72913620,
      "cancellations": 0,
      "coupons": 4299,
      "downgrades": 1,
      "failed_charges": 3,
      "fees": 3168,
      "ltv": 164342,
      "mrr": 6076135,
      "net_revenue": 99926,
      "new_customers": 1,
      "other_revenue": 0,
      "reactivated_customers": 0,
      "refunds": 0,
      "revenue_churn": 451,
      "trial_conversions": 0,
      "upgrades": 1,
      "user_churn": 575
    }
  ]
}

Query Params

start_date
string
required
end_date
string
required
 
Suggest Edits

Show Metric

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.baremetrics.com/v1/metrics/metric
RestClient.get "https://api.baremetrics.com/v1/metrics/mrr?start_date=2016-11-26&end_date=2016-11-292"
{
  "metrics": [
    {
      "date": 1480118400,
      "human_date": "2016-11-26",
      "value": 6024087,
      "notes": null,
      "previous": {
        "date": 1477526400,
        "human_date": "2016-10-27",
        "value": 5941979,
        "percent": 1.4,
        "notes": null
      }
    },
    {
      "date": 1480204800,
      "human_date": "2016-11-27",
      "value": 5991743,
      "notes": null,
      "previous": {
        "date": 1477612800,
        "human_date": "2016-10-28",
        "value": 5932562,
        "percent": 1,
        "notes": null
      }
    },
    {
      "date": 1480291200,
      "human_date": "2016-11-28",
      "value": 6050735,
      "notes": null,
      "previous": {
        "date": 1477699200,
        "human_date": "2016-10-29",
        "value": 5940529,
        "percent": 1.9,
        "notes": null
      }
    },
    {
      "date": 1480377600,
      "human_date": "2016-11-29",
      "value": 6076135,
      "notes": null,
      "previous": {
        "date": 1477785600,
        "human_date": "2016-10-30",
        "value": 5935279,
        "percent": 2.4,
        "notes": null
      }
    }
  ]
}

Path Params

metric
string
required

You can see a list of available metrics here

Query Params

start_date
date
required
end_date
date
required
compare_to
int32

The number of days ago to compare results to

 
Suggest Edits

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.

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.baremetrics.com/v1/metrics/metric/customers
RestClient.get "https://api.baremetrics.com/v1/metrics/new_customers/customers"
{
  "metrics": [
    {
      "date": 1475107200,
      "human_date": "2016-09-29",
      "value": 2,
      "customers": [
        {
          "customer": {
            "oid": "example",
            "source_id": "stripe_1",
            "source": "stripe",
            "created": 1474005930,
            "email": "customer@example.com",
            "name": "Example",
            "display_image": "https://logo.clearbit.com/example.com",
            "display_name": "Example",
            "notes": null,
            "ltv": 100
          },
          "current_plan": {
            "oid": "mrr_50_mo",
            "source_id": "stripe_1",
            "source": "stripe",
            "name": "Startup $50 - MRR - Monthly",
            "interval": "month",
            "interval_count": 1,
            "trial_duration": null,
            "trial_duration_unit": null,
            "created": 1450216295,
            "active": true,
            "setup_fees": 0,
            "amounts": [
              {
                "currency": "USD",
                "symbol": "$",
                "symbol_right": false,
                "amount": 5000
              }
            ]
          },
          "previous_plan": {
            "oid": "free",
            "source_id": "stripe_1",
            "source": "stripe",
            "name": "Free",
            "interval": "month",
            "interval_count": 1,
            "trial_duration": 14,
            "trial_duration_unit": "day",
            "created": 1438620623,
            "active": true,
            "setup_fees": 0,
            "amounts": [
              {
                "currency": "USD",
                "symbol": "$",
                "symbol_right": false,
                "amount": 0
              }
            ]
          },
          "mrr": 5000
        },
        {
          "customer": {
            "oid": "example_2",
            "source_id": "stripe_1",
            "source": "stripe",
            "created": 1460175851,
            "email": "customer@example.com",
            "name": "Example 2",
            "display_image": "https://logo.clearbit.com/example.com",
            "display_name": "Example 2",
            "notes": null,
            "ltv": 100
          },
          "current_plan": {
            "oid": "mrr_25_mo",
            "source_id": "stripe_1",
            "source": "stripe",
            "name": "Hobby $25 - MRR - Monthly",
            "interval": "month",
            "interval_count": 1,
            "trial_duration": null,
            "trial_duration_unit": null,
            "created": 1450216236,
            "active": true,
            "setup_fees": 0,
            "amounts": [
              {
                "currency": "USD",
                "symbol": "$",
                "symbol_right": false,
                "amount": 2500
              }
            ]
          },
          "previous_plan": {
            "oid": "free",
            "source_id": "stripe_1",
            "source": "stripe",
            "name": "Free",
            "interval": "month",
            "interval_count": 1,
            "trial_duration": 14,
            "trial_duration_unit": "day",
            "created": 1438620623,
            "active": true,
            "setup_fees": 0,
            "amounts": [
              {
                "currency": "USD",
                "symbol": "$",
                "symbol_right": false,
                "amount": 0
              }
            ]
          },
          "mrr": 2500
        }
      ]
    }
  ]
}

Path Params

metric
string
required

You can see a list of available metrics here

Query Params

start_date
date
required
end_date
date
required
 
Suggest Edits

Show Plan Breakout

This allows you to break down a metric by plan, across a date range

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.baremetrics.com/v1/metrics/metric/plans
RestClient.get "https://api.baremetrics.com/v1/metrics/mrr/plans?start_date=2016-11-26&end_date=2016-11-292"
{
  "metrics": [
    {
      "date": 1477872000,
      "human_date": "2016-10-31",
      "value": 52664,
      "plan": {
        "oid": "startup_yearly_790",
        "source_id": "3ULWIj59pU016O",
        "source": "stripe",
        "name": "Startup (Yearly)",
        "interval": "year",
        "interval_count": 1,
        "trial_duration": null,
        "trial_duration_unit": null,
        "created": 1394818080,
        "active": true,
        "setup_fees": 0,
        "amounts": [
          {
            "currency": "USD",
            "symbol": "$",
            "symbol_right": false,
            "amount": 79000
          }
        ]
      }
    },
    {
      "date": 1477872000,
      "human_date": "2016-10-31",
      "value": 66300,
      "plan": {
        "oid": "mrr_900_yr",
        "source_id": "3ULWIj59pU016O",
        "source": "stripe",
        "name": "Pro $900 - MRR - Yearly - 3/mo discount",
        "interval": "year",
        "interval_count": 1,
        "trial_duration": null,
        "trial_duration_unit": null,
        "created": 1460564309,
        "active": true,
        "setup_fees": 0,
        "amounts": [
          {
            "currency": "USD",
            "symbol": "$",
            "symbol_right": false,
            "amount": 90000
          }
        ]
      }
    }
  ]
}

Path Params

metric
string
required

You can see a list of available metrics here

Query Params

start_date
date
required
end_date
date
required