API Integration guide

Managing Subscriptions

Automatically create and manage subscriptions for your customers, including recurring billing, additional charges, and one-off invoices.

Overview

Subscriptions allow you to automatically invoice customers on a recurring basis for the services you provide. This integration pattern is ideal when:

You offer recurring services or products (SaaS, membership, maintenance contracts)
You need to bill usage-based charges or seat-based billing on top of base subscriptions
You want to collect payments automatically via direct debit (SEPA) or credit card
You need to send occasional one-off invoices alongside regular subscription billing

Prerequisites

You have an access token and your administration ID. See Getting started and Authentication.
You have created products for your subscription services. See Products.
You know the correct ledger_account_id and tax_rate_id for your revenue. See Ledger accounts and Tax rates.
For automatic payment collection, Moneybird Payments must be enabled for your administration.

Step-by-step

1. Create or Find Contact

Before creating a subscription, ensure you have a contact record in Moneybird.

Create a new contact:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "contact": {
      "company_name": "TechStart Inc.",
      "firstname": "John",
      "lastname": "Smith",
      "address1": "123 Business St",
      "zipcode": "1234 AB",
      "city": "Amsterdam",
      "country": "NL",
      "email": "john@techstart.com",
      "customer_id": "external_id_12345"
    }
  }'

2. Set Up Payment Mandate (Optional but Recommended)

For automatic payment collection, set up a Moneybird Payments mandate. This allows you to automatically collect payments via SEPA direct debit or credit card.

Option A: Generate a mandate URL and redirect the customer:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts/{CONTACT_ID}/moneybird_payments_mandate/url.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Response:

Code
 
{
  "url": "https://moneybird.com/mandate/setup/abc123def456",
  "expires_at": "2025-10-01T12:00:00Z"
}

Direct your customer to this URL to complete the mandate setup. The customer will make a small authorization payment.

Option B: Send mandate request via email:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts/{CONTACT_ID}/moneybird_payments_mandate.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

This sends an email to the contact with instructions to set up the payment mandate.

Monitor mandate setup completion:

You can listen for the contact_mandate_request_succeeded webhook event to get notified when the customer successfully completes the mandate setup. See Webhooks for setup instructions.

3. Create a Subscription

Create a subscription for the contact using a product with recurring billing:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscriptions.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "subscription": {
      "contact_id": "{CONTACT_ID}",
      "product_id": "{PRODUCT_ID}",
      "start_date": "2025-10-01",
      "reference": "SUB-2025-001",
      "workflow_id": "{WORKFLOW_ID}",
      "frequency": "month",
      "frequency_amount": 1
    }
  }'

Key parameters:

product_id: Must be a product configured for recurring billing
start_date: When the subscription starts (first invoice sent)
workflow_id: Determines invoice settings and payment collection method
frequency: Billing frequency (month, quarter, year)
frequency_amount: Multiplier for frequency (e.g., 2 for every 2 months)

4. Add Usage-Based or Additional Charges

For services with variable usage (e.g., API calls, storage, additional seats), add charges that will be billed with the next subscription invoice:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscriptions/{SUBSCRIPTION_ID}/additional_charges.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "product_id": "{USAGE_PRODUCT_ID}",
    "amount": "150",
    "price": "0.05",
    "period": "2025-09-01..2025-09-30",
    "description": "API Calls - September 2025"
  }'

Usage examples:

API usage: Track API calls and bill per call or batch
Storage charges: Bill for additional storage used
Seat billing: Charge for extra users added during the billing period
Support charges: Bill for premium support hours used

5. Create One-Off Invoices

Sometimes you need to bill separate costs alongside the subscription (setup fees, consulting, etc.). Create and schedule these to be sent together with the subscription invoice:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscriptions/{SUBSCRIPTION_ID}/create_and_schedule_one_off_sales_invoice.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "sales_invoice": {
      "reference": "SETUP-2025-001",
      "details_attributes": [
        {
          "description": "Initial Setup and Configuration",
          "price": "500.00",
          "amount": "1",
          "tax_rate_id": "{TAX_RATE_ID}",
          "ledger_account_id": "{LEDGER_ACCOUNT_ID}"
        },
        {
          "description": "Data Migration Service",
          "price": "750.00",
          "amount": "1",
          "tax_rate_id": "{TAX_RATE_ID}",
          "ledger_account_id": "{LEDGER_ACCOUNT_ID}"
        }
      ]
    }
  }'

This invoice will be automatically merged with and sent alongside the next subscription invoice.

6. Monitor and Manage Subscriptions

Check subscription status:

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

List all subscriptions for a contact:

Code
 
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/subscriptions.json?contact_id={CONTACT_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Payment Collection with Workflows

When you create a subscription with a workflow that has Moneybird Payments and Automatic direct debit enabled, and the customer has accepted the mandate, invoices will be automatically paid via direct debit or credit card.

Common Integration Patterns

SaaS Billing

Base subscription for platform access
Additional charges for usage (API calls, storage, seats)
One-off charges for setup or premium features

Membership Services

Monthly/yearly membership subscription
Additional charges for events or premium content
One-off charges for merchandise or special services

Next Steps

After setting up subscriptions, you may want to:

Set up webhooks to receive notifications about subscription events and payment status changes
Consider hosted subscription management for self-service subscription management via Moneybird's customer portal

Last modified on September 29, 2025

Sending Invoices with Peppol Hosted Subscription Management