Stripe
If you would like to use Stripe as a payment gateway and send Orb invoices, follow the instructions here instead
The following instructions are only if you would like to use Stripe Invoicing to send and manage invoices.
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 under payment_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 |
This metadata enables you to:
- 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
You can access this metadata through the Stripe API when retrieving invoice objects, or view it in the Stripe Dashboard under the invoice’s metadata section.
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.updatedwebhook 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.
The synchronized address information includes:
- Billing address (street, city, state, postal code, country)
- Shipping address (if different from billing address)
This automatic synchronization helps maintain accurate customer information for tax calculations, invoice delivery, and compliance requirements.
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.
When syncing an Orb invoice to Stripe, Orb will determine which option to use depending on the due_date of the invoice.
- For invoices with net terms set to zero,
collection_behavioris set tocharge_automatically - For invoices with non-zero net terms,
collection_behavioris set tosend_invoice
Stripe’s auto_advance field determines whether the invoice should be automatically finalized after it’s created. Orb sets this true