billing-schedule-setup

# Billing Schedule Setup

This skill activates when a practitioner needs to configure Salesforce Billing (blng__ namespace) billing schedules, invoice plans, billing policies, or billing treatments — from initial Legal Entity setup through Invoice Run execution. It covers In-Advance, In-Arrears, Evergreen, Milestone, and Dynamic Invoice Plan schedule types.

---

## Before Starting

Gather this context before working on anything in this domain:

- Confirm the Salesforce Billing managed package (namespace prefix `blng__`) is installed. Salesforce Billing is a separate managed package layered on top of Salesforce CPQ — it is not part of core Salesforce or CPQ alone.
- Confirm **Data Pipelines is enabled** in the org (Setup > Data Pipelines). This is a hard platform dependency: without it, the Billing package cannot create billing schedule records even if all configuration is correct.
- Identify the required schedule type (In-Advance, In-Arrears, Evergreen, Milestone, or Dynamic Invoice Plan) — this determines configuration path and invoice run behavior.
- Confirm the OrderProducts are CPQ-sourced (via Quote > Order flow), not manually created — manually created Orders bypass CPQ fields required by Billing.
- Know the billing period (Monthly, Quarterly, Annually, Custom) and billing day-of-month required by the business.

---

## Core Concepts

### Billing Lifecycle: Order Activation Creates blng__BillingSchedule__c

The Salesforce Billing lifecycle begins when an Order is activated. At activation, the Billing package creates one `blng__BillingSchedule__c` record per OrderProduct that has a valid Billing Rule reference. Each `blng__BillingSchedule__c` holds the projected charge dates and amounts for that product's billing period. These records are auto-generated — do not create them manually.

The configuration chain that must be in place before Order activation:

```
Legal Entity → Billing Policy → Billing Treatment → Tax Policy → (Invoice Plan if Dynamic)
```

Each link in this chain is a lookup on the previous object. Missing any one link prevents billing schedule generation or invoice creation.

### Schedule Types and Their Behavior

Salesforce Billing supports five schedule types, each controlled by the `blng__BillingType__c` field on `blng__BillingRule__c`:

| Type | Invoice Timing | Manual Trigger Required | Notes |
|---|---|---|---|
| In-Advance | Invoice issued before service period | No | Default for most subscription SaaS |
| In-Arrears | Invoice issued after service period ends | No | Calculates from actual usage period end date |
| Evergreen | Rolls forward each period indefinitely | No | No end date; must explicitly cancel |
| Milestone | Invoice issued at milestone completion | Yes | Admin or Apex must trigger invoice run per milestone |
| Dynamic Invoice Plan | Custom date-driven schedule | No | Requires separate Invoice Plan record |

The most commonly misconfigured: **Milestone billing** — practitioners expect it to fire automatically but it requires a manual Invoice Run scoped to the milestone date.

### Invoice Run: Batch Processing and Governor Limits

Invoice Runs (`blng__InvoiceRun__c`) are the mechanism that aggregates `blng__BillingSchedule__c` items into `blng__Invoice__c` records. Invoice Runs execute as batch jobs, processing approximately **300 billing schedule lines per batch chunk** to stay within Salesforce governor limits. For orgs with thousands of order products, this means a single Invoice Run may spawn many batch iterations.

Key Invoice Run fields:
- `blng__InvoiceDate__c` — the date that appears on the invoice header
- `blng__TargetDate__c` — the cutoff date; only schedule items on or before this date are processed
- `blng__Status__c` — Posted, Canceled, Draft; only Draft runs can be modified

### blng__BillingSchedule__c vs blng__RevenueSchedule__c vs OpportunityLineItem Revenue Schedules

These are three entirely different constructs:

- `blng__BillingSchedule__c` — Salesforce Billing managed package object; one per OrderProduct; controls invoice generation
- `blng__RevenueSchedule__c` — Salesforce Billing managed package object; controls revenue recognition timing (separate from billing timing)
- OpportunityLineItem Revenue Schedule — standard Salesforce feature for splitting opportunity revenue; has no integration with the Billing package

Do not conflate these. Enabling "Revenue Schedules" in standard Salesforce Setup is unrelated to and does not replace `blng__RevenueSchedule__c`.

---

## Common Patterns

### Pattern 1: Standard Subscription Billing (In-Advance, Monthly)

**When to use:** A subscription product should invoice at the start of each monthly period.

**How it works:**
1. Create a `blng__BillingRule__c` with `blng__BillingType__c = In-Advance`, `blng__BillingDayOfMonth__c = 1` (or contract start day), `blng__InitialBillingDate__c` logic set to Order Start Date.
2. Create a `blng__RevenueRecognitionRule__c` if revenue recognition is required.
3. On the Product2 record, set the `blng__BillingRule__c` lookup to the new rule.
4. Ensure a Billing Policy exists with a Legal Entity and Tax Policy attached.
5. Ensure the Billing Policy is set on the Account record (`blng__BillingPolicy__c` lookup on Account).
6. Activate the Order — `blng__BillingSchedule__c` records are created automatically.
7. Run an Invoice Run with `blng__TargetDate__c` set to today or the desired billing date.

**Why not the alternative:** Manually creating `blng__BillingSchedule__c` records bypasses Billing Rule logic and produces orphaned records that Invoice Runs cannot reliably pick up.

### Pattern 2: Milestone Billing for Professional Services

**When to use:** A services engagement invoices at project milestone completion (e.g., 30% at kickoff, 40% at delivery, 30% at acceptance).

**How it works:**
1. Set `blng__BillingType__c = Milestone` on the `blng__BillingRule__c`.
2. Define milestone amounts on the `blng__BillingSchedule__c` child records (created at Order activation).
3. When a milestone is achieved, update the milestone record's status to indicate completion.
4. Manually trigger an Invoice Run scoped to the milestone date — the run will only process lines where the milestone status is complete and the date is on or before `blng__TargetDate__c`.

**Why not the alternative:** Using In-Advance for milestone billing creates invoices on fixed calendar dates regardless of project status, violating contract terms and creating disputes.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| SaaS subscription, invoice before each period | In-Advance billing schedule | Matches standard subscription contract terms; invoices auto-generate |
| Usage-based billing, invoice after metering | In-Arrears billing schedule | Arrears calculates from actual period end; supports usage data import |
| Month-to-month with no defined end date | Evergreen billing schedule | No termination date required; rolls forward indefinitely until canceled |
| Professional services with milestone gates | Milestone billing with manual Invoice Run | Prevents premature invoicing; admin controls when each invoice fires |
| Complex custom schedule (variable amounts by date) | Dynamic Invoice Plan | Supports arbitrary date/amount combinations outside period-based logic |
| Need to invoice multiple order products on one invoice | Single Invoice Run with shared Invoice Date | Invoice Run aggregates multiple schedule items into one blng__Invoice__c per Account |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Verify prerequisites** — Confirm Salesforce Billing (blng__) is installed, Data Pipelines is enabled, and the org has at least one CPQ-sourced Order in Draft status. Check that the Account has a `blng__BillingPolicy__c` value set.
2. **Build the configuration chain** — In order: create or confirm Legal Entity (`blng__LegalEntity__c`), then Billing Policy (`blng__BillingPolicy__c`) linked to the Legal Entity and Tax Policy, then Billing Treatment (`blng__BillingTreatment__c`) linked to the Billing Policy. Do not skip steps or reorder.
3. **Configure Billing Rules on Products** — Set `blng__BillingRule__c` on each Product2 record. Select the schedule type (In-Advance, In-Arrears, Evergreen, Milestone). Set billing period and day-of-month fields to match contract terms.
4. **Activate the Order** — Change Order Status to Activated. Confirm that `blng__BillingSchedule__c` records are created — one per OrderProduct. If records are missing, check Data Pipelines status and Billing Rule linkage.
5. **Create and submit an Invoice Run** — Create a `blng__InvoiceRun__c` with `blng__InvoiceDate__c` and `blng__TargetDate__c` set correctly. Set Status to Posted to execute. Monitor the batch job in Setup > Apex Jobs for completion.
6. **Validate invoices** — Confirm `blng__Invoice__c` records are created with correct amounts, invoice dates, and line items. Confirm `blng__BillingSchedule__c` records show the expected next billing date.
7. **For Milestone billing only** — After each milestone completes, manually trigger a scoped Invoice Run. Confirm that only the completed milestone lines are invoiced; future milestones must remain uninvoiced.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Data Pipelines is enabled in Setup (hard dependency confirmed)
- [ ] Legal Entity, Billing Policy, Billing Treatment, and Tax Policy are all created and linked in the correct order
- [ ] Every Product2 in scope has a `blng__BillingRule__c` lookup populated with the correct schedule type
- [ ] The Account record has `blng__BillingPolicy__c` set to the correct Billing Policy
- [ ] `blng__BillingSchedule__c` records were auto-generated upon Order activation (no manual records)
- [ ] Invoice Run `blng__TargetDate__c` is set to capture all intended billing schedule items
- [ ] Invoice Run batch completed without errors (check Setup > Apex Jobs)
- [ ] `blng__Invoice__c` records show correct amounts, line counts, and invoice dates
- [ ] Milestone billing: only completed milestones have been invoiced; future milestones are still pending

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Data Pipelines is a silent hard dependency** — If Data Pipelines is not enabled, the Billing package installs successfully and the UI shows no errors, but `blng__BillingSchedule__c` records are never created when Orders activate. The failure is silent — no error is thrown, no record is created. Always verify Data Pipelines is enabled before debugging any "missing billing schedule" issue.
2. **Billing Policy must be on the Account, not the Order** — Many practitioners set the Billing Policy lookup on the Order directly, expecting it to drive invoice generation. The billing engine reads `blng__BillingPolicy__c` from the Account record, not the Order. Setting it only on the Order has no effect.
3. **Invoice Run Target Date is a hard cutoff, not a range** — An Invoice Run processes all billing schedule items where the next billing date is on or before `blng__TargetDate__c`. If `blng__TargetDate__c` is set to yesterday, items scheduled for today are excluded. Practitioners expecting to invoice "through today" must set target date to today, not yesterday.
4. **In-Arrears calculates from period end, not run date** — In-Arrears billing schedule amounts are finalized based on the actual service period end date stored on the schedule item, not the date the Invoice Run executes. Running the Invoice Run early does not change the invoice amount or date — the run simply skips items whose period has not yet ended.
5. **Manually created blng__BillingSchedule__c records are not invoice-run-eligible** — The Invoice Run engine has internal validation that marks billing schedule items as engine-created. Records created via Data Loader, Flow, or Apex that bypass the Order activation trigger are treated as invalid by the Invoice Run and silently skipped.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| `blng__LegalEntity__c` record | Top of the configuration chain; required before Billing Policy can be created |
| `blng__BillingPolicy__c` record | Links Legal Entity and Tax Policy; set on Account to drive billing behavior |
| `blng__BillingTreatment__c` record | Child of Billing Policy; defines how the policy applies to specific billing scenarios |
| `blng__BillingRule__c` record | Set on Product2; defines schedule type, billing period, and day-of-month |
| `blng__BillingSchedule__c` records | Auto-generated per OrderProduct at Order activation; source of truth for invoice timing |
| `blng__InvoiceRun__c` record | Triggers batch processing of billing schedule items into invoices |
| `blng__Invoice__c` records | Aggregated invoice documents sent to customers |

---

## Related Skills

- `admin/products-and-pricebooks` — Configure Product2 records and price book entries before Billing Rules can be applied
- `admin/batch-job-scheduling-and-monitoring` — Monitor Invoice Run batch jobs in Setup > Apex Jobs and diagnose batch failures