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

1. Sign Up

First, you need a Sulu Merchant account.

2

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

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 your merchantId.
  • Learn more about Products.
4

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”), the productId from the previous step, and set aggregation to SUM.
  • Learn more about Billable Metrics.
5

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 pricing model (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 the billingInterval (e.g., monthly), currency (e.g., USD), link it to your Product, and associate the Price you just created.
  • Learn more about Plans and Prices.
6

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 your merchantId.
  • This generates a URL to be used as a subscription link.
7

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 your Merchant to their Consumer) and a Subscription resource (linking the Customer to your Plan).
  • Learn more about Customers and Subscriptions.
8

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), the customerId, the timestamp of the event, and the properties detailing which billableMetricId was consumed and the quantity.
  • Sulu automatically bills the event against the customer’s Subscription and deducts the cost from their Wallet 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.