Prerequisites:
- Stripe account with Invoicing enabled
Connecting Stripe with Orb
if you’re already using Stripe as a payment gateway, you can skip this step, since the connection already exists.
- In the Orb dashboard, click the dropdown menu on the bottom left and navigate to Organization settings, navigate to the “Integrations” tab of the modal, and select Connect to Stripe
- Follow the instructions to connect Stripe
Mapping items
Mapping items to products in Stripe is required for the integration to succeed. If you do not map items, invoices will fail to issue. In Stripe, items are called Products, and can be found by searching for the product catalog. Create a product in Stripe for every item that you are selling in Orb. If you’d like Orb to also pull back any tax information from Stripe, select a tax treatment for the items. Then, navigate to the Items tab in Orb under Settings, and select a Stripe item for each Orb item.
Configuring customers
When creating or updating customers in the Orb UI, select Stripe as the Payment Provider in order to view a list of previously created customers in your Stripe account. Customer mappings can also be configured in the API, by passing in the customer’s Stripe ID underpayment_provider_id
, and setting payment_provider
to stripe_invoice
. Note that the payment provider here is stripe_invoice
. If you instead pass stripe_charge
, we will use Stripe as a payment gateway, and not as an invoicing provider.
The customer’s Stripe ID can be found on the customer page, and starts with the prefix cus_
.
Once mappings are configured, invoices for customers with a Stripe payment provider ID will be synced to Stripe Invoicing. For synced invoices, payment methods and invoice display are controlled with Stripe’s platform settings.
Invoice Metadata
When using Orb’s Stripe Invoice Sync, Orb automatically adds metadata to Stripe invoices to enable cross-referencing between Orb and Stripe invoice resources. This metadata is added to every synced invoice and can be accessed through Stripe’s API or dashboard. The following metadata fields are added to each Stripe invoice:Metadata Field | Description |
---|---|
payment_source | Always set to orb to identify invoices synced from Orb |
orb_invoice_id | The Orb invoice ID for cross-referencing |
orb_subscription_id | The Orb subscription ID, or empty if this is not a subscription invoice (e.g., one-off invoice) |
orb_customer_id | The Orb customer ID |
orb_external_plan_id | The Orb external plan ID, or empty if it does not exist |
orb_external_customer_id | The Orb external customer ID, or empty if the customer does not have an external customer ID |
- Reconcile invoices between Orb and Stripe systems
- Track subscription relationships across both platforms
- Maintain data consistency when working with both Orb and Stripe APIs
- Build integrations that can seamlessly map between Orb and Stripe resources
Customer Address Syncing
Orb automatically syncs customer addresses from Stripe to ensure billing and shipping information stays up-to-date. Address synchronization occurs in two scenarios:- When linking customers: When a customer in Orb is linked to a customer in Stripe (either through the UI or API), Orb will automatically pull the customer’s billing and shipping addresses from Stripe and update the corresponding Orb customer record.
- Via webhooks: When Orb receives a
customer.updated
webhook from Stripe, the system will automatically sync any address changes to the linked Orb customer. This ensures that address information remains consistent between both platforms without manual intervention.
- Billing address (street, city, state, postal code, country)
- Shipping address (if different from billing address)
Invoice Collection Behavior
When syncing invoices from Orb to Stripe, Orb’s auto-collection setting does not control how Stripe collects payment. Stripe provides two mechanisms for auto-collection:charge_automatically
: Stripe will attempt to automatically charge the customer’s default payment method upon invoice finalization.send_invoice
: Stripe will send the invoice to the customer without immediately charging a card.
due_date
of the invoice.
- For invoices that are “due on issue” (net terms = 0),
collection_behavior
is set tocharge_automatically
- For invoices with non-zero net terms,
collection_behavior
is set tosend_invoice
- For invoices with a custom due date in the past (before invoice creation date),
due date
is set tonull
to accomodate limitations in Stripe
auto_advance
field determines whether the invoice should be automatically finalized after it’s created. Orb sets this true
.