API Integration guide

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 where all subscription operations are handled through your application.

Prerequisites

• You have an access token and your administration ID. See Getting started and 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:

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

Response:

Code
 
[
  {
    "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:

Code
 
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:

Code
 
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:

Code
 
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 for setup instructions.

Next Steps

After implementing hosted subscription management:

1. Set up webhooks 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.