Core Concepts

This reference covers the core terminology in Salable. From products and plans to entitlements and grantee groups, each concept is explained to help you understand how the pieces fit together and get up and running quickly.

Foundational Concepts

Test Mode vs Live Mode

Salable operates in two environments. In Test Mode, you use separate test API keys and Stripe's test cards for checkout. No real money changes hands, so it's safe for development and integration testing. When you're ready, switch to Live Mode, which uses separate live API keys and processes real payments. Live Mode requires you to complete Stripe's onboarding process before you can accept payments in production.

Pricing Hierarchy

Product

A Product is the top-level container representing what you're selling, whether that's a SaaS application or a service offering. Each Product contains one or more Plans and includes a name, description, and settings that control how your pricing works.

Plan

A Plan is a bundle of offerings, services, feature sets, or tiers at the payment model you define. It brings together the pricing components for a specific Subscription option: your Basic tier, Pro tier, an Analytics Add-on, or any other offering you want to sell.

Each Plan belongs to exactly one Product and can contain one or more Line Items with different pricing models. You can mix flat fees, per-seat charges, usage-based pricing, and one-time fees within a single Plan. A base Subscription fee plus per-user pricing plus metered API calls? Add those Line Items to your Plan.

Plans are the purchasable entities in your app. When a customer subscribes, they're subscribing to a Plan. Line items within a Plan can have different billing intervals and frequencies. When a customer adds a Plan to their cart, they specify an interval (like "month") and a value (like "1" for monthly or "3" for quarterly). If a currency is provided, Salable cherry-picks only the Line Items that match the requested interval, value, and currency combination. You can design sophisticated pricing models without creating dozens of separate Plans for each variation.

Line Item

Line items are the individual pricing components that make up a Plan. You can combine multiple Line Items within a single Plan to create varied pricing models. Each Line Item can have different billing intervals and values.

There are four types of Line Items you can use:

Flat Rate charges a fixed amount every billing cycle, regardless of usage. For example, a $29/month platform fee that every subscriber pays.

Per-Seat pricing multiplies the charge by the number of users, licenses, or seats. You might charge $10 per user per month, and you can set minimum and maximum quantities. Per-seat Line Items also support tiered pricing, so you can offer volume discounts as teams grow.

Metered pricing is usage-based. You bill customers based on what they use during the billing period, such as $0.01 per API call or $0.05 per GB of storage. These Line Items use slugs for tracking usage across billing periods.

One-Time charges happen once and never recur. For example, a $99 onboarding fee billed only when someone first subscribes.

Price

A Price represents the actual monetary value and configuration for a Line Item in a specific currency. Each Line Item can have Prices in multiple currencies, and each Price includes the amount, currency, and billing scheme details.

You can modify Prices at any time. Existing Subscriptions continue using the Price version they started with and won't update to new pricing unless you explicitly move them. You can grandfather existing customers on old pricing or migrate them to your new rates.

Interval

The interval defines the billing frequency unit: day, week, month, or year. Combined with an interval value (a multiplier), you can create any billing frequency. An interval of "month" with a value of 1 means monthly billing. Change that value to 3 for quarterly billing, or use "week" with a value of 2 for biweekly billing.

When customers add a Plan to their cart, they specify the interval and optionally the interval value (which defaults to 1 if not provided). Salable then cherry-picks only the Line Items from that Plan that match the requested combination. Intervals also affect how proration is calculated when Subscription changes occur mid-cycle.

Currency

Currency represents the monetary unit for pricing and billing. How currency works depends on whether you specify it when creating a cart.

When you provide a currency: Salable cherry-picks only the Line Items from the Plan that have Prices in that specific currency and interval combination. You can create region-specific pricing models, such as different Line Items or pricing structures for USD vs EUR customers.

When you don't provide a currency (geolocation mode): Stripe detects the customer's location and displays the appropriate currency. Every Line Item in the Plan must have the same default currency, and each Line Item should have Prices for every currency you want to support. If the defaults don't match, the checkout link will error. If a Line Item is missing a Price for a specific currency, that Line Item falls back to its default currency. In this mode, all Line Items are used—no cherry-picking occurs.

Access Control

Owner

An owner is an identifier used to scope Subscriptions, carts, and usage records in Salable. Typically a user ID for individual Subscriptions, or a team or organization ID for shared Subscriptions where multiple people need access to the same Subscription data.

The owner ID should be an identifier accessible to anyone who needs to view Subscription data or increment usage meters. In a team Subscription, all team members who might record usage would share the same owner ID (like a team or organization ID). Your application's RBAC determines who can modify or cancel Subscriptions, and your business logic determines who is financially responsible. The owner ID is the scoping mechanism for organizing Subscription data in Salable.

You must provide an owner when creating carts and Subscriptions, though you can update it later. This is useful when converting anonymous sessions to authenticated user IDs after signup. A single owner can have multiple Subscriptions and grantee groups, and you can filter entitlement checks by owner to scope results.

Grantee

A grantee is any entity that receives access to features or entitlements through a Subscription. Grantees are identified by unique IDs from your system (a granteeId string you provide). These can represent users, teams, projects, boards, workspaces, or any other entity in your application that needs feature access.

Grantees can belong to one or more grantee groups, and they receive entitlements through these group memberships. You can optionally provide a name for display purposes, making it easier to manage your grantees in the dashboard. For example, you might have a user with ID user_abc123 or a project with ID project_xyz789. Both would be grantees in Salable.

Group

A group is a collection of grantees that share access to features from a Subscription. Groups are how you implement team or organization Subscriptions in Salable. Each group has an owner (usually an organization or team lead) and contains zero or more grantees.

When you create a Subscription, you assign groups to Subscription items to grant access to all the grantees in that group. You can create groups before checkout (useful for pre-onboarding teams) or during the checkout process. A single owner can have multiple groups, which is perfect for organizations with different departments or teams.

Once you've created a group for a team or organization, you can reuse it for future add-ons and additional Subscriptions. You don't need to recreate the group structure. Assign the existing group to new Plans as the team purchases more features.

A single grantee can belong to multiple groups and gains cumulative access from all their memberships. This handles scenarios like contractors working with multiple clients or employees on cross-functional teams.

Seat

A seat is a license or slot for a grantee within a per-seat Line Item. The seat count is the quantity on your per-seat Line Item and must be greater than or equal to the number of grantees in the assigned group.

You can define minimum and maximum limits for seats on your Line Item to control how teams scale. Seat count and grantee count are managed independently, so you can have headroom to allow for growth without an immediate upgrade.

If a grantee belongs to multiple groups with different Plans that have per-seat pricing, the lowest seat limit across all those Plans applies. This prevents under-provisioning of seats and ensures consistent access.

Entitlement

An entitlement is a named permission or feature that you can check to control access in your application. Entitlements are named using lowercase snake_case (like advanced_analytics or export_pdf) and are attached to Plans rather than individual Line Items.

When a Subscription is created with a Plan, the entitlements from that Plan are inherited by the Subscription. To check access, you use the grantee ID. The chain of relationships: a grantee is in a group, the group is assigned to a Subscription, the Subscription contains a Plan with an entitlement, and so the grantee has access to that entitlement.

Tier Tags and Tier Sets

Tier tags are string "tags" on Plans that restrict Owners from purchasing multiple Plans that share the same tag. Plans sharing a tier tag belong to the same tier set, and an Owner can only subscribe to one Plan in a tier set at a time. Tier tags and tier sets make your Plans mutually exclusive purchases.

What tier tags and tier sets prevent:

  • Adding multiple Plans of one tier set to the same cart
  • Adding Plans to a cart that belong to the same tier set as a Plan the cart's owner already subscribes to

Note that owners can still replace a Plan in a Subscription with another Plan belonging to the same Tier Set as they will still only be subscribed to one member of the tier set.

You can add tier tags to your Plan upon Plan creation or when editing an existing Plan.

Transaction Concepts

Cart

A cart is a temporary container for Plans that an owner intends to purchase. It converts into a Subscription after successful checkout. When you add the first item to a cart, you specify a billing interval. You can also optionally provide a currency when creating the cart.

If you provide a currency, Salable cherry-picks Line Items from added Plans that match both the interval and currency combination. If you don't provide a currency, Salable only matches by interval and uses Stripe's geolocation to detect the appropriate currency at checkout.

You can assign grantee groups to cart items before checkout, which is useful for pre-configuring team access. The owner can be updated later, for example converting a session ID to a user ID after signup. Salable supports multiple active carts per owner, so customers can have different purchasing sessions going simultaneously.

Cart Item

A cart item represents a single Plan within a cart. Each cart item references a specific Plan and includes a quantity (which matters for per-seat Line Items). It can optionally have a grantee group ID assigned to it.

Checkout

Checkout converts your cart into a paid Subscription. When you're ready to complete a purchase, you generate a Stripe Checkout session URL that redirects your customer to Stripe's hosted payment page.

You can configure default checkout settings at the Product level, like success and cancel URLs. If you've set these defaults in your Product settings, Salable uses them automatically. If you haven't provided Product defaults, include the required configuration parameters when generating the checkout link.

Once payment succeeds, Salable creates the Subscription and any necessary grantee groups. All grantees in the assigned groups immediately gain access to the entitlements attached to their Plans. Checkout works for both authenticated users and anonymous sessions, which is useful for guest checkout flows where you assign the owner ID after the customer signs up.

Subscription

A Subscription is an active, recurring billing relationship between an owner and one or more Plans. Created after successful checkout, each Subscription contains one or more Subscription items (which are Plans) and renews based on the billing interval.

You can modify Subscriptions after creation by adding or removing Plans, changing quantities, or updating other settings. To end a Subscription, cancel it immediately (with proration handling for any unused time) or schedule the cancellation for the end of the current billing period.

Subscription Item

A Subscription item represents a single Plan within a Subscription. Each item links to the Plan and its Line Items, includes quantities for per-seat pricing, and may have a grantee group assigned to it. When a group is assigned, all grantees in that group receive the entitlements from the Plan. You can individually modify or remove Subscription items without affecting the entire Subscription.

Usage Tracking

Metered Line Item

Metered Line Items let you charge customers based on what they actually use. Throughout the billing period, you record usage via API calls using a unique slug identifier. At the end of each period, Salable automatically calculates and bills the charges.

You can use the same slug across multiple Plans, keeping your code simple. When recording usage, you increment against the slug name, like "photo_generation", regardless of which Plan the user is on. Salable figures out their Plan and bills at the appropriate rate. One Plan might charge $0.10 per photo while another charges $0.05 per photo, but you increment the same slug.

When customers change Plans, any outstanding metered usage is invoiced immediately, and new counters start fresh at zero. Plans can have multiple metered Line Items, so you could track photos, videos, and API calls all within the same Plan. Metered Line Items support per-unit, tiered, and volume pricing schemes.

Meter Slug

A meter slug is the unique identifier used to track usage for metered Line Items. It follows lowercase snake_case format, like api_calls or storage_gb. When you record usage via the API, you reference this meter slug to increment the counter.

You can use the same meter slug across multiple Plans. This keeps one usage counter per owner per meter slug, preventing double-billing. If you have "photo generation" on both Basic and Pro Plans, use the same meter slug (photo_generations) on both. Your code increments one counter, but billing happens at different rates depending on which Plan the customer has.

Usage Record

A usage record tracks metered usage for an owner during a billing period. When you record usage for the first time in a period, Salable creates a usage record. Throughout the period, this record tracks cumulative usage as you continue to increment the counter.

Usage records move through states during their lifecycle. While usage is tracked during the billing period, the record has current status. Once the next interval starts, the previous record transitions to recorded status. When the Subscription ends, the current record becomes final and the accumulated usage is billed. There's one usage record per Owner per Meter slug per period, preventing confusion about what's been billed.

Billing Concepts

Proration

Proration handles financial adjustments when Subscriptions change mid-cycle. There are three approaches:

Charge on Next Invoice is the most common approach. It refunds unused time from the old Plan and starts billing for the new Plan at the next cycle, with minimal immediate financial impact.

Charge Immediately refunds unused time from the old Plan and bills for the new Plan right away, creating an instant invoice. Use this when you want to settle everything at once rather than waiting for the next billing cycle.

No Refund, Charge Next switches to the new Plan immediately but doesn't refund unused time. The new Plan starts billing at the next cycle. The customer keeps the remaining time on their old Plan while moving to the new one.

Billing Cycle

The billing cycle is the time period between recurring charges for a Subscription. Its length is determined by the Plan's interval: monthly, yearly, or whatever interval you've configured. The cycle starts on the Subscription creation date (called the billing anchor), and usage for metered items resets at the start of each cycle. All Plans within a Subscription share the same billing cycle.

Invoice

An invoice is the document showing all charges for a billing period. Salable generates invoices at the end of each cycle, including flat fees, per-seat charges, and metered usage in one place. You can preview upcoming invoices before the period ends. Once generated, invoices are downloadable as PDFs. Paid invoices are immutable; they can't be changed after payment.

Billing Anchor

The billing anchor is the date a Subscription was created, and it determines all future billing dates. Salable uses the billing anchor to set the recurring charge date and calculate proration when Subscriptions change. The billing anchor stays consistent across Plan changes. If you create a Subscription on January 15th, it will bill on the 15th of each month going forward.

Operational Concepts

Cancellation

Cancellation terminates a Subscription, and you have two options for how this happens.

Immediate cancellation ends the Subscription right away. Metered usage is finalized and billed, access is revoked, and a final invoice may be generated.

End of period cancellation marks the Subscription for cancellation but lets it continue until the current billing period ends. You can reverse this before the period ends. The customer keeps access until the period they paid for expires.

Sync to Latest Price

When you update your pricing, you might want to move existing Subscriptions to the new Prices. Syncing to the latest Price does this. You can grandfather existing customers by not syncing them (they stay on old pricing) or migrate them to the new pricing by syncing. When you sync, proration rules apply during the transition to handle mid-cycle adjustments.

Webhook

Webhooks are HTTP callbacks that Salable sends to your application when events occur. They notify your app of Subscription changes, usage updates, and payment events. Each webhook includes the event type and full payload, and you must verify the signature using HMAC to ensure authenticity.

Salable will retry failed webhooks up to 10 times with exponential backoff, and each attempt has a 15-second timeout. Common events include Subscription created, updated, and cancelled; usage recorded and finalized; receipt created; and owner updates.

For a complete guide to configuring webhook destinations, implementing handlers, and monitoring deliveries, see the Webhooks guide.

Special Patterns

Anonymous to Authenticated Conversion

This pattern lets you start a cart with a session ID and update it to a user ID after signup. You create a cart with an owner like "session_abc123", let the user add Plans to their cart, and redirect them to checkout. After payment completes, the user signs up, and you update the owner to their actual user ID like "user_xyz789". This enables guest checkout flows that convert to authenticated accounts.

Pre-Purchase Team Setup

You can add grantees to a group before completing checkout. This lets you invite team members before subscribing, show who will get access, and validate that seat counts match team size. Create a grantee group, add grantees to it, create a cart item with the group assigned, set the quantity to match the group size (or higher for growth room), and proceed to checkout. Once payment succeeds, everyone in the group immediately has access.

Cross-Plan Metering

This pattern uses the same meter slug across multiple Plans to maintain a single usage counter. Your Basic Plan might charge $0.10 per photo generation using the slug photo_generations, while your Pro Plan charges $0.05 per photo generation with the same slug. You increment photo_generations once in your code, but Salable bills at the rate of whichever Plan the customer has. Simple implementation, flexible pricing across tiers.

Quick Reference

Hierarchy Overview

Organization
  └─ Product
      └─ Plan (specific interval + currency)
          └─ Line Item (flat/seat/metered/one-time)
              └─ Price (amount in currency)

Access Flow

Subscription Item → Assigned Grantee Group → Contains Grantees
                  → Plan → Entitlements → Grantees Have Access

Checkout Flow

Cart → Cart Items (Plans + Groups) → Checkout → Payment
  → Subscription Created → Grantee Groups Assigned → Access Granted

Billing Cycle

Start Date → Usage Recording → End of Period → Finalize Usage
  → Generate Invoice → Process Payment → New Period Begins

Next Steps

Now that you understand the core concepts, explore these guides to implement specific patterns:

  • Getting Started Guide: Build your first Product and Plan
  • Understanding Entitlements: Implement feature gating
  • Grantee Groups: Set up team Subscriptions
  • Webhooks: Configure real-time event notifications
  • Caching Strategies: Optimize entitlement checks in production