Skip to main content
POST
/
api
/
external
/
v2
/
billing_subscriptions
Create a billing subscription
curl --request POST \
  --url https://app.pennylane.com/api/external/v2/billing_subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2023-01-01",
  "mode": {
    "type": "email",
    "email_settings": {
      "recipients": [
        "[email protected]",
        "[email protected]"
      ]
    }
  },
  "payment_conditions": "upon_receipt",
  "payment_method": "offline",
  "recurring_rule": {
    "type": "yearly",
    "interval": 123,
    "count": 12
  },
  "customer_id": 42,
  "customer_invoice_data": {
    "currency": "EUR",
    "customer_invoice_template_id": 42,
    "pdf_invoice_free_text": "Additional free field",
    "pdf_invoice_subject": "Invoice title",
    "pdf_description": "Invoice description",
    "special_mention": "Additional details",
    "language": "fr_FR",
    "discount": {
      "type": "absolute",
      "value": "25"
    },
    "invoice_line_sections": [
      {
        "title": "Invoice line section title",
        "description": "Description of the invoice line section",
        "rank": 1
      }
    ],
    "invoice_lines": [
      {
        "label": "Demo label",
        "quantity": 12,
        "unit": "piece",
        "raw_currency_unit_price": "33.333334",
        "vat_rate": "FR_200",
        "description": "<string>",
        "section_rank": 1,
        "discount": {
          "type": "absolute",
          "value": "25"
        },
        "ledger_account_id": 1255,
        "product_id": 42
      }
    ]
  }
}'
{
  "id": 42,
  "next_occurrence": "2023-01-01",
  "prev_occurrence": "2023-01-01",
  "stopped_at": "2023-08-30T10:08:08.146343Z",
  "start": "2023-01-01",
  "finish": "2023-12-31",
  "status": "draft",
  "mode": "awaiting_validation",
  "activated_at": "2023-08-30T10:08:08.146343Z",
  "payment_conditions": "upon_receipt",
  "payment_method": "offline",
  "email_settings": {
    "recipients": [
      "[email protected]"
    ],
    "billing_email_template": {
      "id": 123,
      "label": "<string>"
    }
  },
  "recurring_rule": {
    "day_of_month": [
      123
    ],
    "month_of_year": [
      123
    ],
    "week_start": 123,
    "day": [
      123
    ],
    "rule_type": "monthly",
    "interval": 123,
    "count": 12,
    "until": "<string>"
  },
  "customer": {
    "id": 42,
    "url": "https://app.pennylane.com/api/external/v2/customers/42"
  },
  "customer_invoice_data": {
    "label": "Demo label",
    "currency": "EUR",
    "amount": "230.32",
    "currency_amount": "230.32",
    "currency_amount_before_tax": "196.32",
    "exchange_rate": "1.0",
    "currency_tax": "34.0",
    "language": "fr_FR",
    "customer_invoice_template": {
      "id": 123
    },
    "discount": {
      "type": "absolute",
      "value": "25"
    },
    "pdf_invoice_free_text": "Thanks for paying this invoice",
    "pdf_invoice_subject": "Invoice subject",
    "pdf_description": "Invoice description",
    "special_mention": "Additional details",
    "invoice_line_sections": {
      "url": "https://app.pennylane.com/api/external/v2/billing_subscriptions/42/invoice_line_sections"
    },
    "invoice_lines": {
      "url": "https://app.pennylane.com/api/external/v2/billing_subscriptions/42/invoice_lines"
    }
  },
  "created_at": "2023-08-30T10:08:08.146343Z",
  "updated_at": "2023-08-30T10:08:08.146343Z"
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
start
string<date>
required
Example:

"2023-01-01"

​
mode
object
required

Use this mode if you need generated invoices to be sent by email.

  • Email
  • Other
​
payment_conditions
enum<string>
required
Available options:
upon_receipt,
7_days,
15_days,
30_days,
30_days_end_of_month,
45_days,
45_days_end_of_month,
60_days
​
payment_method
enum<string>
required

Payment method offline means the subscription is not linked to a payment method gocardless_direct-debit means at each new occurrence the client will be automatically debited thanks to GoCardless. To do so, you need a GoCardless account properly configured.

Available options:
offline,
gocardless_direct_debit
​
recurring_rule
object
required
  • Yearly recurrence
  • Monthly recurrence
  • Weekly recurrence
​
customer_id
integer
required

Customer identifier

Example:

42

​
customer_invoice_data
object
required

Response

Renders the created billing subscription

​
id
integer
required

Billing subscription identifier

Example:

42

​
next_occurrence
string<date> | null
required

The date for the next subscription renewal

Example:

"2023-01-01"

​
prev_occurrence
string<date> | null
required

The date of the previous subscription renewal

Example:

"2023-01-01"

​
stopped_at
string<date-time> | null
required

The exact timestamp when the subscription was terminated

Example:

"2023-08-30T10:08:08.146343Z"

​
start
string<date>
required

The subscription start date

Example:

"2023-01-01"

​
finish
string<date> | null
required

The date for when the subscription will end

Example:

"2023-12-31"

​
status
enum<string>
required
Available options:
draft,
stopped,
finished,
pending,
not_started,
in_progress
​
mode
enum<string>
required
  • awaiting_validation: generated invoices will be in draft
  • finalized: generated invoices will be finalized
  • email: generated invoices will be finalized and sent by email to the recipients configured on the subscription
Available options:
awaiting_validation,
finalized,
email
​
activated_at
string<date-time> | null
required

The exact timestamp for when the subscription was activated

Example:

"2023-08-30T10:08:08.146343Z"

​
payment_conditions
required
Available options:
upon_receipt,
7_days,
15_days,
30_days,
30_days_end_of_month,
45_days,
45_days_end_of_month,
60_days
​
payment_method
enum<string>
required

Payment method offline means the subscription is not linked to a payment method gocardless_direct-debit means at each new occurrence the client will be automatically debited thanks to GoCardless. To do so, you need a GoCardless account properly configured.

Available options:
offline,
gocardless_direct_debit
​
email_settings
object | null
required
​
recurring_rule
object
required
​
customer
object | null
required
​
customer_invoice_data
object
required
​
created_at
string<date-time>
required

The time the subscription has been created

Example:

"2023-08-30T10:08:08.146343Z"

​
updated_at
string<date-time>
required

The last time the subscription has been updated

Example:

"2023-08-30T10:08:08.146343Z"

⌘I