Now that you have defined your Product and how to price it using Plans and Prices, the next step is to connect your offering with the end-users who will consume it. This is managed through Customers and Subscriptions.

​
Customers

A Customer resource represents the relationship between your Merchant Organization and a Consumer Organization that uses your Product.

  • Linkage: It connects a specific Consumer (who holds a Wallet and pays) to your Merchant account.
  • Context: When you report Usage Events, you report them against a Customer ID, allowing Sulu to identify the correct Consumer Wallet to bill and the correct Merchant Wallet to credit.
  • Creation: Customer resources are typically created automatically as part of the Subscription Flow.

​
Subscriptions

A Subscription formalizes the agreement between a Customer and a specific Plan (and by inheritance, a Product).

  • Agreement: It signifies that the Customer (representing the Consumer Organization) has agreed to pay for the Product according to the rates defined in the Plan.
  • Scope: A Subscription links one Customer to one Plan.
  • Billing Basis: Active Subscriptions are necessary for Sulu to correctly process Usage Events and apply the right Prices.
  • Creation: Like Customers, Subscriptions are usually created automatically during the Subscription Flow.

Essentially:

  1. A Consumer wants to use your Product.
  2. You establish a Customer relationship between your Merchant and their Consumer.
  3. The Customer agrees to a specific Plan by creating a Subscription.
  4. The Subscription allows the Merchant to report Usage Events for that Customer, which are then billed according to the Plan’s Prices against the Consumer’s Wallet.

​
The Subscription Flow

Sulu provides a managed checkout flow to simplify the process of creating Customers and Subscriptions.

1

1. Generate Authorization Link

To initiate the flow, you need a unique URL associated with a specific Plan.

  • Method: Use the Create Authorization Session API endpoint (POST v0/customers/authorization) or the “Generate Authorization Link” button on the Plan details page in the Sulu Merchant Dashboard.
  • Input: You’ll need the planId and your merchantId.
  • Output: Sulu generates a unique URL (e.g., https://platform.sulu.sh/authorize/...) representing a pending authorization session.
2

2. Redirect Consumer to Link

Provide the generated authorization URL to the end-user who wants to subscribe.

3

3. Sulu Checkout

The user clicks the link and is taken to Sulu’s secure, hosted checkout page.

  • Existing Sulu User: If the user is already logged into a Sulu Consumer account, they will be prompted to confirm the subscription to the specified Plan.
  • New Sulu User: If the user is not logged in or doesn’t have a Sulu account, they will be guided through creating a new Sulu Consumer Organization and User account, and adding a payment method to top up their Wallet before confirming the subscription.
  • Merchant Branding: The checkout page displays the Product and Plan details (name, description) you defined.
4

4. Resource Creation

Upon successful completion of the checkout flow by the user:

  • Sulu automatically creates a Customer resource linking your Merchant Organization to the Consumer Organization (if one didn’t already exist for this Consumer).
  • Sulu automatically creates a Subscription resource linking the Customer to the chosen Plan.
  • The subscription status becomes active.
5

5. Ready for Usage

The Customer is now successfully subscribed to your Plan, and you can begin reporting Usage Events against their customerId.

​
Entitlements

An Entitlement represents a Customer’s right to consume Billable Metrics associated with their active Subscription, provided they have sufficient funds in their Wallet.

Sulu allows Merchants to check these entitlements in real-time, which is crucial for Pay-As-You-Go (PAYG) models where access should be granted before consumption and billing.

​
Checking Active Entitlements

To verify if a Customer is currently entitled to use resources associated with certain Billable Metrics:

  • Use the Get Active Entitlements API endpoint (GET v0/entitlements/activeEntitlements).
  • Provide the customerId.
  • Response: The endpoint returns a list of ActiveEntitlement objects. Each object indicates an active Subscription and lists the billableMetrics the customer is currently permitted to consume under that Subscription (based on the subscription being active and the associated Consumer Wallet having a positive balance).

If the response list is empty, or if the specific billableMetricId you are checking is not present in any of the returned ActiveEntitlement objects, the Customer is not entitled to consume that resource at this moment.

​
Example Flow: API Gateway Entitlement Check

Imagine you’re building an API gateway for your monetized API:

  1. Request Received: A user sends a request to your gateway, including their API key.
  2. Authentication & Customer Lookup: Your gateway authenticates the key and looks up the associated Sulu customerId.
  3. Check Sulu Entitlements: Your gateway calls Sulu’s GET v0/entitlements/activeEntitlements endpoint with the customerId.
  4. Verification: The gateway checks the response:
    • Does the response contain an ActiveEntitlement object?
    • Does that object’s billableMetrics list include the ID for the metric being consumed by this API call (e.g., bm_api_call)?
  5. Decision:
    • Entitled: If yes to both, the gateway forwards the request to your backend service. Upon successful processing by the backend, the gateway reports a Usage Event to Sulu for the consumed billableMetricId and quantity (usually 1 for a per-call metric).
    • Not Entitled: If no, the gateway rejects the request immediately (e.g., with an HTTP 402 Payment Required or 403 Forbidden status code), preventing usage and potential billing issues.

This real-time check ensures users only consume resources they are actively subscribed to and have the balance to pay for.

With Customers subscribed and Entitlements understood, the final piece is reporting consumption via Usage Events.