Subscriptions & Billing

Salable manages the full subscription lifecycle, ensuring entitlements stay in sync as customers upgrade, downgrade, or cancel. This guide walks you through how subscriptions work and the control you have from checkout to cancellation.

Understanding Subscriptions

How Subscriptions Are Created

When a customer completes checkout, Stripe notifies Salable of the successful payment. Salable then creates a Subscription from the Plans purchased in the Cart.

The Subscription inherits properties from the Cart (currency, billing interval, Grantee Group assignments, and any metadata) and belongs to the Owner who made the purchase. If the Cart included Grantee Group assignments, Salable links these Groups to the appropriate Subscription Items, giving team members immediate access to Entitlements.

Subscription Status

Subscriptions move through several states during their lifecycle:

  • active: in good standing with successful payments; full Entitlement access
  • past_due: payment failed; Stripe is retrying via Smart Retries. You can configure whether customers retain Entitlement access during this period
  • cancelled: terminated, will not renew. Immediate cancellation revokes access right away. End-of-period cancellation maintains access until the billing cycle ends
  • trialling: trial period with full access but no charge yet. Transitions to active when the trial ends, unless cancelled
  • incomplete: initial payment failed. Stripe retries briefly before moving to cancelled

Subscription Items

Subscriptions contain Subscription Items, one for each Plan purchased. A customer buying your main Product plus add-ons has multiple Subscription Items, each tracked separately.

Within each Subscription Item, individual Line Items maintain their own quantities. A per-seat Line Item tracks purchased seats, a consultancy Line Item might track purchased hours, and a metered Line Item tracks usage records.

Subscription Items inherit Entitlements from their Plan and can be associated with Grantee Groups. If a customer assigned a team Plan to a Grantee Group during checkout, that association persists, ensuring all group members receive the appropriate Entitlements.

Managing Subscription Items

You can add, remove, or replace Plans on a Subscription in a single request. You specify the proration behaviour to control billing. All actions in the request are processed together to calculate a single billing adjustment. Plans must match the Subscription's currency and billing interval.

  • Add adds a new Plan to the Subscription.
  • Remove removes an existing Plan from the Subscription. You cannot remove the last one.
  • Replace swaps one Plan for another. Useful for upgrades or downgrades.

Tier Tags

If your Plans use Tier Tags, you can replace one Plan with another from the same tier set. For example, if a customer is on the "Basic" Plan, it can be replaced with the "Pro" Plan even if they share the same tier tag. This is how to handle upgrades/downgrades within a tier set.

You cannot add a Plan that shares a tier tag with a Plan already on the Subscription. If you need to move a customer to a different Plan within the same tier set, use the replace action rather than adding the new Plan separately.

Quantity Management

After a customer purchases a Subscription, you can adjust the quantity of each Line Item on their Plan. You specify the proration behaviour to control billing. The minimum and maximum limits configured on the Line Item are enforced.

For per-seat Line Items, the quantity determines how many seats are available for the associated Grantee Group. You can increase the quantity at any time to add seats, but you cannot decrease it below the current number of group members. You must remove members from the group first.

Proration

When a customer upgrades, downgrades, adds Plans, or changes quantities between billing dates, the amount owed for the partial period is prorated based on the time remaining until the next billing anchor.

For example, if a customer with a $100/month Plan upgrades to a $150/month Plan on day 10 of a 30-day cycle, the prorated charge is approximately $33.33 (the $50 difference × 20/30 remaining days). At the next billing date, the full $150 is charged. This applies to seat additions, plan changes, and add-ons. All changes synchronise to the single billing anchor, so customers receive one invoice per period.

Proration Behaviours

Salable supports these proration behaviours:

  • create_prorations calculates the difference between the old and new Subscription value immediately and generates an invoice or credit. If a customer upgrades from a $50/month Plan to a $100/month Plan halfway through the month, they are charged approximately $25 (the prorated difference for the remaining half-month). At their next billing date, they pay the full $100.

  • always_invoice creates an invoice immediately for any proration amount, even if the change results in a credit. This generates invoices for every change (useful for audit purposes), though credits still apply to the customer's balance for future billing.

  • none turns off proration entirely. The customer continues paying the old rate until their next billing date, then starts paying the new rate. Simpler for customers to understand and avoids mid-cycle charges, but you may be giving away upgraded access for free during the transition period. Works well for downgrades where you want customers to keep premium features until the end of their paid period.

Choosing the Right Proration Strategy

The proration behaviour you specify depends on the update:

  • Upgrades: create_prorations works well. Customers expect to pay more for better features, and immediate billing compensates you for the upgrade.
  • Downgrades: none lets customers keep premium features until the end of their paid period before switching to the lower price.
  • Add-ons: create_prorations makes sense because the customer is actively requesting a feature and expects to pay for it. The immediate charge confirms access.
  • Multiple changes: create_prorations calculates the net difference, resulting in a small charge, a small credit, or nearly zero change.

Cancellation Management

End-of-Period Cancellation

Schedule a Subscription to cancel at the end of the current billing period by disabling auto-renewal. The Subscription remains active until the period ends, then terminates. No refund is issued. The customer receives the full value of what they paid.

After scheduling, the Subscription includes cancelAtPeriodEnd: true. Use this to show customers when access ends. To reverse a scheduled cancellation, re-enable auto-renew.

Immediate Cancellation

Immediate cancellation terminates the Subscription and revokes Entitlements. Salable issues a prorated refund for the unused portion of the billing period.

Use immediate cancellation for terms of service violations, account deletions, or when switching billing intervals.

Billing Cycles and Intervals

How Billing Anchors Work

Every Subscription has a billing anchor date: the day of the month when the Subscription renews and the next billing period begins. Salable sets this anchor when the Subscription is created, based on the checkout completion date.

If a customer subscribes on January 15th with monthly billing, their anchor is the 15th. They are billed on the 15th of each month for the upcoming period.

Customers know when charges will occur each month. For annual Subscriptions, the anchor works the same way, spanning years instead of months.

Month-End Edge Cases

Billing anchors on the 29th, 30th, or 31st require special handling because month lengths vary.

Stripe and Salable handle this by billing on the last available day of shorter months. A January 31st anchor bills on February 28th (or 29th in leap years), then March 31st, April 30th, May 31st, and so on. The anchor remains conceptually tied to the 31st, but actual billing happens on the last available day of each month.

Customers never miss a billing date, and the cycle stays as close to monthly as possible. Billing periods do vary slightly in length: a period ending on February 28th is shorter than one ending on March 31st.

Invoice Management

Stripe generates an invoice for every Subscription billing event. Each invoice includes Line Items showing what was billed, payment status, total amount, and an invoicePdf URL for PDF receipts.

For metered Line Items, invoices show usage charges with quantity consumed, per-unit price, and total (eg "API Calls: 1,450 × $0.10 = $145.00").

You can also preview what customers will be charged on their next billing date before it is finalised. The preview includes recurring charges, pending metered usage, account credits, and the final amount.

Price Synchronisation

Price Changes

When you update a price in Salable, existing Subscriptions continue billing at the old price by default. Existing customers are grandfathered in.

Note You can configure the billing model to apply updated prices to all customers.

Syncing to New Prices

The Price Synchronisation endpoint migrates a Subscription to the latest pricing. It updates the Subscription Items to reference the current prices for their Plans.

The proration behaviour determines when the new pricing takes effect. Using none means the Subscription continues at the old price through the current billing period, then switches to the new price at the next renewal. Using create_prorations means the price change takes effect immediately with appropriate prorated charges or credits.

Communicating Price Changes

When changing prices:

  • Announce at least 30 days in advance
  • Explain the reasons and any value changes
  • State the dates when the change takes effect for existing customers
  • Consider offering options to lock in current pricing

End-of-period price synchronisation respects the customer's current billing cycle and gives them time to adjust.

Important Price notification requirements vary by jurisdiction. Some require 30 days' notice, others 60 days or more. Research legal requirements for your customer locations or consult legal counsel before changing prices.

Payment Failures and Dunning

Past Due Status

If a scheduled Subscription payment fails, the Subscription enters a past_due state. Stripe attempts Smart Retries, adapting the retry schedule based on failure reason and historical patterns.

During this period, you can control whether customers retain Entitlement access. Maintaining access reduces frustration if the failure is temporary, but it means providing service without current payment.

3D Secure and Strong Customer Authentication

In the European Economic Area, Strong Customer Authentication (SCA) regulations require additional verification for certain transactions, commonly through 3D Secure (3DS). Recurring Subscription payments benefit from exemptions, but several scenarios trigger authentication:

  • Price increases beyond certain thresholds (often 30 EUR or equivalent)
  • Initial Subscription payments (handled automatically by Stripe checkout)
  • Payment method changes
  • Large mid-cycle charges from upgrades or expensive add-ons

When a payment fails due to SCA, the customer must authenticate. Updating their card will not resolve the issue. Notify customers that verification is required, and provide Stripe's billing portal link to complete the authentication challenge.

For price increases or mid-cycle modifications that may trigger authentication, tell customers in advance that their bank may require verification. Consider offering the option to delay changes until the next billing date to avoid mid-cycle triggers.

Note SCA requirements are mandatory in the European Economic Area. Other regions may have different requirements or none at all. Consider your customer distribution when planning communication strategies.

Customer Communication During Dunning

Stripe handles payment retries, but you are responsible for customer communication. When a payment fails, notify the customer through email or in-app messages. Explain the failure, provide a link to update their payment method, and tell them how much time they have before access is affected.

If retries continue to fail, escalate urgency. After several days, make it clear that cancellation is imminent.

If a payment succeeds after a retry, confirm the charge was successful so customers know the issue is resolved.

Stripe's hosted billing portal is the simplest way for customers to update their payment method. You can generate portal links that take customers to a secure page where they update cards, view billing history, and manage their Subscription. Include these portal links in your payment failure communications.

Salable Only Subscriptions

Salable also offers the ability to generate Subscriptions without having to go through the standard checkout process. Aptly named Salable Only Subscriptions, these Subscriptions can be generated directly from the Subscriptions page and skip the Stripe checkout process that standard Subscriptions go through.

A Salable Only Subscription is functionally identical to a normal Subscription. It carries Entitlements, supports Grantee Groups, and participates in the same Tier Tag constraints that prevent conflicting Plans on a single Subscription. The only meaningful difference is that no invoice is generated and no payment is collected through a checkout link. From your application's perspective, when checking Entitlements via the API, a Salable Only Subscription is indistinguishable from one created through checkout.

When to Use Salable Only Subscriptions

Salable Only Subscriptions are the right tool when you want to generate Subscriptions without having to go through the standard checkout process. A few common scenarios illustrate how this plays out in practice.

Internal team access. Your engineering, support, and product teams need to use your application to do their jobs. Putting them through a checkout flow is unnecessary friction, and charging your own employees doesn't make sense. A Salable Only Subscription gives them full access under the same Entitlement system your paying customers use, which also means their experience accurately reflects what customers see.

Partners and integrations. Technology partners, agency partners, or integration developers often need access to build on top of your platform. The value exchange isn't monetary—it's the ecosystem growth they enable. A Salable Only Subscription establishes the access relationship formally, with a proper Subscription record and Entitlements, without requiring a billing arrangement.

Trials and demos you control. Some customer journeys benefit from access that you provision directly rather than through self-serve checkout. A sales-led trial might start with you granting the prospect a time-limited Subscription. A demo environment for a prospective enterprise customer can be set up in seconds without needing the customer to enter payment details.

Compensation and goodwill. When something goes wrong—extended downtime, a billing error, a support failure—granting a period of free access is a meaningful gesture. A Salable Only Subscription lets you do this precisely, for exactly the Plans and duration you intend, without manual workarounds.

Early access and beta programs. Beta testers and early access users are providing feedback and validation rather than paying for a finished product. A Salable Only Subscription with an expiry date matching your beta window gives them proper access while keeping your customer records clean and your Entitlement checks consistent with production.

Manual invoicing. There may be cases where you want to collect payment manually outside of Salable such as having customers in regions where card payments aren't practical, or deals negotiated with custom payment terms. When you collect outside of Salable, you still need to grant access to your application. A Salable Only Subscription lets you provision access immediately when payment is confirmed, without going through the Salable checkout process. This can also be handy for enterprise customers who you would like to manually invoice via purchase order and give immediate access to your application while awaiting funds.

Creating a Salable Only Subscription

Salable Only Subscriptions are created from the Subscriptions page in your dashboard by clicking Create Subscription. You will need to add:

  • 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 that's just a string you provide. These can represent users, teams, projects, boards, workspaces, or any other entity in your application that needs access to features.
  • Owner — An owner is an identifier used to scope subscriptions and usage records in Salable. This is 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. If the Owner doesn't exist yet in your account, it will be created automatically.
  • Grantee — optionally, the specific user or Group who receives the Entitlements. If you're granting team-level access, you'd specify a Grantee Group here.
  • Lifecycle Options — because there's no Stripe billing cycle to inherit, you define the life cycle of the Subscription directly.

Lifecycle Options

Salable Only Subscriptions give you precise control over how long access lasts. When creating a Subscription, you choose one of three approaches.

Interval-based billing works like a standard Subscription. You set an interval (day, week, month, or year) and an interval count, and the Subscription renews accordingly. Unlike a paid Subscription, there's no payment collected at each renewal, but the Subscription remains active and Entitlements remain valid across renewal periods. For example, if you want to create a Subscription that cycles every month you would set the interval to "month" and the interval count to "1", for subscriptions that cycle quarterly you would set the interval to "month" and the interval count to "3", so on and so forth. You can also enable Cancel at Period End to schedule the Subscription to terminate when the current period completes, without renewing.

Expiry date lets you set a fixed date when the Subscription terminates automatically. This is the right option for time-limited trials, beta access, or compensation periods where you want access to end on a specific day regardless of any other logic. You specify the date when creating the Subscription; no billing interval is needed.

Perpetual creates a Subscription that never expires and never renews—it remains active indefinitely until you explicitly cancel it. This is useful for permanent partner access, internal tooling, or any scenario where access should continue without any time constraint.

Note that selecting between an expiry date and being perpetual are mutually exclusive, subscriptions can either expire at the expiry date specified or continue perpetually.

Metered Plans and Salable Only Subscriptions

Interval and interval count must be specified when creating a Salable Only Subscription. This is necessary because metered billing aggregates usage over a billing period. At the end of the period the final usage count is recorded and a new record is created for the next period.

Everything else about metered billing works the same way. You record usage through the API, Salable keeps track of the consumption for each cycle on the Subscription.

Note that the same meter restrictions also apply to Salable Only Subscriptions, an Owner cannot subscribe to a metered Plan if they're already subscribed to the associated meter elsewhere.

What Salable Only Subscriptions Don't Include

Salable Only Subscriptions do not generate invoices, receipts, or any billing records. Because there's no Stripe involvement, there are no payment method requirements, no dunning retries, no proration calculations, and no SCA challenges. Price synchronisation doesn't apply since there's no price being charged.

If you later want to transition a customer from a Salable Only Subscription to a paid Subscription, you would cancel the Salable Only Subscription and direct them through the standard checkout flow to create a new paid Subscription.