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 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:
- Create Token — Tokenize the customer’s payment method via the iFrame or checkout page with
oneTimePayment: false.
- Create Customer —
POST /v1/customers
- Create Customer Wallet —
POST /v1/customers/{Customer}/wallet — Store the token to the customer’s wallet.
- Create Subscription Plan —
POST /v1/subscriptions — Define the billing plan (cycle, amount, label).
- Create Customer Subscription —
POST /v1/customers/{Customer}/subscriptions — Link the customer and their wallet to the subscription plan.
Dynamic Checkout Page
The Dynamic Checkout 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
{
"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. |
| 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}
