## 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.

> **INFO**
>**Estimated time:** 10-15 minutes for a basic implementation


## 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](https://dash.blockbee.io/register) to get access to the dashboard.

### 2. Configure Addresses

Set up the cryptocurrency addresses where you want to receive subscription payments at [Addresses](https://dash.blockbee.io/profile/addresses).

> **INFO**
>Check this handy [tutorial](https://support.blockbee.io/support/solutions/articles/204000013598-how-to-set-up-the-addresses-) on how to setup your addresses.


### 3. Configure Subscription Settings

Configure your subscription plans and settings at [Subscription Settings](https://dash.blockbee.io/profile/subscriptions).

### 4. Generate API Key

1. Navigate to the [API Keys section](https://dash.blockbee.io/profile/api-keys) in your dashboard
2. Click "Generate New API Key"
3. Copy the generated API key - you'll need this for all API requests

> **INFO**
>Check this handy [tutorial](https://support.blockbee.io/support/solutions/articles/204000013926-how-to-generate-a-new-api-key) on how to generate an API Key.


> **WARNING**
>**Keep your API key secure:** Never expose your API key in client-side code or public repositories. Store it securely in environment variables or server-side configuration.


## 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/`

> **TIP**
>**API Reference:** See [Create a Subscription](/api/subscriptioncreate) for full parameter details.


### Code Examples
```javascript
// 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);
  }
};
```

```php
// ... existing code ...
```

```python
# ... existing code ...
```

```ruby
# ... existing code ...
```

```csharp
// ... existing code ...
```

```java
// ... existing code ...
```

```go
// ... existing code ...
```

```bash
# ... existing code ...
```

### 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.

```json
{
  "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)

> **TIP**
>**API Reference:** See [Fetch Subscription](/api/subscriptionfetch) and [List Subscriptions](/api/subscriptionlist) for full details.


### Code Examples
```javascript
// 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).

> **TIP**
>**Webhook Reference:** For complete webhook field documentation, see our [Subscriptions Webhook reference](/webhooks/subscriptions-webhook).


### 2. Expiration Notification Webhook
Sent when a subscription expires.

> **TIP**
>**Webhook Reference:** For complete webhook field documentation, see our [Subscriptions Webhook reference](/webhooks/subscriptions-webhook).


### Webhook Handling Example
```javascript
// 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*');
});
```

> **TIP**
>**Signature Verification:** Always verify webhook signatures. See [Verify Webhook Signature](/webhooks/verify-webhook-signature).


### 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](https://ngrok.com/) to expose your local server for webhook testing.

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

> **SUCCESS**
>**Ready for production?** Switch to your production API Key and endpoints when going live.