Subscriptions using the API

Steps

1. Create subscription

Create a recurring invoice by calling POST /subscriptions.

The billing_cycle defines the frequency of the invoices to be generated. The billing_cycle can be set:

• with a periodic interval (for example, monthly, quarterly, yearly, etc.) using the type as interval,
• or with a custom interval using the type as custom. To set a custom interval you need to define the day of the month and the month of the year as used in a cron expression.

The invoice_details contains the template for each invoice generated by the subscription. Check the invoice creation for further details. Subscriptions are only available using invoice series.

The usage of webhooks is recommended to receive real-time notifications about the invoices generated as part of the subscription.

The response of the invoice creation contains:

• The id of the subscription
• The starts_at date when the subscription will generate the first invoice

In this scenario:

• There is a non-periodic subscription issued every 10th of May and September.
• The payment is deferred for 30 days.

Request

POST /subscriptions

{
  "type": "custom",
  "name": "Non-periodic SAAS subscription",
  "billing_cycle": {
    "type": "custom",
    "day_of_month": "10",
    "month_of_year": "5,9"
  },
  "invoice_details": {
    "code": {
      "type": "fixed_series",
      "series_id": "ser_4ehg1mkv3mvt3256vcn8dspb4h"
    },
    "seller": {
      "id": "acc_96468af833b74501bd0415e797"
    },
    "buyer": {
      "id": "acc_44678r08jtm8zbt227tzhc4nw5",
      "notifications": [
        {
          "type": "email",
          "to": [
            "invoices@buyer.com"
          ]
        }
      ]
    },
    "currency": "EUR",
    "lines": [
      {
        "item": {
          "name": "Align direction",
          "amount": 4000,
          "unit": "hour"
        },
        "quantity": 1,
        "taxes": [
          {
            "type": "percentage",
            "name": "VAT",
            "percent": 20,
            "reference": "vat"
          }
        ]
      }
    ],
    "payment": {
      "terms": {
        "type": "deferred",
        "due_dates": [
          {
            "days": 30
          }
        ]
      },
      "methods": [
        {
          "type": "external_direct_debit",
          "payment_instrument_id": "pai_42572e6cf7914e23b5b312d5b1"
        }
      ]
    },
    "documents": [
      {
        "format": "pdf"
      }
    ]
  }
}

Response

201 Created

{
  "id": "sub_4378g9ymq82qz3tr26zx02nh5m",
  "starts_at": "2024-09-10"
}

2. Notify about invoice issued

A invoice_issued webhook notification in sent in the configured webhook URL every time an invoice is generated as part of the subscription.

It is particularly important when using subscriptions since this webhook will contain the generated invoice code value in its payload.

The rest of the webhooks are the same as the invoice creation and depend on the details of the invoice configured.

3. Send invoice buyer notification

If the document is generated and the buyer has notifications configured, the system will send an email to the buyer with the invoice generated every time a new invoice is issued as part of the subscription.

Webhooks related are the same as the invoice creation.