> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# API Integration for Subscriptions

This guide shows you how to implement subscriptions using either the prebuilt UI component or direct API integration.

## When to Use API Integration

#### Perfect For

**Choose API integration when you need full customization**

* Custom branded checkout experience
* Non-React frameworks (Vue, Angular, vanilla JS, mobile)
* Complex subscription logic (trials, upgrades, prorations)
* Multi-step checkout with additional business logic
* Backend-only subscription management
* Custom payment method collection flows
* Teams with frontend development capacity

**Integration time:** 1-2 weeks for custom UI

#### Consider Prebuilt UI If

**These scenarios work better with the prebuilt component**

* **React/Next.js apps** with standard subscription flows
* **Quick validation** of subscription business model (hours vs weeks)
* **Limited resources** for building custom payment UI
* **Standard checkout** without complex customization needs
* **Faster time to market** is critical priority

→ See [Prebuilt Coinflow UI](./prebuilt-coinflow-ui) for fastest integration

> **Info**
>
> **Trade-offs: Speed vs Control**
>
> The prebuilt UI gets you live in hours with minimal code, while API integration takes 1-2 weeks but gives you complete control over the user experience. Both support the same payment methods, currencies, and business logic.

---

## UI Implementation

### Installation

Install the latest Coinflow packages:

```bash
npm i @coinflowlabs/react
```

### Configuration

To use the provided purchase page for subscriptions:

1. Supply the `merchantId` and `planCode` in the `CoinflowPurchase` component
2. The subscription cost and information will automatically populate the form

### Example Implementation

```javascript
// Example of how to configure CoinflowPurchase for subscriptions
<CoinflowPurchase
  sessionKey={'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'}
  merchantId={'YOUR_MERCHANT_ID'}
  env={'sandbox'} // Change to 'prod' for production
  onSuccess={(...args) => {
    console.log('Purchase Success', args);
    // Create your own on success function after payment success
  }}
  chargebackProtectionData={[
    {
      productName: "Subscription plan",
      productType: "subscription",
      quantity: 1,
      rawProductData: {
        description: "subscription to gold tier products",
        productsInGoldTier: ["celebrity access passes", "cool merchandise"],
        tradible: false
      }
    }
  ]}
  planCode={'12345'}
/>
```

### Component Display

### How the Subscription Purchase Works

When a customer subscribes:

1. **Payment Method**: Customer provides a payment method (card or bank account)
2. **Initial Payment**: The first payment is processed immediately
3. **Subscription Creation**: If payment succeeds, the subscription is created with `Active` status
4. **Recurring Billing**: Future payments are automatically processed according to the plan schedule

> **Note**: If the first payment fails, the subscription is not created. The customer must retry the entire subscription purchase.

## API Implementation

Follow these steps to implement subscriptions via direct API integration.

### Step 1: Create a Subscription Plan

[Create a subscription plan](/api-reference/api-reference/merchant-subscription/create-plan) using the merchant API. This is a one-time setup for each plan you want to offer.

```curl
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/merchant/subscription/plans \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "interval": "Monthly",
  "amount": {
    "currency": "USD",
    "cents": 1000
  },
  "name": "Gold Tier Plan",
  "code": "12345",
  "duration": 4,
  "description": "A monthly subscription to gain access to our gold tier product suite",
  "settlementType": "USD"
}
'
```

> **Note:** Use `USDC` or `EUROe` for `settlementType` if you want stablecoin settlement; see [Settlement Types](/guides/checkout/settlement-locations).

**Response:**

```json
{
  "merchant": "6840bca9c7cb21ee5baaae76",
  "name": "Gold Tier Plan",
  "code": "12345",
  "interval": "Monthly",
  "duration": 4,
  "amount": {
    "cents": 1000,
    "currency": "USD"
  },
  "description": "A monthly subscription to gain access to our gold tier product suite",
  "settlementType": "USD",
  "active": true,
  "_id": "6851d74578269da7d5a533c4",
  "__v": 0,
  "id": "6851d74578269da7d5a533c4"
}
```

### Step 2: Get Available Subscription Plans

[Get all available subscription plans](/api-reference/api-reference/subscription/get-available-plans) that customers can purchase. Use this endpoint in your application to display plan options.

```curl
curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/plans \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'
```

**Response:**

```json
[
  {
    "id": "6851d74578269da7d5a533c4",
    "name": "Gold Tier Plan",
    "code": "12345",
    "interval": "Monthly",
    "duration": 4,
    "amount": {
      "cents": 1000,
      "currency": "USD"
    },
    "description": "A monthly subscription to gain access to our gold tier product suite",
    "settlementType": "USD",
    "active": true
  }
]
```

### Step 3: Create Subscription with Credit Card

[Enable customers to subscribe to a plan](/api-reference/api-reference/subscription/create-subscription-card) with a credit card. This processes the first payment and creates the subscription.

> **Important**: You must tokenize the card before making this request. See the [card tokenization guide](/guides/developer-resources/checkout-implementation/credit-cards-implementation/tokenize-credit-cards) for details.

```curl
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/subscribers/card \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw' \
     --data '
{
  "card": {
    "cardToken": "411111YJM5TX1111",
    "expYear": "30",
    "expMonth": "10",
    "email": "test@gmail.com",
    "firstName": "Dwayne",
    "lastName": "Johnson",
    "address1": "201 E Randolph Street",
    "city": "Chicago",
    "zip": "60625",
    "state": "IL",
    "country": "US"
  },
  "chargebackProtectionData": [
    {
      "productName": "Subscription plan",
      "productType": "subscription",
      "quantity": 1,
      "rawProductData": {
        "example": "{\"description\": \"subscription to gold tier products\", \"productsInGoldTier\": [\"celebrity access passes\", \"cool merchandise\"], \"tradible\": false}"
      }
    }
  ],
  "planCode": "12345"
}
'
```

**Response:**

```text
c10d7ac6-cca8-436b-b99f-2c7418f1cbe1
```

### Step 4: Enable Customer to Cancel Subscription

Allow customers to [cancel their subscription](/api-reference/api-reference/subscription/cancel-customer-subscription) when needed.

#### Get Customer Subscriptions

First, retrieve all subscriptions for the customer:

```curl
# Gets all the subscriptions the customer is currently subscribed to
# API Reference: /api-reference/api-reference/customers/get-customersubscriptions

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/subscribers \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'
```

**Response:**

```json
[
  {
    "id": "6851d8c378269da7d5a535d6", // This is the subscriptionId
    "customerId": "dwaynejohnson75",
    "blockchain": "user", // Internal routing field; can be ignored for bank/card subscriptions
    "merchantId": "mello",
    "email": "test@gmail.com",
    "plan": "Gold Tier Plan",
    "planCode": "12345",
    "status": "Canceled"
  }
]
```

#### Cancel the Subscription

Use the subscription ID from the previous response to cancel:

```curl
# Allows customer to cancel their subscription
# See also: Cancel Subscription (by merchant) as an alternative for server-to-server cancellation
# API Reference: /api/cancelsubscription

curl --request PATCH \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/subscribers/6851d8c378269da7d5a535d6 \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'
```

## Testing

To test credit card purchases for a subscription, please see our [testing credit card purchase documentation](/guides/checkout/testing/testing-credit-cards). For bank-account testing, see the [ACH testing guide](/guides/checkout/testing/testing-ach).