Subscriptions

Overview

BlockBee Subscriptions allow you to offer recurring crypto payments for your services. You can create subscriptions for users, fetch their status, and handle renewal/expiration notifications via webhooks. BlockBee manages the payment interface and reminders, while you handle business logic on your end.

Setup

Before you can start implementing subscriptions, you need to configure your BlockBee account and get your API credentials.

1. Create a BlockBee Account

If you haven't already, sign up for a BlockBee account to get access to the dashboard.

2. Configure Addresses

Set up the cryptocurrency addresses where you want to receive subscription payments at Addresses.

3. Configure Subscription Settings

Configure your subscription plans and settings at Subscription Settings.

4. Generate API Key

1. Navigate to the API Keys section in your dashboard
2. Click "Generate New API Key"
3. Copy the generated API key - you'll need this for all API requests

Step 1: Create Subscription

To start, create a subscription for your user using the API.

API Endpoint

Method: GET URL: https://api.blockbee.io/subscription/create/

Code Examples

// Create a subscription
const createSubscription = async (userId, userEmail, option) => {
  const params = new URLSearchParams({
    apikey: 'YOUR_API_KEY',
    user_id: userId,
    user_email: userEmail,
    option: option, // e.g., 'pro-plan'
    post: '1'
  });
  const response = await fetch(`https://api.blockbee.io/subscription/create/?${params}`);
  const result = await response.json();
  if (result.status === 'success') {
    return {
      token: result.token,
      subscriptionUrl: result.subscription_url
    };
  } else {
    throw new Error('Failed to create subscription: ' + result.message);
  }
};

Required Parameters

• apikey – Your BlockBee API key
• user_id – User identifier in your system
• user_email – Customer email

Optional Parameters

• option – Subscription plan slug
• post – Set to 1 for POST webhooks

Response

Returns a subscription token and URL.

{
  "status": "success",
  "token": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o",
  "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o"
}

Step 2: Fetch & List Subscriptions

You can fetch a single subscription or list all subscriptions for your profile.

Fetch Subscription

Method: GET URL: https://api.blockbee.io/subscription/fetch/

Parameters:

• apikey (required)
• token (required)

List Subscriptions

Method: GET URL: https://api.blockbee.io/subscription/list/

Parameters:

• apikey (required)
• p (page, optional)

Code Examples

// Fetch a subscription
const fetchSubscription = async (token) => {
  const params = new URLSearchParams({
    apikey: 'YOUR_API_KEY',
    token
  });
  const response = await fetch(`https://api.blockbee.io/subscription/fetch/?${params}`);
  return await response.json();
};

Step 3: Handle Webhooks

BlockBee sends webhooks for subscription payments (renewals) and expiration. Your application must handle these to update user access and status.

1. Payment Notification Webhook

Sent when a user makes a payment (initial or renewal).

2. Expiration Notification Webhook

Sent when a subscription expires.

Webhook Handling Example

// Express.js webhook handler
app.post('/subscription-webhook', express.json(), (req, res) => {
  const { action, subscription_id, subscription_end_date_ts, payment_status } = req.body;
  if (action === 'renew' && payment_status === 'done') {
    // Grant/extend access for user
  } else if (action === 'expired') {
    // Revoke access for user
  }
  res.status(200).send('*ok*');
});

Best Practices

• Idempotency: Use subscription_id to avoid duplicate processing.
• Respond Quickly: Always respond with *ok* and status 200.
• Asynchronous Processing: Handle long tasks after responding.

Testing Your Integration

• Use a test user and plan for end-to-end flow.
• Test both payment and expiration webhooks.
• Use ngrok to expose your local server for webhook testing.

ngrok http 3000
# Use the public URL as your webhook endpoint