Skip to content

Billing Request Templates

Billing Request Templates allow merchants to preconfigure their VRP consent caps in GoCardless and reuse the template when starting new customer authorisations. When a template is stored on the merchant, the API will reference it automatically instead of sending ad-hoc constraints with each request.

Portal configuration

Merchant owners can manage the template from Merchant Portal → Settings:

  1. Enter an existing GoCardless template ID (e.g. BRT123) and optional metadata JSON to cache the latest template details.
  2. Or create a new sweeping template directly from the portal. The form collects per-payment and periodic limits, then calls billing_request_templates.create via the merchant's GoCardless credentials. The returned template ID and metadata are persisted on the merchant.

Any cached metadata is displayed read-only so teams can audit the stored caps. Clearing the template removes both the ID and metadata.

Management command

A management command is available for operational tasks:

python manage.py refresh_billing_request_templates <merchant_id> [--template-id BRT123] [--refresh]
  • Without extra flags the command lists available templates for the merchant.
  • --template-id fetches the specified template, stores the ID on the merchant and saves the metadata payload.
  • --refresh re-fetches metadata for the currently stored template ID.

The command prints the cached metadata as formatted JSON so that changes can be inspected during support or onboarding calls.

API behaviour

POST /api/v1/vrp/mandates now prefers the stored template when one is available:

  • If a merchant has set gc_billing_request_template_id, the API requests a billing request using template.links.billing_request_template and attaches the cached metadata description.
  • When no template is configured, the endpoint falls back to the explicit constraints payload supplied by the caller (legacy behaviour).

This approach keeps idempotency guarantees—template IDs are included in the idempotency fingerprint—and ensures VrpMandate.constraints is populated using either the template metadata or the supplied constraints for downstream reporting.

  1. Use the portal bootstrap form (or the management command) to create a sweeping template with agreed limits.
  2. Optionally sync metadata from GoCardless using the management command to capture any future edits.
  3. Verify the stored caps in Portal → Settings under “Stored template metadata”.
  4. Integrate create_vrp_mandate without providing constraints; the API will inject the configured template ID.

By centralising the template ID, merchant teams can adjust caps without code changes while the API continues to operate safely with consistent metadata.