Moneybird logo
Moneybird API
Moneybird API

Subscriptions

Subscriptions allow you to automatically invoice customers on a recurring basis for the services you provide.

Get additional charges

GET
https://moneybird.com/api/v2
/{administration_id}/subscriptions/{id}/additional_charges{format}

Get the additional charges of the given subscription.

Required scope(s)

sales_invoices

Get additional charges › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id
​identifier · pattern: ^\d+$ · required

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Get additional charges › query Parameters

include_billed
​boolean | string

If true, includes the additional charges that have already been billed. Default is false.

Get additional charges › Responses

A subscription additional charge

subscription_additional_charge_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

contact_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

subscription_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

product_id
​identifier · pattern: ^\d+$

A unique record identifier

detail_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

amount
​string | null
price
​string
period
​string · pattern: ^[0-9]{6}..[0-9]{6}$
description
​string

Create an additional charge to be invoiced together with the subscription

POST
https://moneybird.com/api/v2
/{administration_id}/subscriptions/{id}/additional_charges{format}

At the end of the current subscription period, the additional charges are merged where possible and an invoice will be created for them. The invoice will be scheduled for sending together with the subscription invoice, so that they are merged on sending.

Required scope(s)

sales_invoices

Create an additional charge to be invoiced together with the subscription › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id
​identifier · pattern: ^\d+$ · required

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Create an additional charge to be invoiced together with the subscription › Request Body

Create an additional charge to be invoiced together with the subscription › Responses

Subscription additional charge created

subscription_additional_charge_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

contact_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

subscription_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

product_id
​identifier · pattern: ^\d+$

A unique record identifier

detail_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

amount
​string | null
price
​string
period
​string · pattern: ^[0-9]{6}..[0-9]{6}$
description
​string

Create and schedule an invoice to be sent together with the subscription

POST
https://moneybird.com/api/v2
/{administration_id}/subscriptions/{id}/create_and_schedule_one_off_sales_invoice{format}

Besides the recurring sales invoice for the subscription, you sometimes need to bill separate costs like usage based charges. Ideally you want these costs to be on the same invoice as the subscription invoice. This endpoint allows you to put extra invoice details on the subscription invoice.

This endpoint creates a new sales invoice and schedules it for sending on the same date as the next subscription invoice. During sending, Moneybird will merge both the scheduled invoice and the subscription invoice. This means the contact will receive one sales invoice with multiple invoice details, both from the subscription and from the one off sales invoice.

Required scope(s)

sales_invoices

Create and schedule an invoice to be sent together with the subscription › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id
​identifier · pattern: ^\d+$ · required

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Create and schedule an invoice to be sent together with the subscription › Request Body

​object

Create and schedule an invoice to be sent together with the subscription › Responses

Sales invoice created

sales_invoice_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

contact_id
​identifier · pattern: ^\d+$

A unique record identifier

contact_person_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

​
invoice_id
​string | null

The invoice number. It is null while the invoice is a draft.

recurring_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

subscription_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

workflow_id
​identifier · pattern: ^\d+$

A unique record identifier

document_style_id
​identifier · pattern: ^\d+$

A unique record identifier

identity_id
​identifier · pattern: ^\d+$

A unique record identifier

draft_id
​integer | null

Sequence number a draft is referred to by while it has no invoice number yet.

state
​string · enum
Enum values:
draft
scheduled
open
pending_payment
reminded
late
paid
uncollectible
invoice_date
​string | null · date
due_date
​string · date
payment_conditions
​string | null
payment_reference
​string | null
short_payment_reference
​string | null
reference
​string | null
language
​string | null
currency
​string
discount
​string | null
original_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

paused
​boolean
paid_at
​string | null · date
sent_at
​string | null · date
created_at
​string · date-time
updated_at
​string · date-time
public_view_code
​string | null
public_view_code_expires_at
​string | null · date-time
version
​version
​detail_response[]
​payment_response[]
total_paid
​string
total_unpaid
​string
total_unpaid_base
​string
prices_are_incl_tax
​boolean
total_price_excl_tax
​string
total_price_excl_tax_base
​string
total_price_incl_tax
​string
total_price_incl_tax_base
​string
total_discount
​string
marked_dubious_on
​string | null · date
marked_uncollectible_on
​string | null · date
reminder_count
​integer | null
next_reminder
​string | null · date
original_estimate_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

url
​string
payment_url
​string
​custom_field_value_response[]
​note_response[]
​attachment_response[]
​event_response[]
​tax_subtotal_response[]
​minimal_time_entry_response[]

Get subscription

GET
https://moneybird.com/api/v2
/{administration_id}/subscriptions/{id}{format}

Get a subscription.

Required scope(s)

sales_invoices

Get subscription › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id
​identifier · pattern: ^\d+$ · required

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Get subscription › Responses

A subscription

subscription_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

start_date
​string · date
end_date
​string | null · date
frequency
​integer | null
frequency_type
​string | null · enum
Enum values:
day
week
month
quarter
year
reference
​string | null
cancelled_at
​string | null · date-time
product_id
​identifier · pattern: ^\d+$

A unique record identifier

​product_response
contact_id
​identifier · pattern: ^\d+$

A unique record identifier

contact_person_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

​
​subscription_product_response[]
recurring_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

Cancel a subscription

DELETE
https://moneybird.com/api/v2
/{administration_id}/subscriptions/{id}{format}

Cancels the subscription. Stops the recurring sales invoice for the contact. Optionally you can provide an end_date to stop the subscription on a future date.

Required scope(s)

sales_invoices

Cancel a subscription › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id
​identifier · pattern: ^\d+$ · required

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Cancel a subscription › Request Body

​object

Cancel a subscription › Responses

Subscription cancelled

subscription_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

start_date
​string · date
end_date
​string | null · date
frequency
​integer | null
frequency_type
​string | null · enum
Enum values:
day
week
month
quarter
year
reference
​string | null
cancelled_at
​string | null · date-time
product_id
​identifier · pattern: ^\d+$

A unique record identifier

​product_response
contact_id
​identifier · pattern: ^\d+$

A unique record identifier

contact_person_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

​
​subscription_product_response[]
recurring_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

Update a subscription

PATCH
https://moneybird.com/api/v2
/{administration_id}/subscriptions/{id}{format}

Updates the product the contact is subscribed to. This will automatically calculate the differences between the product prices and create a one off sales invoice to bill the extra charge for the remaining billing period.

Optionally you can provide a start date for the product change to become active.

Required scope(s)

sales_invoices

Update a subscription › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id
​identifier · pattern: ^\d+$ · required

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Update a subscription › Request Body

​object

Update a subscription › Responses

Subscription updated

subscription_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

start_date
​string · date
end_date
​string | null · date
frequency
​integer | null
frequency_type
​string | null · enum
Enum values:
day
week
month
quarter
year
reference
​string | null
cancelled_at
​string | null · date-time
product_id
​identifier · pattern: ^\d+$

A unique record identifier

​product_response
contact_id
​identifier · pattern: ^\d+$

A unique record identifier

contact_person_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

​
​subscription_product_response[]
recurring_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

List subscriptions of a contact

GET
https://moneybird.com/api/v2
/{administration_id}/subscriptions{format}

Lists the subscriptions of a single contact. There is no endpoint that returns the subscriptions of every contact at once.

Required scope(s)

sales_invoices

List subscriptions of a contact › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

List subscriptions of a contact › query Parameters

contact_id
​identifier · pattern: ^\d+$ · required

A unique record identifier

List subscriptions of a contact › Responses

200

A list of subscriptions

subscription_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

start_date
​string · date
end_date
​string | null · date
frequency
​integer | null
frequency_type
​string | null · enum
Enum values:
day
week
month
quarter
year
reference
​string | null
cancelled_at
​string | null · date-time
product_id
​identifier · pattern: ^\d+$

A unique record identifier

​product_response
contact_id
​identifier · pattern: ^\d+$

A unique record identifier

contact_person_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

​
​subscription_product_response[]
recurring_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

Create a new subscription

POST
https://moneybird.com/api/v2
/{administration_id}/subscriptions{format}

Starts a new subscription for the given contact. The product_id points to a product with a frequency, price and description. A recurring sales invoice is automatically created to bill the contact for the given frequency. The first invoice will be sent on the start date, but no sooner than tomorrow. The reference will be added to the sales invoices.

Optionally you can create a subscription with a different frequency than stored in the product. Make sure the frequency of the product and the provided frequency are compatible. E.g. you can bill a monthly product yearly.

Required scope(s)

sales_invoices

Create a new subscription › path Parameters

administration_id
​administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

format
​string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Create a new subscription › Request Body

​object

Create a new subscription › Responses

Subscription created

subscription_response
id
​identifier · pattern: ^\d+$

A unique record identifier

administration_id
​administration_id · pattern: ^\d+$

A unique record identifier

start_date
​string · date
end_date
​string | null · date
frequency
​integer | null
frequency_type
​string | null · enum
Enum values:
day
week
month
quarter
year
reference
​string | null
cancelled_at
​string | null · date-time
product_id
​identifier · pattern: ^\d+$

A unique record identifier

​product_response
contact_id
​identifier · pattern: ^\d+$

A unique record identifier

contact_person_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

​
​subscription_product_response[]
recurring_sales_invoice_id
​identifier_nullable · pattern: ^\d+$

A unique record identifier

Subscription templatesTask lists