Skip to main content

Documentation Index

Fetch the complete documentation index at: https://stripe-invoice-custom-fields-docs.vinaka-apps.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide is written for business users, not developers. If you can use Stripe Invoicing, you can set this up.

​
What this app does for you

  • Fills in custom fields on draft invoices automatically as Stripe creates them.
  • Carries Checkout custom field values forward to subscription renewal invoices.
  • Optionally mirrors the same values into invoice metadata for downstream queries.
  • Shows on the invoice drawer where each value came from.

​
Start in 3 quick steps

​
1. Subscribe and enable

In Stripe, open the app and go to Billing:
  1. Click Start subscription (14-day free trial).
  2. Complete checkout.
  3. Go to Configuration and toggle Enable app.
Skip the subscription if you’re in sandbox or test mode — both are free for testing. The subscription is only required in live mode.

​
2. Configure field mappings

Go to Configuration:
  1. Add up to 4 field mapping rules.
  2. For each rule, set the invoice label and source key. Optionally set a static fallback.
  3. (Optional) toggle Enable saving custom fields as invoice metadata if you want the same values mirrored to invoice.metadata.
  4. Click Save.
Example setup:
Invoice labelSource keyFallback
PO Numberpo_number
Projectproject_code
Delivery Datedelivery_date
Cost Centercost_centerDefault

​
3. Add data where the app can find it

Set the same keys (e.g. po_number) as metadata or Checkout custom fields, depending on your flow:
Your flowWhere to put the data
Manual invoices in the dashboardInvoice metadata or Customer metadata
Subscriptions started via CheckoutAdd custom fields to the Payment Link / Checkout — the app saves them onto the subscription so renewals pick them up
Subscriptions created via APISet them as subscription metadata directly
Payment Links (one-time)Add custom fields to the link — see “Payment Links” below

​
How invoices get filled in

​
Drafts created by Stripe (subscription renewals, dashboard-drafted invoices)

When Stripe creates a draft invoice, the app’s webhook fires, the engine resolves each rule against your source priority, and the values land on the invoice before Stripe finalizes it. Nothing for you to do — open the invoice, see the fields filled in.

​
The invoice drawer

Open any invoice in Stripe and the app shows a drawer with:
  • The label, value, and source for each rule that resolved.
  • Rules that didn’t resolve are shown muted with the reason (“No data found”).
  • For draft invoices, this is what will be saved when Stripe finalizes.
  • For finalized invoices, this is what was saved — including the original source tier the value came from at the time.
There are no buttons in the drawer. Everything happens automatically.

​
Subscriptions

When a customer subscribes through Checkout, the app saves their custom field values as metadata on the subscription. From the first renewal invoice onward, those values flow through to the invoice automatically. The very first invoice (created at checkout) can’t be modified by the app — Stripe finalizes it immediately. From the second invoice onward, the app fills it in. When you add custom fields to a Payment Link in the Stripe dashboard, you give each field a label that customers see at checkout (e.g. Delivery Date, PO Number). In the app, set up a rule where Source key matches that label — or a slugified version of it. The matching is flexible: all of these source keys will pick up a custom field labeled “Delivery Date”:
  • Delivery Date
  • delivery date
  • delivery_date
  • delivery-date
So you can keep your source keys lowercase and snake_case (matching Stripe’s metadata convention) without worrying about the exact label format your customer sees.
Recommended: use snake_case for source keys (e.g. delivery_date). The same rule will then match the Payment Link’s label AND any matching metadata key on the invoice, subscription, or customer — across all source tiers in the priority chain.
Internally, every Stripe Checkout custom field has both a label (visible) and a programmatic key (often auto-generated). The app reads both and tries every reasonable variation, so the merchant doesn’t need to know the internal key.
For subscription Payment Links, custom fields land on the subscription metadata and apply from the first renewal onward.For one-time Payment Links, the app’s behavior depends on whether “Create invoice” is enabled on the link and on Stripe’s timing — the app cannot reliably fill custom fields on every one-time-payment invoice. If you need custom fields on one-time invoices, the recommended path is to create the invoice manually after the payment and let the app fill it in as a draft.

​
Read the source on the invoice drawer

Each filled field shows where its value came from:
  • Invoice — invoice metadata
  • Subscription — subscription metadata snapshot
  • Checkout — checkout custom field
  • Customer — customer metadata
  • Static value — your configured fallback
For finalized invoices, the source you see is the original source recorded at the moment the app applied the field — even if the same value has since been mirrored into invoice metadata by the “save as metadata” toggle.

​
Good first-week checklist

  1. Test in sandbox with 2-3 invoices.
  2. Confirm custom fields appear on the invoice header.
  3. If you use subscriptions: complete a Checkout, confirm subscription metadata is set, then create a renewal invoice manually to verify it auto-fills.
  4. Go live and enable the app.
  5. Add metadata to customers as needed.

​
Need help?

If anything is unclear, contact support@vinaka-apps.com.