PEpennylane
Billing Subscriptions

Create a billing subscription

Changed on

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

  • Base URL
    https://app.pennylane.com
  • URL
    https://app.pennylane.com/api/external/v2/billing_subscriptions
  • Auth
    OAuth 2
    Authorization code: https://app.pennylane.com/oauth/authorize
    Token URL: https://app.pennylane.com/oauth/oauth/token scopes: billing_subscriptions:all

Headers

X-Company-Idstring
Example:12345

Numeric ID of the company to act on. Required when authenticating with a firm token. Ignored when the token is already bound to a company.

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"
}

Changes

  • 871f863307e5Revision changes
    • breaking

      added subschema #1 subschema #2 to the request property allOf list

    • breaking

      removed subschema #1: Yearly recurrence subschema #2: Monthly recurrence subschema #3: Weekly recurrence from the request property anyOf list

    • breaking

      the request property type changed from object to no type

    • warning

      added the new VES enum value to the / response property for the response status

    • warning

      added the new es_ES enum value to the / response property for the response status

    • info

      added the new optional header request parameter X-Company-Id

    • info

      added the new DE_intracom_exempt_BU0233 enum value to the request property ///

    • info

      added the new ES_intracom_sales_goods enum value to the request property ///

    • info

      added the new ES_intracom_sales_services enum value to the request property ///

    • info

      added the new ES_isp_purchases_100 enum value to the request property ///

    • info

      added the new ES_isp_purchases_210 enum value to the request property ///

    • info

      added the new ES_isp_sales enum value to the request property ///

    • info

      added the new ES_suplido enum value to the request property ///

    • info

      added the new VES enum value to the request property /

    • info

      added the new es_ES enum value to the request property /