> ## Documentation Index > Fetch the complete documentation index at: https://docs.ecrypt.com/llms.txt > Use this file to discover all available pages before exploring further. # Subscriptions Subscriptions allow you to automate recurring billing for a customer on a defined schedule. This guide covers the prerequisites, API flow, and how to create and manage subscription plans. ## Prerequisites Before creating a subscription, two things must be in place: * **Stored Customer**: The customer must exist in the Ecrypt system with a populated customer wallet containing at least one stored payment token (wallet payment method). * **Reusable Payment Token**: When capturing the initial payment method (via iFrame or checkout page), `oneTimePayment` must be set to `false`. This ensures the generated token can be stored to the customer wallet and used for future recurring charges. Setting this to `true` will prevent the token from being reused. ## API Flows ### iFrame and Direct API For a first-time customer using the iFrame or direct API integration, the typical sequence is: 1. **Create Token** -- Tokenize the customer's payment method via the iFrame or checkout page with `oneTimePayment: false`. 2. **Create Customer** -- `POST /v1/customers` 3. **Create Customer Wallet** -- `POST /v1/customers/{Customer}/wallet` -- Store the token to the customer's wallet. 4. **Create Subscription Plan** -- `POST /v1/subscriptions` -- Define the billing plan (cycle, amount, label). 5. **Create Customer Subscription** -- `POST /v1/customers/{Customer}/subscriptions` -- Link the customer and their wallet to the subscription plan. ### Dynamic Checkout Page The [Dynamic Checkout](/checkout-page) page simplifies this considerably. By including a `subscription` object in the `POST /v1/dynamiccheckout` request body, the checkout page handles the entire flow in a single session: > **Tokenization > create customer > store payment method > subscription enrollment.** You simply select a pre-defined billing cycle and a billing date (start date) within the pages subscription object, and the checkout page takes care of the rest. ## Create a Subscription Plan **`POST /v1/subscriptions`** This endpoint defines a reusable subscription plan that can then be assigned to one or more customers. ### Required Fields `label` *(string, required)* -- A human-readable name for the subscription plan. Must be between 1 and 100 characters. `cycle` *(object, required)* -- Defines the billing frequency and timing. | Field | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `unit` | string | The base time unit: `day`, `week`, `month`, or `year` | | `interval` | int32 | How often the cycle repeats within that unit. For `day`: 1-365 (1 = daily, 2 = every other day). For `week`: 1-52 (1 = every week, 2 = every other week -- defaults to Monday if no `dayOfCycle` is set). For `month`: 1-12 (1 = every month, 2 = every other month -- defaults to the subscription activation date if no `dayOfCycle` is set). For `year`: 1-500. | | `day_of_cycle` | int32 | The specific day within the cycle to charge. For `week` unit: 1-7 (1 = Monday, 7 = Sunday). For `month` unit: 1-31 (31 defaults to the last day of the month for shorter months). For `year` unit: 1-365. Not applicable for `day` unit. | `amount` *(object, required)* -- The billing amount for each cycle occurrence. | Field | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `currency` | integer | ISO 4217 numeric currency code. Example: `840` = USD. | | `value` | decimal | The full charge amount per cycle, inclusive of all taxes, fees, and discounts. Range: `0.01` to `999999999.99`. Example: `49.99` | ### Example Request ```json theme={null} theme={null} { "label": "Monthly Premium Plan", "cycle": { "unit": "month", "interval": 1, "day_of_cycle": 1 }, "amount": { "currency": "USD", "value": 49.99 } } ``` *** ## Enrolling a Customer in a Subscription **`POST /v1/customers/{Customer}/subscriptions`** Once a subscription plan exists and the customer has a populated wallet, use this endpoint to activate the subscription for a specific customer. | Field | Type | Description | | -------------------- | ----------------- | ----------------------------------------------------------- | | `subscription_id` | string | The ID of the subscription plan to assign. | | `start` | date-time | The billing start date -- when the first charge will occur. | | `skip_first_payment` | boolean | If `true`, the first scheduled billing cycle is skipped. | | `wallet` | string (required) | The wallet ID of the stored payment method to charge. | | `initiated_by` | string | Indicates who initiated the transaction. | *** ## Checkout Page Subscription Object When using the Dynamic Checkout page (`POST /v1/dynamiccheckout`), include the `subscription` object to handle the full enrollment flow automatically. This is the simpler path for new customers. | Field | Type | Description | | --------------- | --------- | ------------------------------------------------------------------ | | `billing_cycle` | integer | Pre-defined billing cycle. See values below. | | `billing_date` | date-time | The start date for the subscription and first charge is scheduled. | | `label` | string | A label for the subscription. | **Billing Cycle Values** | Value | Cycle | | ----- | --------------------------- | | `10` | Daily | | `20` | Weekly | | `30` | BiWeekly | | `50` | SemiMonthly (1st and 15th) | | `52` | SemiMonthly (15th and Last) | | `70` | Monthly | | `71` | Monthly (1st) | | `73` | Quarterly | | `79` | Monthly (Last) | | `90` | SemiAnnually | | `95` | Annually | *** ## Subscription Management Once active, a customer subscription can be managed via the following endpoints. See the Customer Subscription section in the API reference. * **Modify Price** -- `PUT /v1/customers/{Customer}/subscriptions/{Subscription}` * **Suspend** -- `PUT /v1/customers/{Customer}/subscriptions/{Subscription}/suspend` * **Resume** -- `PUT /v1/customers/{Customer}/subscriptions/{Subscription}/resume` * **Cancel** -- `DELETE /v1/customers/{Customer}/subscriptions/{Subscription}` * **Delete Plan** -- `DELETE /v1/subscriptions/{Subscription}`