Help Center / Integrations

Stripe Integration

Light's Stripe integration syncs your Stripe invoices, payments, and credit notes into Light as they happen, keeps customers and products aligned across both systems, and charges your Light sales invoices through Stripe.

What is this page about

This page covers connecting Stripe to Light with a Stripe API key, what syncs between the two systems, and how Light collects payment on your sales invoices through Stripe. Use it to set up the integration, understand which records arrive in Light on their own, and resolve the most common sync problems.

On this page

  • Integration capabilities
  • Setting up Stripe integration
  • How invoice sync works
  • Product matching
  • Credit note sync
  • Charging invoices through Stripe
  • Stripe as a bank feed
  • Disconnecting Stripe
  • Troubleshooting Stripe sync
  • Related articles

Integration capabilities

With Stripe connected:

  • Invoice sync: Light creates a sales invoice for each finalised Stripe invoice and opens it
  • Payment sync: When a Stripe invoice is paid, Light records the payment on the matching sales invoice
  • Credit note sync: Light creates and posts Stripe credit notes as customer credits
  • Void handling: Voiding an invoice or credit note in Stripe voids the matching record in Light
  • Customer sync: Light creates customers from Stripe invoice data
  • Product sync: Light matches Stripe products to Light products, and creates them when they are missing
  • Document sync: Light attaches the original Stripe invoice and credit note PDFs to the Light records
  • Bank feed: Connect your Stripe balance as a bank feed for reconciliation
  • Invoice charging: Light charges your sales invoices through Stripe using a saved payment method

Setting up Stripe integration

Light connects to Stripe with a Stripe API key. Create the key in Stripe, then add it in Light.

  1. In Stripe, open your API keys page and create a key for Light. Stripe recommends a restricted key with write access to Checkout Sessions and PaymentIntents
  2. Copy the key
  3. In Light, go to Settings (gear icon) > Integrations
  4. Click Add integration, then choose Add Stripe API key
  5. Paste your key into the API key field
  6. Use Apply to entities to limit the key to specific entities, or leave it blank to use it across the whole company
  7. Click Add API key

Light checks the key with Stripe before saving it, so you know straight away whether it works. Once Light accepts the key, the integration card shows as active and syncing starts. Light receives events from Stripe via webhooks, so records sync as they happen. Document attachments (invoice and credit note PDFs) sync via their own background job, which retries automatically if needed.

How invoice sync works

The integration is event-driven. When something happens in Stripe, Light reacts immediately:

  1. Invoice finalised in Stripe: Light checks whether the customer already exists, matched by Stripe customer ID. If not, Light creates the customer from the Stripe invoice's customer name, email, and billing country. Light then creates the sales invoice with its lines, quantities, amounts, taxes, and billing periods, and opens it.
  2. Invoice paid in Stripe: Light records a payment on the matching sales invoice for the amount paid.
  3. Invoice voided in Stripe: Light voids the matching sales invoice.

Invoices are matched by the Stripe invoice ID, so payments and voids always land on the right record.

Note: When syncing Stripe invoices, Light preserves the original Stripe invoice number as the primary invoice number in Light. This keeps invoice numbers consistent across Stripe and Light for easier reconciliation and customer enquiries. (This applies to new imports; existing invoices retain their current numbers.)

Product matching

When a synced Stripe invoice references products:

  • If a Light product is already linked to the Stripe product, the invoice line uses it
  • A Stripe product can be linked explicitly by adding a light_product_id entry to the product's metadata in Stripe, pointing at the Light product's ID
  • If no linked product exists, Light creates the product automatically with Stripe as its external source
  • If the product exists in Light but is priced in a different currency, the invoice currency is added to the product's pricing

Note: When syncing Stripe invoices that include line-level discounts, Light captures the discount amount explicitly on each invoice line. The line amount represents the pre-discount, pre-tax subtotal, and the discount is shown separately, matching how Stripe represents discounted invoices.

Credit note sync

When a credit note is created in Stripe:

  1. Light receives the event in real time
  2. Light creates a customer credit for the matching customer, referencing the Stripe credit note
  3. Light posts the customer credit
  4. The Stripe credit note PDF is attached to the customer credit

Voiding the credit note in Stripe voids the customer credit in Light.

Note: When syncing Stripe credit notes with line-level discounts or taxes, Light preserves the line amount and discount structure exactly as Stripe provides them, ensuring customer credit totals match Stripe's final amounts. This keeps your records consistent with what customers see in Stripe.

Charging invoices through Stripe

Light also collects payment for your sales invoices through Stripe:

  1. Set the payment type to Stripe on the invoice, or on the contract that generates it
  2. The customer saves a payment method once, through a secure Stripe checkout link
  3. Light charges that saved payment method for the invoice's remaining balance
  4. The invoice moves to Payment pending
  5. Once the Stripe payout is reconciled against your bank account (via the Stripe bank feed), the invoice is marked paid

Light looks for invoices to charge once a day. It picks up any invoice that carries the Stripe payment type, sits in an open or partially paid state, and has reached its due date. Invoices you create by hand and invoices a contract generates are treated the same way, so each one charges on its own due date. Setting the Stripe payment type on a contract stamps that payment type onto every invoice the contract generates.

The checkout link collects a payment method once per customer. After the card is saved, Light charges later invoices against it without sending a new link.

Stripe as a bank feed

Your Stripe balance can act as a bank feed in Light, so Stripe activity flows into bank reconciliation like any other bank account:

  1. Go to Settings (gear icon) > Integrations and click Add integration
  2. Choose Bank
  3. Select the Stripe account tile, marked "via Stripe", then click Next
  4. Pick your connection from Select Stripe connection, or add an API key if this is your first Stripe connection
  5. Light imports your Stripe balance and balance transactions
  6. Reconcile Stripe payouts and charges alongside your other bank accounts

The bank feed runs on an API key connection. If you have not added a key yet, Next opens the same Add your Stripe API key modal so you can add it inline.

Disconnecting Stripe

You can disconnect the integration from Settings (gear icon) > Integrations, or by removing Light's access from your Stripe dashboard. Either way, Light marks the connection inactive and stops syncing. Records already synced remain in Light.

Troubleshooting Stripe sync

Invoices not syncing: Check that the integration card shows as active. Only finalised Stripe invoices sync, so finalise the invoice in Stripe and Light imports it from there.

Wrong customer assigned: Customers are matched by Stripe customer ID. Check whether the customer was previously imported under a different Stripe customer.

Product not linked: Verify the light_product_id metadata on the Stripe product points to a valid Light product ID.

Connection failed: Light rejects an API key that Stripe no longer accepts. Create a fresh restricted key in Stripe, then add it again from Settings (gear icon) > Integrations.

Charge failed: Check that the invoice's payment type is Stripe and that the customer has saved a payment method through the checkout link.

Was this article helpful?

Book a demo