# Hosted Subscription Management

Enable self-service subscription management for your customers using Moneybird's hosted checkout and customer portal, allowing them to start subscriptions, change tiers, and manage billing independently.

## Overview

Hosted subscription management allows customers to manage their own subscriptions through Moneybird's customer portal. This approach is ideal when:

- You want to minimize subscription management complexity in your application
- You need customers to self-service subscription changes, upgrades, and billing
- You want Moneybird to handle the checkout flow and payment collection

This differs from [API-driven subscription management](/integration/managing-subscriptions) where all subscription operations are handled through your application.

## Prerequisites

- You have an access token and your administration ID. See [Getting started](/integration/getting-started) and [Authentication](/authentication).
- You have created subscription templates in Moneybird that define your subscription tiers and pricing.
- Moneybird Payments is enabled for automatic payment collection.
- You have configured workflows for your subscription billing.

## Step-by-step

### 1. Set Up Subscription Templates

First, create subscription templates in the UI that define your subscription tiers, pricing, and settings. These templates will be used for the hosted checkout experience.

**List existing subscription templates:**

```bash
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscription_templates.json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
```

**Response:**
```json
[
  {
    "id": "465273141772421025",
    "administration_id": 123,
    "workflow_id": "465273141748303769",
    "document_style_id": "465273141702166424",
    "mergeable": false,
    "contact_can_update": true,
    "products": [
      {
        "id": "465273141767178144",
        "administration_id": 123,
        "description": "Premium Plan",
        "title": "Premium",
        "identifier": "premium-monthly",
        "price": "29.99",
        "currency": "EUR",
        "frequency": 1,
        "frequency_type": "month",
        "tax_rate_id": "465273141755643806",
        "ledger_account_id": "465273141762983839"
      }
    ]
  }
]
```

### 2. Create Hosted Checkout Links

Generate checkout links for customers to start subscriptions through Moneybird's hosted checkout flow.

**Option A: Contact-specific checkout link (unique URL):**

When you provide a `contact_id`, you get a unique checkout URL for that specific customer:

```bash
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscription_templates/{TEMPLATE_ID}/checkout_identifier.json?contact_id={CONTACT_ID}&start_date=2025-10-01" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
```


**Option B: General checkout link (reusable URL):**

Without a `contact_id`, you get a general checkout URL that can be reused for multiple customers:

```bash
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscription_templates/{TEMPLATE_ID}/checkout_identifier.json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
```

This general URL can also be obtained directly through the Moneybird UI and used in website buttons, or email campaigns.

### 3. Redirect Customer to Hosted Checkout

Direct your customer to the generated checkout URL. The hosted checkout will:

- Allow the customer to review subscription details
- Collect payment information and set up automatic billing
- Create the subscription and payment mandate
- Redirect back to your application, if configured in your workflow.

### 4. Generate Customer Portal Links

After a subscription is created through hosted checkout, you can generate portal links for customers to manage their subscriptions.


**Generate link to specific subscription:**

```bash
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/customer_contact_portal/{CONTACT_ID}/subscriptions/{SUBSCRIPTION_ID}.json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
```

All portal links expire after 1 hour for security reasons.

## Customer Portal Capabilities

When customers access the portal through your generated links, they can:

### Subscription Management
- View current subscription details and billing cycle
- Upgrade or downgrade between available tiers (if `contact_can_update` is enabled)
- Pause or cancel subscriptions
- Update billing information and payment methods

### Invoice Management
- View all past and current invoices
- Download invoice PDFs
- See payment status and due dates
- Access payment history

### Account Management
- Update contact information
- Manage payment mandates
- View upcoming charges and billing dates

## Webhooks Integration

Monitor subscription changes and customer actions through webhooks:

- `subscription_created`: When customer completes hosted checkout
- `subscription_updated`: When customer changes subscription tier
- `subscription_cancelled`: When customer cancels subscription
- `sales_invoice_created`: When subscription invoices are generated

See [Webhooks](/webhooks/getting-started) for setup instructions.

## Next Steps

After implementing hosted subscription management:
1. Set up [webhooks](/webhooks/getting-started) to monitor subscription lifecycle events


## Comparison with API Management

| Feature | Hosted Management | API Management |
|---------|------------------|----------------|
| **Setup Complexity** | Low - use templates | High - custom implementation |
| **Customer Experience** | Moneybird-hosted portal | Custom UI in your app |
| **Subscription Changes** | Self-service through portal | API calls from your app |
| **Payment Collection** | Automatic via Moneybird | Manual API integration |
| **Customization** | Limited to template options | Full control over UX |
| **Maintenance** | Managed by Moneybird | Your responsibility |

Choose hosted management for faster implementation and reduced complexity, or API management for maximum control and custom user experiences.