# Stripe Billing flows configuration

Learn how to configure the Stripe Billing flows extension

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.
![](https://b.stripecdn.com/docs-statics-srv/assets/create_update_subs_add_stripeacct.372cd1bab362f6805751564f66398825.png)

## 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-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)

> **Phase Consolidation Caveat for Gaps**: The logic will throw an error if a ***gap*** is detected between phases.

- **Property Mismatches**: If two overlapping phases have different properties (for example, one has collection_method set to send_invoice and the other to charge_automatically), the flow can’t 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’re performing this request on behalf of a connected account, provide the Stripe ID (for example, `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 (for example, creating `Sync_Log__c` records, upserting Stripe Billing objects) after the callouts are complete.
![](https://b.stripecdn.com/docs-statics-srv/assets/addnl_subs_flow_settings.d85ef49063bc98d4887576156849e87b.png)

## 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 aren’t 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’re 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 (for example, 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,` and so on) that handle the two-way sync of product and price data.