Sign in

v1

latestOpenAPI 3.0.12026-07-141671231.8 MB
Billing Subscriptions

Update a billing subscription

Update a billing subscription

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

put/api/external/v2/billing_subscriptions/{id}

Path parameters

idinteger required
Example:42

The ID of the billing subscription to retrieve

Request body

stopboolean

To stop an in_progress billing subscription use value true. To resume a stopped billing subscription use value false

payment_conditions'upon_receipt' | '7_days' | '15_days' | '30_days' | '30_days_end_of_month' | '45_days' | '45_days_end_of_month' | '60_days'
payment_method'offline' | 'gocardless_direct_debit' | 'pro_account_sepa_core'

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

Customer identifier

Example request

{
  "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": {
      "create": [
        {
          "title": "Invoice line section title",
          "description": "Invoice line section description",
          "rank": 1
        }
      ],
      "update": [
        {
          "id": 12,
          "title": "Invoice line section title",
          "description": "Invoice line section description",
          "rank": 1
        }
      ],
      "delete": [
        {
          "id": 12
        }
      ]
    },
    "invoice_lines": {
      "create": [
        {
          "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
        }
      ],
      "update": [
        {
          "id": 42,
          "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
        }
      ],
      "delete": [
        {
          "id": 42
        }
      ]
    }
  }
}

Response

Renders the updated 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"
}