Skip to main content
POST
/
customer-subscriptions
Create Customer Subscription
curl --request POST \
  --url https://api.mijnklantportaal.nl/v1/customer-subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customerId": "cst_abc12345def678",
  "description": "Contribution costs",
  "startDate": "2024-05-04",
  "interval": "1 year",
  "amount": "12.95",
  "vatRate": 21,
  "createInvoice": true,
  "createPayment": true,
  "invoiceDescription": "Extending subscription",
  "paymentIntegrationMandateId": "mdt_123abc",
  "followUpFailedPayment": true
}'
{
  "id": "sub__abc12345def678",
  "customerId": "cst_abc12345def678",
  "description": "Website maintenance contract",
  "startsAt": "2024-04-29",
  "interval": "1 year",
  "renewsAt": "2025-04-29",
  "currency": "EUR",
  "amount": "12.95",
  "vatRate": 21,
  "status": "in_progress",
  "options": {
    "createInvoice": true,
    "createPayment": true,
    "invoiceDescription": "Extending subscription",
    "paymentIntegration": "mollie",
    "paymentIntegrationMandateId": "mdt_123abc",
    "followUpFailedPayment": true
  },
  "terminatedAt": "2024-04-29T21:00:00+02:00",
  "createdAt": "2024-04-29T21:00:00+02:00"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
customerId
string
required

ID of the customer this offer is meant for

Example:

"cst_abc12345def678"

​
description
string
required

Description of the Subscription

Example:

"Contribution costs"

​
startDate
string
required

Date the subscription should or has started, as format YYYY-mm-dd.

Example:

"2024-05-04"

​
interval
string
required

The interval of which the subscription will be extended. Can be 14 days, 1 month, 2 months, 6 months or 1 year.

Example:

"1 year"

​
amount
string
required

Amount to be charged in Euro (EUR), as string.

Example:

"12.95"

​
vatRate
integer
required

The VAT rate percentage as integer. Can be 0, 9 or 21.

Example:

21

​
createInvoice
boolean

Indicates if MijnKlantportaal should create an invoice in the connected bookkeeping integration. Can only be set to true when an integration has been set up already.

Example:

true

​
createPayment
boolean

Indicates if MijnKlantportaal should create a payment at the connected payment provider integration when the subscription gets extended. Can only be set to true when an integration has been set up already and supports only mollie.

Example:

true

​
invoiceDescription
string

The string which will be added as row on the created invoice. Will be ignored when createInvoice is set to false or omitted.

Example:

"Extending subscription"

​
paymentIntegrationMandateId
string

The ID of the mandate at the payment provider integration which will be used to create the payment. Will be ignored when createPayment is set to false or omitted. Be aware: MijnKlantportaal will not check if the mandate is valid!

Example:

"mdt_123abc"

​
followUpFailedPayment
boolean

When true, MijnKlantportaal will create another payment when the first one fails. Will be ignored when createPayment is set to false or omitted.

Example:

true

Response

The created Customer Subscription

Customer Subscription

​
id
string

ID of the subscription, always starting with sub_.

Example:

"sub__abc12345def678"

​
customerId
string

ID of the customer which the subscription belongs to.

Example:

"cst_abc12345def678"

​
description
string

Description of the subscription

Example:

"Website maintenance contract"

​
startsAt
string

Start date of the subscription. Formatted as YYYY-mm-dd.

Example:

"2024-04-29"

​
interval
string

The interval of which the subscription will be extended. Can be 14 days, 1 month, 2 months, 6 months or 1 year.

Example:

"1 year"

​
renewsAt
string

Date of when the subscription will be renewed next. Formatted as YYYY-mm-dd.

Example:

"2025-04-29"

​
currency
string

Currency of the subscription amount.

Example:

"EUR"

​
amount
string

Amount value as string.

Example:

"12.95"

​
vatRate
integer

The VAT rate percentage as integer. Can be 0, 9 or 21.

Example:

21

​
status
string

The current status of the subscription. Can be planned, in_progress, terminated or ended.

Example:

"in_progress"

​
options
object

Settings of the subscription

​
terminatedAt
string

Date and time when the subscription was terminated. Written in ATOM format.

Example:

"2024-04-29T21:00:00+02:00"

​
createdAt
string

Date and time when the subscription was added to MijnKlantportaal. Written in ATOM format.

Example:

"2024-04-29T21:00:00+02:00"

⌘I