--- title: API Integration for Subscriptions excerpt: Developers can use this guide to implement subscriptions via UI or API deprecated: false hidden: false metadata: title: '' description: '' robots: index next: description: '' --- This guide shows you how to implement subscriptions using either the prebuilt UI component or direct API integration. ## When to Use API Integration **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 **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 **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 { 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 `CoinflowPurchase` component looks configured for an existing subscription plan. ### 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": "USDC" } ' ``` **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": "USDC", "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": "USDC", "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", "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).