Baremetrics User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Log in to your Baremetrics account.
2. Navigate to Settings > API.
3. Generate or copy your API key.
4. Include the key as a Bearer token in the Authorization header: 'Authorization: Bearer {api_key}'.

List Customers

• Method: GET
• URL: https://api.baremetrics.com/v1/{source_id}/customers
• Watch out for: source_id in the path refers to your Baremetrics source identifier, not a customer ID.

Request example

GET /v1/abc123/customers?per_page=30&page=1
Authorization: Bearer {api_key}

Response example

{
  "customers": [
    {"oid":"cust_1","name":"Jane Doe","email":"jane@example.com"}
  ],
  "meta": {"pagination": {"total": 100}}
}

Retrieve Customer

• Method: GET
• URL: https://api.baremetrics.com/v1/{source_id}/customers/{oid}
• Watch out for: Use your own OID (oid), not the Baremetrics internal id.

Request example

GET /v1/abc123/customers/cust_1
Authorization: Bearer {api_key}

Response example

{
  "customer": {
    "oid": "cust_1",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "current_mrr": 4900
  }
}

Create Customer

• Method: POST
• URL: https://api.baremetrics.com/v1/{source_id}/customers
• Watch out for: Only available for Baremetrics-native sources; customers from Stripe/Braintree etc. are synced automatically.

Request example

POST /v1/abc123/customers
Content-Type: application/json
{
  "oid": "cust_new",
  "name": "John Smith",
  "email": "john@example.com"
}

Response example

{
  "customer": {
    "oid": "cust_new",
    "name": "John Smith",
    "email": "john@example.com"
  }
}

Update Customer

• Method: PUT
• URL: https://api.baremetrics.com/v1/{source_id}/customers/{oid}
• Watch out for: PUT replaces updatable fields; omitted optional fields may be cleared.

Request example

PUT /v1/abc123/customers/cust_1
Content-Type: application/json
{
  "name": "Jane Updated",
  "email": "jane_new@example.com"
}

Response example

{
  "customer": {
    "oid": "cust_1",
    "name": "Jane Updated",
    "email": "jane_new@example.com"
  }
}

Delete Customer

• Method: DELETE
• URL: https://api.baremetrics.com/v1/{source_id}/customers/{oid}
• Watch out for: Only applicable to Baremetrics-native source customers. Deleting removes all associated subscription data.

Request example

DELETE /v1/abc123/customers/cust_1
Authorization: Bearer {api_key}

Response example

HTTP 204 No Content

List Subscriptions for Customer

• Method: GET
• URL: https://api.baremetrics.com/v1/{source_id}/subscriptions
• Watch out for: Filter by customer_oid to scope to a single customer.

Request example

GET /v1/abc123/subscriptions?customer_oid=cust_1
Authorization: Bearer {api_key}

Response example

{
  "subscriptions": [
    {"oid":"sub_1","plan_oid":"plan_pro","status":"active"}
  ]
}

List Sources

• Method: GET
• URL: https://api.baremetrics.com/v1/sources
• Watch out for: You must retrieve your source_id from this endpoint before making customer/subscription calls.

Request example

GET /v1/sources
Authorization: Bearer {api_key}

Response example

{
  "sources": [
    {"id": "abc123", "provider": "stripe", "provider_id": "acct_xxx"}
  ]
}

Update Customer Attributes

• Method: PUT
• URL: https://api.baremetrics.com/v1/{source_id}/customers/{oid}
• Watch out for: Custom attributes are used for segmentation in Baremetrics dashboards; key names must be pre-defined in settings.

Request example

PUT /v1/abc123/customers/cust_1
Content-Type: application/json
{
  "attributes": {"plan_tier": "enterprise", "region": "US"}
}

Response example

{
  "customer": {
    "oid": "cust_1",
    "attributes": {"plan_tier": "enterprise", "region": "US"}
  }
}

• Rate limits: Baremetrics does not publicly document specific rate limit numbers. Requests that exceed limits receive HTTP 429 responses.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No publicly documented per-plan rate limit tiers found in official docs. Contact Baremetrics support for enterprise limits.

• Pagination method: cursor

• Default page size: 30

• Max page size: 200

• Pagination pointer: per_page / page

• Webhooks available: Yes

• Webhook notes: Baremetrics supports webhooks that fire on subscription and customer lifecycle events. Configure endpoints in Settings > Webhooks.

• Alternative event strategy: Poll the REST API for changes if webhooks are not feasible.

• Webhook events: subscription.created, subscription.updated, subscription.canceled, subscription.reactivated, customer.created, customer.updated, customer.deleted, charge.created, charge.refunded

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• No SCIM support documented in official Baremetrics developer docs.

Three integration scenarios are well-supported by the documented API:

• Provision a native customer and subscription: Call GET /v1/sources to retrieve your source_id, then POST /v1/{source_id}/customers with oid, name, and email, followed by POST /v1/{source_id}/subscriptions. This only applies to Baremetrics-native sources - Stripe-synced customers are read-only.

• Enrich customer records with segmentation attributes: Pre-define attribute keys in Settings > Attributes, then PUT /v1/{source_id}/customers/{oid} with an attributes object. Keys not pre-defined in the dashboard will be rejected or silently ignored.

• Sync customer deletions: On a user removal event in your system, call DELETE /v1/{source_id}/customers/{oid} and confirm HTTP 204. Deletion is permanent and removes all associated subscription and charge history - use only for native-source customers.

Pagination uses page and per_page query parameters with a maximum of 200 records per page. Rate limits are not publicly documented; HTTP 429 is returned when limits are exceeded, with no Retry-After header provided.

Provision a new customer and subscription via Baremetrics native source

1. Call GET /v1/sources to retrieve your Baremetrics native source_id.
2. Call POST /v1/{source_id}/customers with oid, name, and email to create the customer.
3. Call POST /v1/{source_id}/subscriptions with customer_oid, plan_oid, and started_at to create the subscription.

Watch out for: This workflow only applies to the Baremetrics native source. If your billing is in Stripe, customers are auto-synced and cannot be created via API.

Enrich customer records with custom segmentation attributes

1. Pre-define custom attribute keys in Baremetrics Settings > Attributes.
2. Call GET /v1/{source_id}/customers to list existing customers and identify target OIDs.
3. Call PUT /v1/{source_id}/customers/{oid} with an 'attributes' object containing your key-value pairs.

Watch out for: Attribute keys not pre-defined in the dashboard will be rejected or silently ignored.

Sync customer deletions when a user is removed from your system

1. Receive a user deletion event in your system.
2. Call GET /v1/sources to confirm the correct source_id.
3. Call DELETE /v1/{source_id}/customers/{oid} using the customer's OID.
4. Verify HTTP 204 response to confirm deletion.

Watch out for: Deletion is permanent and removes all historical subscription and charge data for that customer in Baremetrics. Only use for Baremetrics-native source customers.

The most significant API caveat is source scope: all write operations - create, update, delete - are only available for Baremetrics-native source customers. Any customer synced from Stripe, Braintree, Chargebee, or Recurly is read-only via the API. Teams that assume full API control over their customer records will hit this wall immediately.

Additional sharp edges: the oid field is your system's identifier and must be used in all path parameters - the Baremetrics internal id is not interchangeable. Custom attributes must be pre-configured in the dashboard before they can be set via API; there is no way to create attribute keys programmatically.

Authentication is solely via static API key with no rotation mechanism documented, which is a credential hygiene concern for production integrations.