Billing plan webhook (Back Office legacy)

Back Office webhook (legacy)

This article applies only to the legacy registration configured in Settings > Webhook. New Public API registrations use /api/v2/management/webhook-registrations/ and follow the V2 payload reference. Existing V1 registrations keep their historical contract.

Overview

The Billing Plan webhook sends an event when a subscription billing plan is created or updated. It is used to synchronize subscription state, billing schedule changes, and payment configuration with external systems.

Who It Is For

• Teams syncing subscription lifecycle into finance or CRM tools.
• Operations teams managing pauses, renewals, and payment method changes.
• Support teams troubleshooting recurring billing behavior.

Supported Events

• billing_plan-create: sent when a member subscribes to a contract.
• billing_plan-update: sent when an existing billing plan changes.

Common billing_plan-update triggers include:

• Pause or resume actions.
• Cancellation updates.
• Payment method changes.
• Plan-level billing schedule updates.

Inspect an existing registration

1. Open https://backoffice.bsport.io/settings/webhook.
2. Locate the existing billing plan registration.
3. Verify its event and destination before planning the migration.

Do not create a new Back Office registration. New integrations must use the Public API event catalogue; billing plan events are not yet available there.

Payload Envelope

{
  "event_type": "billing_plan-update",
  "date": 1721640025,
  "data": {
    "billing_plan": {}
  }
}

Data Fields

Field	Type	Description	Example
event_type	string	Billing plan webhook event name.	"billing_plan-update"
date	number	Unix timestamp when event was emitted.	1721640025
data.billing_plan.id	number	Billing plan unique id.	1
data.billing_plan.member	number	Member id owning the billing plan.	32
data.billing_plan.contract	number or null	Contract template id used for subscription.	null
data.billing_plan.name	string	Billing plan display name.	"Suscripcion ilimitada - 5 meses : Kiko Femenia"
data.billing_plan.status	number	Current plan status code.	1
data.billing_plan.payment_method	number or string	Payment method code used for billing.	0
data.billing_plan.payment_method_identifier	number	Payment method identifier in payment layer.	1
data.billing_plan.recurrent_price	string	Recurring amount configured.	"40.00"
data.billing_plan.first_billing_date	string (date-time)	First billing datetime.	"2020-08-17T08:36:22.879330Z"
data.billing_plan.next_billing_date	string (date-time)	Next planned billing datetime.	"2020-08-17T08:36:22.879330Z"
data.billing_plan.auto_renewal	boolean	Whether plan auto renews.	false
data.billing_plan.planned_invoices	array	Planned invoice schedule details.	[{...}]
data.billing_plan.pauses	array	Pause periods configured on plan.	[]
data.billing_plan.has_discount	boolean	Whether a discount is active on the plan.	false
data.billing_plan.month_billing_day	number or null	Fixed monthly billing day when applicable.	null
data.billing_plan.memberArchived	boolean	Whether related member is archived.	false

Common nested fields:

• planned_invoices[]: uuid, id, date, status, price, billing_plan, name, contract, payment_method, member, is_last_invoice_before_scheduled_stop, amount_due_cts, reverted, invoice_legal_identifier
• pauses[]: date_created, date_ended, id, days, name, first_paused_planned_invoice, billing_plan, creator_staff_name, from_date, until_date, version, contract_pause

Example Payload

{
  "event_type": "billing_plan-update",
  "date": 1721640025,
  "data": {
    "billing_plan": {
      "id": 1,
      "name": "Suscripcion ilimitada - 5 meses : Jane Doe",
      "name_without_member_name": "Suscripcion ilimitada",
      "member": 32,
      "memberName": "Jane Doe",
      "legal_contract": "",
      "contract": null,
      "description": "Nueva oferta ilimitada",
      "interval": "month",
      "recurrence_basis": 1,
      "nb_interval": 5,
      "recurrent_price": "40.00",
      "payment_method": 0,
      "payment_method_identifier": 1,
      "payment_engine": 1,
      "stripe_payment_method_id": "",
      "canceled_at": null,
      "date_created": "2020-08-17T10:36:23.379794+02:00",
      "first_billing_date": "2020-08-17T08:36:22.879330Z",
      "next_billing_date": "2020-08-17T08:36:22.879330Z",
      "has_ended": false,
      "editable": true,
      "planned_invoices": [
        {
          "uuid": "b09bcd48-f030-4aa0-af96-50dc9d729447",
          "id": 1,
          "date": "2020-08-17T10:36:22.879330+02:00",
          "status": 2,
          "price": 40,
          "billing_plan": 1,
          "name": "Suscripcion ilimitada - 5 meses : Jane Doe",
          "contract": null,
          "payment_method": "0",
          "member": 32,
          "is_last_invoice_before_scheduled_stop": false,
          "amount_due_cts": "0.00",
          "reverted": false,
          "invoice_legal_identifier": ""
        }
      ],
      "pauses": [
        {
          "date_created": "2022-10-05T06:10:38.431051-04:00",
          "date_ended": "2022-10-20T06:10:38.428676-04:00",
          "id": 21751,
          "days": 15,
          "name": "Pause",
          "first_paused_planned_invoice": null,
          "billing_plan": 24200,
          "creator_staff_name": "Stadd",
          "from_date": "2022-12-09",
          "until_date": "2022-12-23",
          "version": "v2",
          "contract_pause": 146
        }
      ],
      "auto_renewal": false,
      "payment_pack": 4,
      "is_v2": true,
      "private_pass": null,
      "payment_combo": null,
      "flat_fee": "0.00",
      "started_at": "2020-08-17T10:36:27.117989+02:00",
      "status": 1,
      "note": "",
      "stop_note": "",
      "memberArchived": false,
      "contract_terms_date_accepted": null,
      "contract_terms_pdf_link": null,
      "month_billing_day": null,
      "has_discount": false,
      "member_relation_auto_share": false,
      "has_changed_after_renewal": false,
      "nb_interval_after_auto_renewal": null
    }
  }
}

Delivery, Reliability, And Security

• Your endpoint must accept POST over HTTPS.
• A documented retry policy is not currently specified in this guide.
• Event ordering guarantees are not currently documented.
• Signature verification headers are not currently documented.

Implementation approach:

• Handle events idempotently by billing plan id.
• Keep historical snapshots for state transitions and pause windows.
• Reconcile planned invoices periodically if your finance process is strict.

Troubleshooting

• Missing event: verify exact event type selection in Back Office.
• Unexpected status changes: review pause and planned invoice nested arrays.
• Payment method mismatch: validate both payment_method and payment_method_identifier mappings.

FAQ

Does one update event represent many business changes?

Yes. billing_plan-update can represent multiple kinds of changes, including pauses, cancellation, and payment-related updates.

Should I depend only on one status field?

No. Use status together with billing dates, pause windows, and planned invoices to interpret billing lifecycle accurately.