Sign in

v1

latestOpenAPI 3.0.12026-07-141671231.8 MB
Billing Subscriptions

Create a billing subscription

This endpoint allows you to create a subscription. Pennylane will generate the customer invoice each month. You can also link the subscription to a GoCardless mandate.

ℹ️ This endpoint requires the following scope: billing_subscriptions:all

post/api/external/v2/billing_subscriptions

Request body

startstring date required
payment_conditions'upon_receipt' | '7_days' | '15_days' | '30_days' | '30_days_end_of_month' | '45_days' | '45_days_end_of_month' | '60_days' required
payment_method'offline' | 'gocardless_direct_debit' | 'pro_account_sepa_core' 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.

labelstring nullable
customer_idinteger required

Customer identifier

Example request

{
  "start": "2023-01-01",
  "mode": {
    "email_settings": {
      "recipients": [
        "customer@example.com",
        "accounting@example.com"
      ]
    }
  },
  "recurring_rule": {
    "count": 12
  },
  "customer_id": 42,
  "customer_invoice_data": {
    "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",
    "discount": {
      "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",
        "section_rank": 1,
        "discount": {
          "value": "25"
        },
        "ledger_account_id": 1255,
        "product_id": 42
      }
    ]
  }
}

Response

Renders the created billing subscription

idinteger required

Billing subscription identifier

next_occurrencestring date nullable required

The date for the next subscription renewal

prev_occurrencestring date nullable required

The date of the previous subscription renewal

stopped_atstring date-time nullable required

The exact timestamp when the subscription was terminated

startstring date nullable required

The subscription start date

finishstring date nullable required

The date of the last occurrence of the subscription

status'draft' | 'stopped' | 'finished' | 'pending' | 'not_started' | 'in_progress' required
mode'awaiting_validation' | 'finalized' | 'email' 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
activated_atstring date-time nullable required

The exact timestamp for when the subscription was activated

payment_method'offline' | 'gocardless_direct_debit' | 'pro_account_sepa_core' 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.

labelstring nullable required
created_atstring date-time required

The time the subscription has been created

updated_atstring date-time required

The last time the subscription has been updated

Example response

{
  "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",
  "activated_at": "2023-08-30T10:08:08.146343Z",
  "recurring_rule": {
    "rule_type": "monthly",
    "count": 12
  },
  "customer": {
    "id": 42,
    "url": "https://app.pennylane.com/api/external/v2/customers/42"
  },
  "customer_invoice_data": {
    "label": "Demo label",
    "amount": "230.32",
    "currency_amount": "230.32",
    "currency_amount_before_tax": "196.32",
    "exchange_rate": "1.0",
    "currency_tax": "34.0",
    "discount": {
      "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"
}