Introduction
Heads up — this is our advanced setup.
Most teams won’t need this. But if you’re working with usage- or credit-based billing, this is where the magic happens.
Overview
Atlas combines billing, usage data, and provisioning to provide a modern cockpit for product monetization. Our documentation is intended to be approachable and comprehensive, if something is not clear, or documentation is missing, please contact us.
Atlas accepts first and third party usage data to create a baseline of understanding of what users are doing in your application. Once eventing is configured, non technical resources can configure billable metrics entitlements and subscription plans for customers.
Entitlements can act as feature flags or directly integrate with existing feature flagging systems to allow basic provisioning and access gating.
Billable metrics can be turned into invoices based on configuration and delivered directly to your payment gateway for seamless collection.
Finally, our configuration CRM gateway allows you to bi-drectionally sync data to and from systems of record to ensure all data is in sync.
Key Terms
Here are some important terms to know as you navigate Atlas.
- Merchant: Atlas customer - the entity that’s using Atlas to bill their customers
- Customer: The customer of the merchant
- User: The individual who works at the customer
- Atlas User: The merchant user who is using the atlas app
- Plan: A bucket containing entitlements and/or metrics - most represent what the user is buying
- Entitlement: Static capability or feature, can be granular or high level. Can also include non software specific items that are on a contract, e.g. support hours.
- Metric: A set of events, filtered, and counted, summed, or averaged, etc. to be billed
- Price: Price set on an entitlement or billable metric
- Event: An event defined by our merchants that can be tied to a metric or feature
- Price Type: Defines price structure (one-time, tiered, capped, etc.)
- Credits: Pre-paid units that can be used to pay down invoices or unlock functionality
- Subscription: Ties a plan to a specific user/customer and invoice
- Invoice: What is billed to the customer. Contains terms and detailed line items.
- Jobs Engine: Nightly procedure of reconciling usage with subscriptions, visitors, and accounts. Generates invoices, retries, etc.
- SDK: Both client and server-side packages for calling Atlas API endpoints
Entitlements
Atlas Entitlements are static capabilities or features that help define what the customer receives by purchasing a plan.
Entitlements can also be used for non-software-specific contractual items, e.g. professional support hours or consulting.
To create an entitlement, go to the entitlements page, and press the “Create entitlement” button.
Like billable metrics, entitlements can be tied to specific events. However, this is optional and is only used to represent overall usage. If you want to bill based on usage, use a billable metric.
If you choose to tie an entitlement to an event, you’ll be able to view low, medium, and high usage statistics.
Usage is helpful at determining which capabilities may be in the wrong plan, are under or over monetized, or should be deprecated.
Every entitlement auto-generates an entitlement_key that is returned via API and can be used in provisioning or feature flagging.
Billable Metrics
Billable Metrics are designed for usage, action, and outcome-based pricing scenarios.
To create a new billable metric, go to the billable metric page and ‘Create metric’.
To create a billable metric, you must have matching events flowing into Atlas.
In the “Create metric” modal, you’ll populate a Name and Description, choose if you want to show this metric on invoice, and build the query that matches this billable metric to a specific event type.
This UI allows non-technical resources to build and change billable metrics without reliance on engineering resources.
You can either use the UI rule builder or, for power users, you can write direct SQL using the Advanced SQL editor.
In either case, you can use the Run button to quickly check if events exist for your given query.
Plans
Atlas Plans represent a collection of entitlements and billable metrics that a customer can purchase or subscribe to.
Entitlements and Billable Metrics must be created before you can add them to a Plan.
To create a Plan, go to plans page, and press the Create plan button.
Give the plan a Name, Description, Currency and Payment Terms, then press Save. You now have an empty plan ready to be populated.
The newly-created Plan will go into a ‘Draft’ state. This is to ensure changes can be made to the Plan without fear of the Plan being subscribed to by a customer.
Your newly created plan can be populated with entitlements and metrics by clicking the Add button on either.
When adding an entitlement or billable metric you’ll be asked to populate Billing Cadence, Price Type, and Price.
Customers
There are three main ways to create customers in Atlas:
- Upload a .csv file
- Use our CRM integrations
- Manually
To manually add a new customer, go to the customer page and select Add customer. Only the Name and Email fields are required.
Once a customer is created they can be linked to any available plan manually or via our SDK.
Clicking on a customer brings you to the customer detail page, which allows you to view and customize any active plan, and view and edit invoice details.
Price Details
Atlas supports multiple price types in order to support complex billing scenarios.
- Unit Pricing - Charges are based on a fixed price per unit (e.g., $10,000 platform fee / yr). This model is straightforward and can be used for many common basic billing scenarios.
- Tiered Pricing - Prices change based on quantity thresholds. For example, you might charge .50 for the next 1000, and so on. This encourages higher volume usage with price breaks.
- Package Pricing - Allows bundling of multiple units into a package at a single price. For example, you may offer user accounts in packs of 10. If a customer needs 11 users, they will need to purchase an additional pack of 10, as billing is always done in increments of 10.
- Bulk Pricing - Also known as volume pricing, bulk pricing refers to a pricing strategy used to offer reduced prices or discounts to customers who purchase quantities in bulk. For example, you may charge 1002/unit), but if you buy 200 units you charge 1.5/unit).
- Matrix Pricing - Matrix pricing uses multiple variables to calculate prices in a grid-like structure, offering flexibility for complex, customized pricing. For example, if you’re charging for API usage, you can set different prices based on the type of API response, allowing for more nuanced pricing.
Each of these models ensures you can align pricing with the value your customers receive, offering both flexibility and precision in billing.