Stripe invoicing

Preparing an invoice means bringing a customer, amount and agreed terms together correctly. Stripe invoicing combines existing customer records, a configured Stripe connection and reviewed operations, with provider results recorded separately from the requests that produced them.

Try a complete invoice

Open Plugins at /admin/plugins and enable Stripe invoicing, then open Billing from the sidebar or mobile More menu. Select Create invoice to open the customer and line-item form. Command/Ctrl+K also finds Create invoice; if the module is off, search for invoice and choose Set up invoicing for enablement instructions.

The direct creation link is /admin/invoicing?view=create. If Stripe is disconnected, connect it here first. Credentials belong in the server-only connection controls. Verify test or live mode before a provider action.

Enter the Stripe account ID shown in that business's Stripe settings with its API key. The connection rejects a key from another account. For workshop payments, also supply the matching Publishable key for workshop payments and webhook signing secret. Replacing a key preserves optional credentials only when the verified account stays the same; changing merchants requires that account's own credentials.

1. Select an existing contact and its matching Stripe billing customer. If no billing customer exists, choose Create billing customer and approve the name and email shown. The new profile appears in the refreshed choices; creating it takes no payment.
2. Enter currency, line items and payment terms. For a fictional example, use one consulting session at 125.00 USD, quantity one. The UI uses normal currency units; the corresponding API value is 12500 minor units.
3. Preview the recipient, amount and terms, then submit the exact draft for approval.
4. After approval execution, inspect the provider result. Use the separate reviewed send control when ready, and check its receipt.

A created draft, a sent invoice and a paid invoice are different states. The demo simulates provider actions with fictional records and does not create a live invoice.

Review balances and find an invoice

All invoices reads the connected Stripe account, including invoices created outside this workspace. Search the loaded invoices by number, customer or email, choose a status such as Overdue, and sort by creation or due date. Load more invoices includes older records in your search. Clearing a filter restores the loaded list.

Awaiting payment sums the remaining balances of open invoices. Past due is the overdue part of that same balance, so do not add those two figures together. In draft shows prepared amounts that have not been issued. Each currency has its own figure. The screen states how many invoices are loaded, discloses missing balances, and keeps older information visible if a refresh fails. Refresh successfully before treating it as current.

For a finalized, unpaid invoice created by this workspace, choose Void unpaid invoice. Review the exact customer, amount and consequence before approval. Voiding permanently cancels the invoice and preserves its history. A paid or partly paid invoice needs the appropriate refund or credit-note workflow; this control cannot cancel it.

Review a payment or refund

Select Payments & refunds in the billing navigation. Search the loaded account charges, filter by status or period, and load older payments when needed. The figures describe the selected records: Captured, Refunded, and After refunds. They keep currencies separate and do not include processing fees, disputes, payouts or bank balances. Failed and pending charges do not contribute captured amounts.

For a payment marked as belonging to this workspace, choose Refund payment. Enter a full or partial amount and a reason, then choose Review refund. USD, EUR, GBP, CAD and AUD support partial amounts here; other currencies offer the full remaining balance. Payments that need an invoice ownership check offer Check refund eligibility first. The review verifies their link to invoices belonging to this workspace before allowing a refund.

Approve only the exact amount and original payment method shown in the review. The resulting receipt distinguishes a succeeded refund from a pending or failed provider result. Recent billing actions keeps that result and its provider reference available. Choose Check provider result to read its current status, including after a review expires. The latest observation appears separately and preserves the original execution receipt. A refund does not rewrite the invoice’s recorded payment history. Ticket refunds also follow the existing signed webhook path, which updates the order and admission status from Stripe’s facts.

For example, a fictional $125 consulting payment can receive a reviewed $25 refund. Once Stripe confirms that amount, the payment record shows $25 refunded and $100 after refunds, before fees or other adjustments. The demo simulates this result locally and moves no money.

Export selected payments downloads the currently selected loaded records as CSV. Amount columns explicitly use Stripe’s integer minor units and retain a separate currency column. Load the history you need before exporting; the file is not an automatic complete-account export.

Give the customer a coherent experience

For an invoice created through this workspace, choose Design customer page in Invoice operations. The editor opens the latest active published design, or your workspace branding if there is no published page. Its live preview displays the current Stripe invoice.

Enter a request in Describe your changes, such as “Keep my wording. Use an editorial layout, serif typography, compact spacing, and #164e63,” then select Apply AI changes. AI receives the current presentation so you can refine it repeatedly. Use Undo changes and Redo changes to move through AI revisions and manual edits. Typing in one field is grouped into one step, so you can restore its earlier wording in one click. You can also edit the layout, typography, spacing, accent color, heading, introduction, and closing note directly. Logo and business identity come from workspace branding.

Workspace, Editorial, and Minimal style starters let you try another visual direction while keeping your wording and accent color. Select Phone to inspect the narrow customer view, then Full width to return. The document responds to its preview width, including when you are editing on a large screen. Draft edits remain available until you close the editor; an approved publication saves a version you can reopen.

Select Preview page to review the current design against fresh billing and branding details, then Request publication approval. Any further edit requires another preview. After approval execution, refresh the published links, then choose Open customer page or Copy link. Each approved design gets a new link; editing a draft does not change an existing link. Edit this design starts another draft from a saved version. Revoke an old link when you no longer want customers to use it.

This designs the customer invoice page served by your workspace. It does not redesign Stripe’s hosted payment form or invoice PDF. The payment button opens Stripe’s secure payment page; balances and payment status come from Stripe, while AI edits presentation. Publishing does not send an email. Public content should contain only information intended for the recipient. Demo previews remain inside the browser scenario; they are not live public links.

What this example teaches you to build

An external action needs more than a form. The plugin connects a source record, a reviewable plan, provider execution and a durable result. You can study this pattern when adding another billing or document service.

AI invoice preparation and proposal tools use the same services as the interface. get_billing_records reads bounded invoice or payment pages, and get_billing_action checks an existing operation’s current provider result. preview_billing_change and propose_billing_change prepare the same billing-customer, unpaid-invoice and refund operations for human approval. Provider secrets stay on the host, and the model cannot approve its own action. See the workflow source and developer guide for contracts, verification and upgrade behavior.

Costs and recovery

Draft preparation is deterministic. Stripe usage, hosting and any AI design or chat can incur their normal costs. There is no plugin-specific unlimited free allowance.

If the contact has no matching Stripe customer, check the contact email and use Create billing customer. An existing unambiguous billing profile is reused to prevent duplicates. After a timeout, inspect the original action and provider invoice before retrying with its existing identity. A changed draft needs a new preview and approval. If the editor cannot load the invoice, choose Retry loading invoice; your current draft stays in place while it retries.

Disabling the plugin blocks later execution and makes its customer-page links unavailable. Saved pages remain stored; re-enabling restores unexpired, unrevoked links. Stripe invoices and payments are not reversed. Revoke a page explicitly when you no longer want to share it. The controlled tests in the developer guide check the code, not your specific live connection or payment.

After an uncertain billing result, open Recent billing actions. For an eligible failed operation, Review same operation again retains its original identity and checks whether Stripe already accepted it before attempting another effect. A changed account, balance, recipient, expired review or incomplete provider lookup refuses the retry. Refresh and reconcile that original result before preparing a different action.

The Stripe key needs account, customer, invoice, charge, payment-intent, invoice-payment and refund reads, plus customer, invoice and refund writes for the controls you use. The connection stores credentials encrypted on the server. A missing permission displays an error while preserving previously loaded results. For a permission error, check the named resource on the connected key in Stripe, then reconnect the key in Integrations and refresh. The error includes Stripe’s request reference when available, so you can find the rejected request in Stripe’s logs. Disputed payments and payments without verified workspace ownership cannot be refunded here. Credit notes, accounting journals and bank reconciliation remain separate workflows.