Billing Integration Apex

Billing Integration Apex

Use this skill when writing Apex code that calls the Salesforce Billing managed package APIs — blng.InvoiceAPI, blng.TransactionAPI, or the Connect REST API commerce/invoices endpoint — to programmatically generate invoices, drive payment gateway lifecycles, or automate credit note issuance. This skill does NOT cover admin configuration of billing rules, billing treatments, invoice run scheduling, or tax policies.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the Salesforce Billing managed package is installed and the blng__ namespace is present in the target org. All Billing sObjects use this namespace (e.g., blng__Invoice__c, blng__BillingSchedule__c, blng__Payment__c).
• Identify the API version. The Connect REST API POST /services/data/vXX.0/commerce/invoices endpoint requires API version 63.0 or later (Spring '25+).
• The most common wrong assumption: calling blng.TransactionAPI methods in the same synchronous transaction that also performs DML. TransactionAPI methods execute HTTP callouts internally; mixing callouts with uncommitted DML causes a System.CalloutException: You have uncommitted work pending. Please commit or rollback before calling out error. All TransactionAPI calls must run in an async context with no pending DML.
• Platform constraint: a single Connect REST API invoice generation call accepts a maximum of 200 blng__BillingSchedule__c IDs per request.

Core Concepts

blng.InvoiceAPI — Credit Operations

blng.InvoiceAPI is the managed-package Apex API for credit-side invoice operations. Its primary use is issuing credit notes against existing invoices. Credit notes create offsetting blng__Invoice__c records and adjust the outstanding balance on related billing schedules. The method signature follows the pattern of accepting an invoice ID and returning a result object. Credit note generation does not trigger HTTP callouts, so it can be called in a standard synchronous transaction alongside DML.

blng.TransactionAPI — Payment Gateway Lifecycle

blng.TransactionAPI is the managed-package Apex API for driving the full payment transaction lifecycle. It exposes the following methods:

Every one of these methods executes an HTTP callout to the configured payment gateway. Because Salesforce enforces the rule that callouts cannot be made after DML in the same transaction, all TransactionAPI calls must be isolated in an asynchronous context. Use a Queueable class implementing Database.AllowsCallouts, or a @future(callout=true) method. Queueable is preferred because it is chainable, testable with Test.startTest()/stopTest(), and supports Database.AllowsCallouts explicitly.

Connect REST API — Programmatic Invoice Generation

Salesforce Billing exposes a Connect REST API endpoint for programmatic invoice generation outside the standard batch Invoice Run:

POST /services/data/v63.0/commerce/invoices

This endpoint accepts a request body containing either:

• accountId — generate invoices for all eligible billing schedules under that account, or
• billingScheduleIds — an array of specific blng__BillingSchedule__c IDs (maximum 200 per call)

The endpoint requires API version 63.0 or later. Calls are made via HttpRequest/Http in Apex or via named credentials pointing to the org itself (self-callout pattern). Because this is an HTTP callout, the same DML constraint applies: it must be called from an async context if the same transaction includes DML.

Payment Gateway Adapter Interface

To integrate a custom payment gateway (one not natively supported by Salesforce Billing), implement the blng.PaymentGateway interface. This interface defines the contract that the Billing package calls when routing transactions through your custom gateway. The implementing class is registered in the org's Payment Gateway configuration record (blng__PaymentGateway__c) by setting the blng__GatewayType__c field to reference the Apex class. The Billing package then invokes the interface methods during transaction lifecycle calls, passing request objects and expecting response objects defined within the blng namespace.

Common Patterns

Pattern: Async Payment Transaction via Queueable

When to use: When a trigger, flow-invoked action, or controller needs to authorize, capture, or charge a payment but the calling context may have uncommitted DML or is synchronous.

How it works:

1. Collect the payment record ID and desired operation in the calling context.
2. Enqueue a Queueable class implementing Database.AllowsCallouts.
3. Inside execute(), call the appropriate blng.TransactionAPI method with no preceding DML.
4. Persist the result (success/failure, gateway reference ID) to a custom field or a related record as the only DML in the job.

Why not the alternative: Calling blng.TransactionAPI synchronously from a trigger or a batch execute() method that has already performed DML causes an immediate CalloutException. The @future(callout=true) pattern works but cannot be chained or easily unit-tested; Queueable is preferred.

Pattern: Batched Invoice Generation via Connect REST API

When to use: When you need to programmatically trigger invoice generation for a known set of billing schedules outside the standard Invoice Run batch schedule.

How it works:

1. Query the blng__BillingSchedule__c IDs to process.
2. Chunk the IDs into lists of no more than 200.
3. For each chunk, build an HttpRequest to POST /services/data/v63.0/commerce/invoices with a JSON body containing billingScheduleIds.
4. Call from an async context (Queueable with Database.AllowsCallouts) to avoid DML conflicts.
5. Parse the response to identify any failed schedule IDs and retry or log them.

Why not the alternative: Invoking the standard Invoice Run batch from Apex (blng.InvoiceRunAPI) processes all eligible schedules and cannot be scoped to a specific subset without filtering logic inside the batch itself; the Connect REST API gives precise control.

Pattern: Custom Payment Gateway Adapter

When to use: When the organization uses a payment processor not natively supported by Salesforce Billing and needs full lifecycle control (tokenise, authorize, capture, void, refund).

How it works:

1. Create an Apex class implementing blng.PaymentGateway.
2. Implement each required interface method; translate incoming Billing request objects to your gateway's API format, execute the HTTP callout, and map the response back to Billing response objects.
3. Register the class name in the blng__PaymentGateway__c record's blng__GatewayType__c field.
4. Billing's TransactionAPI methods will automatically route through your adapter when that gateway is selected on a payment record.

Why not the alternative: Directly calling the gateway from a custom trigger on blng__Payment__c bypasses the Billing transaction lifecycle, preventing correct status management and reconciliation.

Decision Guidance

Recommended Workflow

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

1. Confirm prerequisites — Verify the blng__ managed package namespace is present in the org and that the target API version is 63.0 or later. Identify whether the requirement is invoice generation, payment transaction management, credit note issuance, or custom gateway integration.
2. Check transaction context — Determine whether the calling context (trigger, batch, invocable, controller) performs DML before the billing API call. If any DML precedes a blng.TransactionAPI call or a Connect REST API callout, refactor the callout into an async context (Queueable implementing Database.AllowsCallouts is preferred over @future).
3. Implement the Apex class — For TransactionAPI usage, write a Queueable class. For blng.InvoiceAPI, write synchronous Apex. For the Connect REST API, build the HttpRequest with the correct endpoint, API version, and JSON body. For custom gateways, implement the blng.PaymentGateway interface.
4. Handle the 200-schedule limit — If generating invoices for more than 200 billing schedules, implement chunking logic before calling the Connect REST API. Use a Queueable chain or Batch Apex to process each chunk sequentially.
5. Write tests with mock callouts — Use HttpCalloutMock for TransactionAPI and Connect REST API tests. Ensure Test.startTest()/stopTest() wraps Queueable enqueues. Test both success and gateway-error response paths.
6. Validate output records — After execution, query blng__Invoice__c for invoice generation tests, blng__Payment__c / blng__PaymentGatewayLog__c for transaction tests, and confirm status fields reflect the expected lifecycle state.
7. Review checklist below — Confirm no uncommitted DML precedes callouts, namespace usage is correct, and API version is enforced in all endpoint URLs.

Review Checklist

Run through these before marking work in this area complete:

• All blng.TransactionAPI calls are in a Queueable implementing Database.AllowsCallouts or in a @future(callout=true) method — no synchronous context with preceding DML
• Connect REST API endpoint URL contains the correct API version (v63.0 or later)
• Invoice generation calls contain no more than 200 billingScheduleIds per request; chunking logic exists for larger sets
• All Billing sObject references use the blng__ namespace prefix (e.g., blng__Invoice__c, not Invoice__c)
• Test classes use HttpCalloutMock for all callout-dependent paths; no live callouts in tests
• Custom gateway adapter class is registered on the blng__PaymentGateway__c record's blng__GatewayType__c field
• Error handling captures gateway response codes and persists failure details to a log record or platform event for observability

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. TransactionAPI callout + uncommitted DML — Calling any blng.TransactionAPI method in a transaction that has uncommitted DML (including inserts, updates, or deletes that have not been committed) immediately throws System.CalloutException: You have uncommitted work pending. This is a Salesforce platform constraint, not a Billing-specific one, but it catches developers who write trigger-based payment logic without async offloading.
2. 200 billing schedule hard limit on Connect REST API — The POST /commerce/invoices endpoint rejects requests containing more than 200 entries in the billingScheduleIds array. There is no soft warning; the call fails. Implement explicit chunking before calling the endpoint when processing large volumes.
3. blng__ namespace on all managed package references — Omitting the blng__ prefix on any Billing sObject field or class reference causes a compile-time or runtime error. This applies to SOQL queries (SELECT blng__InvoiceStatus__c FROM blng__Invoice__c), DML operations, and field API name references. The blng.InvoiceAPI and blng.TransactionAPI classes use the blng namespace prefix without the double underscore — that is the Apex class namespace, distinct from the sObject namespace convention.
4. API version enforcement on commerce/invoices endpoint — Calling the Connect REST API commerce/invoices endpoint with an API version below 63.0 returns a 404 or unsupported resource error. Hard-code the version in named credential URL overrides or endpoint strings, and document the minimum version requirement in the class header.
5. Gateway adapter interface changes across managed package versions — The blng.PaymentGateway interface is defined inside the managed package. Upgrading the Billing package can add new required interface methods, breaking existing adapter classes with compile errors until they are updated. Pin the package version in sandbox before upgrading production when custom adapters are in use.

Output Artifacts

Related Skills

• callout-and-dml-transaction-boundaries — Core platform rule this skill depends on; read before writing any TransactionAPI code
• apex-queueable-patterns — Patterns for Queueable chaining and error handling relevant to batched invoice generation
• callouts-and-http-integrations — HTTP callout patterns, named credentials, and mock strategies used for Connect REST API calls
• admin/billing-schedule-setup — Admin skill for configuring the billing rules and schedules that this skill operates on programmatically

Official Sources Used

• Salesforce Billing Developer Guide — InvoiceAPI Class: https://developer.salesforce.com/docs/atlas.en-us.billing.meta/billing/billing_dev_invoice_api.htm
• Salesforce Billing Developer Guide — TransactionAPI Class: https://developer.salesforce.com/docs/atlas.en-us.billing.meta/billing/billing_dev_transaction_api.htm
• Salesforce Billing Developer Guide — Payment Gateway Adapter: https://developer.salesforce.com/docs/atlas.en-us.billing.meta/billing/billing_dev_gateway_adapter.htm
• Connect REST API — Create Invoices: https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_invoices.htm
• Apex Developer Guide — Callouts and DML: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_dml.htm