Stripe Billing flows configuration

These flows consist of a primary flow and several subflows that work together in a composable manner to automate subscription management. They primarily serve as a catalyst for building sales-assisted workflows that connect Salesforce processes with Stripe subscriptions. Because this is an unmanaged package:

• Automation flows can be cloned or extended to fit your business processes
• Individual subflows can be repurposed as primary flows for custom record triggers or conditions
• Default object and field mappings can be modified to fit your specific implementation
• Existing automation flows can also be extended or updated to support additional pricing models

Default Flow Configuration Settings

The pre-built flows implement several key configurations and design choices, including:

• Primary Objects: Works with Salesforce Orders and Contract objects as the core entities
• Object Relationship: Orders and Contracts are related, where subscription details are synced back to both objects after creation
• Amendment Handling: When a new Order is created within the same Contract, the default flows treat it as an amendment to the existing subscription
• Pricing Structure: Flat rate recurring pricing model
• Trigger Mechanism: Automation triggered by Salesforce Order object activation
• Line Item Handling: Order items automatically map to phases in Stripe subscription schedules
• Price Reference Method: Enforces to use price_id instead of price_data to favor accurate reporting
• Price Source: Defaults to price_id synchronized with Salesforce Standard Price Book Entry (for custom pricing, price_id can be referenced from Order Product or the object of your choice)
• Metadata Handling: Metadata passing is controlled by the Subscription Scheduler Manager class and can be customized either by refactoring this class or by adding an update subscription action in the primary flow to pass additional metadata
• Timezone/Date Time Consideration: All date fields are formatted as Unix timestamps (in seconds) for the Stripe API request, which are inherently based on UTC. If a mapped source field is a Salesforce Date (with no time), the system defaults the time to 00:00:00 UTC (midnight UTC) for that date. If a DateTime field is used, its UTC equivalent is used.

Core Flow Implementation

Stripe Account Selection

All flow operations require a Stripe Account to be selected. The Create or Update Stripe Subscription Schedule when Order is Activated flow provides a simple method out-of-the-box, using a query to find a Stripe Account by its Name.

For a more robust and dynamic approach, we recommend creating a custom lookup field from your Order or Contract object to the Stripe_Account__c object. This allows you to reference the specific account directly in the flow.

Regardless of the method, you must provide the Salesforce Record ID of the Stripe_Account__c record to the Stripe Account input in the Subscription Schedule Manager.

Configuring Discounts

The flows allow you to apply discounts at both the Subscription Phase and Subscription Phase Item level using two simplified fields:

• Discount Amount Off
• Discount Percent Off

When you provide a non-zero value for either of these fields, the system automatically creates a new Stripe Coupon with Max Redemptions set to 1 and applies it to the corresponding phase or item.

Note on Updates and Amendments

When you perform an Update or Amend operation, the flow creates new Stripe Coupons based on the values provided. This is for simplicity and idempotency, as it avoids the need to track and manage existing Stripe Coupon IDs in Salesforce. The provided discount value is always treated as the total discount for that phase or item at the time of the update.

Subscription Phase Consolidation

A key feature of the automation is its ability to consolidate multiple Salesforce OrderItems into a linear series of Stripe Subscription Phases. Stripe’s API requires that subscription phases are discrete and linear—one phase ends at the exact moment the next one begins, with no gaps or overlaps.

Salesforce Orders don’t have this constraint. For example, you could have two OrderItems with overlapping service dates:

• Product A: Jan 1, 2025 - Jan 1, 2026
• Product B: June 1, 2025 - Jan 1, 2026

The flow logic automatically consolidates these into two distinct, linear phases for Stripe:

• Phase 1: Jan 1, 2025 - June 1, 2025 (Includes only Product A)
• Phase 2: June 1, 2025 - Jan 1, 2026 (Includes Product A + Product B)

• Property Mismatches: If two overlapping phases have different properties (e.g., one has collection_method set to send_invoice and the other to charge_automatically), the flow cannot resolve the conflict and will throw an error.

• Quantity Mismatches: If two phases with the same product overlap but have different quantities, the flow will throw an error.

Additional Subscription Schedule Settings

You can configure several advanced settings in the Additional Subscription Schedule Settings section of the flow action.

• Stripe Connected Account ID: If you are performing this request on behalf of a connected account, provide the Stripe ID (e.g., acct_...) here.
• Idempotency Key: To ensure idempotent requests, you can provide a unique key. The recommended approach is to use the flow interview GUID: {!$Flow.InterviewGUID}.
• Ignore Billing Sync Event Processing: Set this to true to prevent the Stripe Billing Data event import process from running for events generated by this operation. This is useful for preventing recursive loops if you have triggers on the Stripe Billing Data custom objects.
• Perform DML Save After Calls: This flag controls whether the flow commits database saves (e.g., creating Sync_Log__c records, upserting Stripe Billing objects) after the callouts are complete.

Setting up and Activating the Flows

The package includes sample flow templates that are disabled by default. These flows are intended as a starting point and are not guaranteed to fit all business needs. You can activate them directly or clone them to customize the logic. To activate a flow, navigate to Setup → Flows, select the record trigger flow, and click Activate.

Record-Triggered Flows

These flows trigger automatically based on record changes in Salesforce:

Create or Update Stripe Subscription Schedule when Order is Activated

This is the primary flow. When an Order record is activated, it either creates a new Stripe Subscription Schedule or updates an existing one.

• Synchronous Path: The flow first checks if the Contract associated with the Order already has a Stripe Subscription Schedule ID. If it does, it copies that ID to the Order record, preparing it for an update.

• Asynchronous Path: The flow runs asynchronously (to perform the API callout) and checks if the Order has a Subscription Schedule ID.

  • If YES, it calls the Update Stripe Subscription Schedule from Change Order subflow (treating it as an amendment).
  • If NO, it calls the Create Stripe Subscription Schedule from Order subflow.

• Implementation Note: Before activating, you must update the Get Stripe Account query element in the asynchronous path to fetch the Stripe Account you want to use.

Update Stripe Subscription Schedule when OrderItem is Updated

Triggers when an OrderItem record’s Quantity, ServiceDate, or EndDate is modified.

• Asynchronous Path: The flow checks if the parent Order has an associated Stripe Subscription Schedule. If it does, it calls the Update Stripe Subscription Schedule from Original Order subflow to sync the changes.

Sync Product2 when Stripe Product is Upserted

When a stripeGC__Product__c record is upserted in Salesforce (via Stripe’s data sync), this flow upserts a matching Salesforce Product2 record.

• Synchronous Path: Immediately calls the Get or Create Product2 from Stripe Product subflow.

Sync PricebookEntry when Stripe Price is Upserted

When a stripeGC__Price__c record is upserted, this flow upserts a matching Salesforce PricebookEntry record.

• Synchronous Path: Immediately calls the Get or Create PricebookEntry from Stripe Price subflow.

Autolaunched Flows (Subflows)

These flows are the core building blocks used by the record-triggered flows. They are enabled by default but can be cloned and modified. If you customize them, remember to update the record-triggered flows to call your new, cloned versions.

• Create Stripe Subscription Schedule from Order: Handles the logic for creating a new subscription schedule. It fetches the related Account (to use as the Stripe Customer) and OrderItems (to build the phases).

• Update Stripe Subscription Schedule from Change Order: Handles subscription amendments. This flow uses the Amend update type in the Stripe Subscription Schedule Manager action.

• Update Stripe Subscription Schedule from Original Order: Handles updates to an original order (e.g., when an OrderItem is changed). This flow uses the Replace update type, resending the entire picture of the subscription to Stripe.

• Cancel Stripe Subscription Schedule from Order: Cancels the subscription schedule associated with an Order.

• Get or Create Stripe Customer from Account: A reusable utility flow that finds or creates a Stripe Customer based on a Salesforce Account record.

• Get or Create... Product & Price Flows: Utility flows (…Stripe Product from Product2, ...Stripe Price from PricebookEntry, etc.) that handle the two-way sync of product and price data.