Quickstart
This guide provides a fast path to understanding the basic workflow for setting up billing and payments with Sulu. We’ll cover the essential steps from signing up to reporting your first usage event.
For deeper dives into each concept, refer to the Core Concepts section.
1. Sign Up
First, you need a Sulu Merchant account.
- Navigate to https://platform-v2.sulu.sh/merchant to sign up.
- You will create an
Organization
(acting as aMerchant
) and aUser
account linked to it.
2. Find Your API Key
Once signed up, you’ll need your API key to interact with the Sulu API.
- Log in to the Sulu Merchant Dashboard.
- Navigate to the “Settings” section in the sidebar.
- Generate or find your existing API Key. This will be a Bearer token (e.g.,
sk_live_...
). - Keep this key secure! You’ll need it for authentication. Learn more in the Authentication guide.
3. Create a Product
Products organize your offerings. Think of them like projects or folders.
- Define what you are selling. Example: “My Awesome API”.
- Use the Create Product API endpoint or the Dashboard to create your
Product
. - You’ll need a
name
,description
, and yourmerchantId
. - Learn more about Products.
4. Define a Billable Metric
Billable Metrics represent what you charge for.
- Example:
API Requests
,Tokens Processed
,Compute Hours
. - Use the Create Billable Metric API endpoint or the Dashboard.
- Provide a
name
,description
,unit
(e.g., “requests”, “tokens”), theproductId
from the previous step, and setaggregation
toSUM
. - Learn more about Billable Metrics.
5. Create a Plan and Price
Plans link Billable Metrics
to their Prices
. A Plan
acts like a rate card.
- Create a Price: Use the Create Price API endpoint or Dashboard. Link it to your
Billable Metric
. Choose a pricingmodel
(e.g.,standard
for a fixed price) and set its properties (e.g.,unitPrice
for standard). - Create a Plan: Use the Create Plan API endpoint or Dashboard. Give it a
name
, set thebillingInterval
(e.g.,monthly
),currency
(e.g.,USD
), link it to yourProduct
, and associate thePrice
you just created. - Learn more about Plans and Prices.
6. Generate a Subscription Link
To onboard customers, generate a unique link for your Plan
.
- Use the Create Authorization Session API endpoint or the “Generate Authorization Link” button on the Plan details page in the Dashboard.
- Provide the
planId
and yourmerchantId
. - This generates a URL to be used as a subscription link.
7. Customer Subscribes
Send the generated link to your potential customer. Or open a separate Consumer account to test it out!
- When the customer visits the link, they go through the Sulu Checkout flow.
- If they’re new to Sulu, an account (
Consumer
Organization) is created. - If they already have a Sulu account, they confirm the subscription.
- Upon completion, Sulu automatically creates a
Customer
resource (linking yourMerchant
to theirConsumer
) and aSubscription
resource (linking theCustomer
to yourPlan
). - Learn more about Customers and Subscriptions.
8. Report a Usage Event
Now that a Customer
is subscribed, you can report their usage.
- When the customer consumes your product (e.g., makes an API call), send a
Usage Event
to Sulu. - Use the Create Usage Event API endpoint.
- Include an
idempotencyKey
(unique for each event to prevent duplicates), thecustomerId
, thetimestamp
of the event, and theproperties
detailing whichbillableMetricId
was consumed and thequantity
. - Sulu automatically bills the event against the customer’s
Subscription
and deducts the cost from theirWallet
in real-time. - Learn more about Usage Events.
Congratulations! You’ve walked through the core Sulu workflow. Explore the Core Concepts documentation for more in-depth information on each resource.