# 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](/integration/getting-started) and [Authentication](/authentication).
- You have created products for your subscription services. See [Products](/api/products).
- You know the correct `ledger_account_id` and `tax_rate_id` for your revenue. See [Ledger accounts](/api/ledger-accounts) and [Tax rates](/api/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:**

```bash
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:**

```bash
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:**
```json
{
  "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:**

```bash
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](/webhooks/getting-started) for setup instructions.

### 3. Create a Subscription

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

```bash
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 (`day`, `week`, `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:

```bash
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:

```bash
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:**

```bash
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:**

```bash
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:

1. Set up [webhooks](/webhooks/getting-started) to receive notifications about subscription events and payment status changes
2. Consider [hosted subscription management](/integration/hosted-subscription-management) for self-service subscription management via Moneybird's customer portal