Connecting Stripe

TrueUpp creates draft invoices and draft invoice items. It never finalizes, sends, charges, voids or deletes anything in your Stripe account; your team does that in Stripe as usual. Setup takes about ten minutes.

Before you start: pick the right Stripe account

Stripe keeps live mode, test mode and each sandbox apart, and a key only sees the customers in its own one. Open Stripe's account switcher (top left) and choose the account or sandbox that holds the customers you bill. Do every step below in that same place. Start with test mode or a sandbox, then repeat in live mode when you're ready.

Option A: install the TrueUpp app

If Settings › Connections shows Install the TrueUpp app in Stripe, click it and approve the permissions in Stripe. You come back connected, and webhooks arrive automatically, so skip to mapping customers.

Option B: create a restricted key

1. In Stripe, open Developers › API keys › Create restricted key, and choose "Providing this key to another website".
2. Name it "TrueUpp" and set exactly these permissions, leaving everything else as None:
   • Customers: Read
   • Invoices: Write
   • Invoice items: Write
   • Prices and Products: Read
3. Create it, copy the key (it starts with rk_test_ or rk_live_) and paste it in TrueUpp under Settings › Connections › Stripe. TrueUpp checks each permission before saving and names any that are missing. A secret key (sk_) is refused, because it can do far more than TrueUpp needs.

Add the webhook endpoint

The webhook is how TrueUpp learns that you finalized, voided or paid an invoice. (The TrueUpp app sets this up for you.)

1. Copy the endpoint URL shown in Settings › Connections, under Stripe.
2. In Stripe, open Developers › Webhooks › Add destination, choose "Your account", and select these events: invoice.finalized, invoice.voided, invoice.deleted, invoice.paid and invoiceitem.deleted.
3. Choose "Webhook endpoint", paste the URL and create it.
4. Reveal the signing secret (it starts with whsec_) and paste it in TrueUpp. Until it's saved, webhooks are rejected and pushed lines never move to invoiced.

Map each contract to a Stripe customer

Open a contract and use Stripe customer. Search by name or email, or paste the customer ID. Use the ID that starts with cus_: in newer Stripe accounts a customer page also shows an account ID starting with acct_, which is a different object. TrueUpp stores only the customer ID and reads the name live from Stripe.

Push approved lines

• One draft invoice per contract and period, holding only TrueUpp's items, with collection left to you.
• One invoice item per approved line, described with its units, tier pricing and clause reference.
• Every request carries an idempotency key, so pushing twice never creates duplicates.
• When you finalize the invoice in Stripe, the lines become invoiced and the amount is recorded for the expected-versus-invoiced check.
• If someone voids or deletes the draft in Stripe, the line stays as history and an exception asks whether to re-push or write it off. A weekly check catches items edited in the Stripe dashboard.

Troubleshooting

• "No such customer" when searching a cus_ ID. The customer lives in a different account, sandbox or mode from the key. The message names the connected account; create the key in the account that holds the customer and reconnect.
• "Skipped (no Stripe customer mapped)". Map the contract to a customer first, then push again. Nothing was sent.
• "Permission denied … invoice_write" (or another permission). Edit the restricted key in Stripe and set the permission named in the message, then push again.
• Lines stay "Pushed" after you finalize. The webhook isn't reaching TrueUpp: check the endpoint URL, the five events and the signing secret. Connections shows when the last webhook arrived.