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

# Subscription Flow

> End-to-end subscription flow: create, renew, and cancel. Sequence diagrams and links to billing plans, recycling, and cancellation guides.

This page describes how subscriptions move through Revolv3: **create**, **renew** (recurring charges), and **cancel**.

## Flow Overview

| Phase      | What happens                                                                                                                                         |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Create** | You create a subscription with a billing plan and payment method; Revolv3 may charge the first period immediately or after a trial.                  |
| **Renew**  | On each billing date, Revolv3 creates an invoice and attempts to charge the stored payment method. Retries (“recycling”) apply if the attempt fails. |
| **Cancel** | You or the customer cancels; the subscription stops at the end of the current period or immediately, depending on your request.                      |

## Sequence: Create Subscription

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Revolv3 as Revolv3 API
  participant Processor as Payment processor

  App->>Revolv3: POST /subscriptions (plan, payment method, customer?)
  Revolv3->>Revolv3: Create subscription record
  Revolv3->>Processor: First charge if no trial
  Processor-->>Revolv3: Approve/decline
  Revolv3-->>App: 200 + subscription id, status
```

**When to use**: New recurring billing (SaaS, memberships, recurring services). See [Create a Subscription](/docs/core-concepts/subscription/create-subscription) for the full request body and [Billing Plans](/docs/core-concepts/subscription/billing-plans) for plan structure.

## Sequence: Renew (Recurring Charge)

```mermaid theme={null}
sequenceDiagram
  participant Revolv3 as Revolv3
  participant Processor as Payment processor
  participant App as Your app

  Revolv3->>Revolv3: Billing date reached
  Revolv3->>Revolv3: Create invoice for period
  Revolv3->>Processor: Charge stored payment method
  Processor-->>Revolv3: Approve/decline

  alt Success
    Revolv3->>Revolv3: Mark invoice paid, schedule next
  else Soft decline
    Revolv3->>Revolv3: Retry per recycling strategy
    Revolv3->>Processor: Retry (same or other method)
  else Hard decline
    Revolv3->>Revolv3: Stop retries, update subscription state
  end

  Revolv3-->>App: Webhook e.g. InvoicePaid / InvoiceFailed
```

Revolv3 handles scheduling and retries; you consume [webhooks](/docs/webhook-events/webhook) (e.g. `InvoicePaid`, `InvoiceFailed`) and/or poll subscription and invoice status. See [Subscription Status and Recycling](/docs/integration-flows/subscription-status-recycling) for retry behavior, soft vs hard decline, and multiple payment methods.

## Sequence: Cancel

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Revolv3 as Revolv3 API

  App->>Revolv3: POST /subscriptions/{id}/cancel (or PATCH)
  Revolv3->>Revolv3: Set status e.g. Pending Cancellation
  Revolv3-->>App: 200 + updated subscription

  Note over Revolv3: At end of billing period
  Revolv3->>Revolv3: Mark subscription Cancelled
```

Cancellation can be “at end of period” or “immediately,” depending on the API and your call. See [Canceling a Subscription](/docs/core-concepts/subscription/canceling-a-subscription) for options and behavior.

## Sample Create Request (summary)

* **Endpoint**: `POST /api/subscriptions` (use your environment base URL, e.g. `https://api-sandbox.revolv3.com` for sandbox).
* **Body**: Billing plan (or plan id), payment method(s), optional customer id, optional trial.
* **Response**: Subscription id, status, next billing date.

For full request/response examples, see [Create a Subscription](/docs/core-concepts/subscription/create-subscription).

## Where to Go Next

* [Create a Subscription](/docs/core-concepts/subscription/create-subscription) — Full create request and field reference
* [Subscription Billing Plans](/docs/core-concepts/subscription/billing-plans) — Plans, cycles, and value types
* [Subscription Status and Recycling](/docs/integration-flows/subscription-status-recycling) — Statuses, retries, and soft/hard declines
* [Canceling a Subscription](/docs/core-concepts/subscription/canceling-a-subscription) — How and when cancellation takes effect