> ## Documentation Index
> Fetch the complete documentation index at: https://staging-docs.crosspoint.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Recurring revenue on top of your products.

A **subscription** is the recurring relationship between a customer and one of your [products](https://staging-docs.crosspoint.finance/features/products.md). It's created automatically whenever a customer checks out a product that has a recurring price, and it keeps generating orders on each renewal until the customer or you decide to end it.

## How subscriptions work

1. **A customer subscribes.** When a customer completes a [checkout](https://staging-docs.crosspoint.finance/features/checkout/session.md) for a product that has a recurring price, Crosspoint creates a `subscription` and the first [order](https://staging-docs.crosspoint.finance/features/orders.md).
2. **Crosspoint renews it automatically.** At the end of each billing period, Crosspoint advances the subscription to the next cycle and creates a new order, then attempts to charge the customer's default payment method. If the payment fails, the subscription moves to `past_due` and Crosspoint runs an automated [payment recovery flow](https://staging-docs.crosspoint.finance/features/subscriptions/failed-payments.md).
3. **Benefits stay in sync.** As long as the subscription is active or trialing, the customer keeps access to all the [benefits](https://staging-docs.crosspoint.finance/features/benefits/introduction.md) attached to the product. When the subscription ends, those benefits are revoked.
4. **Customers self-serve from the portal.** The [Customer Portal](https://staging-docs.crosspoint.finance/features/customer-portal/introduction.md) lets customers update their payment method, download invoices, cancel, and — if you allow it — change plans or manage seats.

## Recurring pricing

Subscriptions are driven entirely by the way you price the underlying product. Recurring pricing is configured when you [create a product](https://staging-docs.crosspoint.finance/features/products.md#pricing):

* **Billing interval.** Daily, weekly, monthly or yearly.
* **Interval count.** The number of units per cycle. Setting this to `2` with a `month` interval gives you "every 2 months".
* **Pricing type.** Fixed, pay-what-you-want, or free. Free recurring products are still modeled as subscriptions — they just never generate a payment.
* **Currency.** A product can have prices in multiple currencies; the subscription locks in the currency used at checkout.

> [!NOTE]
>
> The billing interval and pricing type are fixed once a product is created. If
> you need a different interval (for example, a yearly plan next to a monthly
> one), create a separate product and show both at checkout. See
> [Products → Variants](https://staging-docs.crosspoint.finance/features/products.md#variants).

## Renewal reminders

For subscriptions on long billing cycles — six months or more — Crosspoint emails the customer **7 days before the renewal date** to let them know an upcoming charge is coming. This helps with regulations (like the EU's Consumer Rights Directive) that require advance notice on long-interval renewals, and avoids surprise charges that often end in chargebacks.

The threshold is six months, however it is expressed: yearly plans, monthly plans with an interval of 6 or more, weekly plans of 25 or more, and daily plans of 180 or more all get the reminder. Reminders are skipped for free subscriptions and for subscriptions already scheduled to cancel at period end.

You can turn renewal reminders off under [**Settings → Customer notifications**](https://app.crosspoint.finance/to/dashboard/settings) if you prefer to handle that communication yourself.

## Cancellation

A subscription can end in one of two ways, both available to you and your customers:

* **Cancel at period end** — the subscription keeps working until `current_period_end`, then transitions to `canceled`. You can reverse this (uncancel) until the end date is reached.
* **Revoke immediately** — the subscription moves to `canceled` right away and benefits are revoked. This is irreversible.

See [Managing subscriptions](https://staging-docs.crosspoint.finance/features/subscriptions/manage.md) for how to perform these actions and everything else merchants can do from the dashboard or the API.

## Creating subscriptions

There are two ways a subscription can come into existence:

* **Through checkout.** The default. Works for any paid recurring product. See [Checkout](https://staging-docs.crosspoint.finance/features/checkout/session.md).
* **Through the API, for free recurring products only.** You can call [Create Subscription](https://staging-docs.crosspoint.finance/api-reference/current/subscriptions/create-subscription.md) to subscribe an existing customer to a free product — no order, no email, no charge. This is useful for freemium onboarding flows where you want every signup to have a subscription tied to it from day one. Paid products always go through checkout so that Crosspoint can collect and validate the payment method.

## Next steps

> **[Managing subscriptions](https://staging-docs.crosspoint.finance/features/subscriptions/manage.md)**
>
> Change plans, seats, trials, billing dates, cancel or revoke — from the
> dashboard or the API.

> **[Proration](https://staging-docs.crosspoint.finance/features/subscriptions/proration.md)**
>
> Control how the price difference is handled when a subscription is upgraded
> or downgraded.

> **[Recovering failed payments](https://staging-docs.crosspoint.finance/features/subscriptions/failed-payments.md)**
>
> How Crosspoint retries failed renewals and when benefits are revoked.

> **[Subscriptions API](https://staging-docs.crosspoint.finance/api-reference/current/subscriptions/list-subscriptions.md)**
>
> List, create, update, and revoke subscriptions programmatically.

## FAQ

> **What's the difference between a subscription and a product?**
>
> A product is the thing you're selling — name, description, benefits,
> pricing. A subscription is one specific customer's ongoing relationship
> with that product.
>
> Crosspoint treats one-time purchases and recurring subscriptions as the same
> kind of object (both are "products"); the only difference is whether the
> price is recurring. See [Products](https://staging-docs.crosspoint.finance/features/products.md) for the full model.

> **Can a customer have more than one active subscription?**
>
> By default, no — a customer can only have one active subscription per
> organization at a time. This keeps the common case simple.
>
> If your product genuinely needs multiple parallel subscriptions per
> customer, you can opt in under **Organization Settings → Subscriptions**
> by toggling on **Allow multiple subscriptions**.

> **When is a customer actually charged?**
>
> At the end of each billing cycle. When a subscription renews, Crosspoint
> advances the cycle, creates a new order with tax and any applicable
> discount, and charges the customer's default payment method. If the
> charge fails the subscription moves to `past_due` and Crosspoint starts the
> [payment recovery flow](https://staging-docs.crosspoint.finance/features/subscriptions/failed-payments.md).
>
> The first charge happens at checkout (or when the [trial](https://staging-docs.crosspoint.finance/features/subscriptions/trials.md)
> ends, if one is configured).

> **Can I change the price of an existing subscription?**
>
> Not the amount on an existing subscription directly — subscriptions lock
> in the price they were created with so existing subscribers aren't
> surprised by changes.
>
> If you update the price on a product, the change applies only to **new**
> subscriptions. To move an existing subscriber to different pricing,
> either create a new product and run an [update to switch them to
> it](https://staging-docs.crosspoint.finance/features/subscriptions/manage.md#change-the-plan), or ask them to
> change plans themselves from the Customer Portal.

> **What happens to benefits when a subscription is canceled?**
>
> Benefits are tied to the subscription's status, not to the cancellation
> action itself:
>
> * If you **cancel at period end**, the customer keeps their benefits
>   until `current_period_end` — they paid for that period.
> * If you **revoke immediately**, the subscription becomes `canceled`
>   right away and all benefits are revoked.
> * If a renewal payment can't be recovered after Crosspoint's retries, the
>   subscription moves to `unpaid` and benefits are revoked the same way
>   as a revoke — subject to the optional
>   [grace period](https://staging-docs.crosspoint.finance/features/subscriptions/failed-payments.md#benefit-revocation-grace-period)
>   you can configure on your organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.