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.

​
Settings page structure

The app settings page has three tabs:
  • Configuration: enable/disable the app and set up field mapping rules,
  • Billing: check subscription status and manage your subscription,
  • Support: documentation and support links.

​
Configuration tab

​
Enable the app

Toggle Enable app to activate the app for your account.
  • In sandbox mode or test mode, the app can be enabled without a subscription.
  • In live mode, an active subscription is required.
  • When the app is disabled, no automatic syncing occurs.

​
Field mapping rules

You can configure up to 4 field mapping rules. Each rule maps a metadata key (or static value) to an invoice custom field label.
SettingDescription
ActiveToggle individual rules on/off without deleting them
Invoice labelThe label shown on the invoice header (max 40 characters)
Source keyThe metadata key (or Checkout custom field key) the app looks up
FallbackOptional static value used when no source has data
The source-key dropdown suggests keys discovered from your account’s recent invoices, customers, subscriptions, and Checkout sessions. You can also type any custom key.

​
Source resolution order

For each rule, the app resolves the value from the highest-priority source that has data:
  1. Invoice metadata
  2. Subscription metadata / Checkout custom fields
  3. Customer metadata
  4. Static fallback
The first non-empty match wins.

​
Save custom fields as invoice metadata (optional)

A toggle below the rules: Enable saving custom fields as invoice metadata. When on, the same values the app writes into custom fields are also mirrored into invoice.metadata using each rule’s source key (or a slugified label for static-only rules). Existing metadata keys are never overwritten — the mirror only fills in keys that aren’t already set. This is useful when you want the same data accessible via the Stripe API for exports, BI, or downstream integrations.

​
How it works for subscriptions

When a customer subscribes through Checkout, the app saves their custom field values as metadata on the subscription. From the second invoice onward (the first renewal), the app reads that subscription metadata and fills in your custom fields automatically — no extra setup needed. The very first invoice for a new subscription is created and finalized by Stripe immediately at checkout, so the app can’t add custom fields to it. Custom fields appear from the first renewal onward. You can also set subscription metadata manually via the Stripe API or dashboard for subscriptions that weren’t started through Checkout. When you add custom fields to a Payment Link in the Stripe dashboard, you give each field a label that customers see at checkout — for example, Delivery Date or PO Number. In the app, set up a mapping rule where Source key matches that label (or a slugified version of it). The app’s matching is flexible, so all of these will pick up a custom field labeled “Delivery Date”:
  • Delivery Date
  • delivery date
  • delivery_date
  • delivery-date
  • deliverydate
Our recommendation: use a snake_case version of the label (e.g. delivery_date) as the source key. It’s the same convention Stripe uses for metadata keys, so the same rule will also pick up matching invoice/customer/subscription metadata.
Internally, every Stripe Checkout custom field has both a label (visible to your customer) and a programmatic key (sometimes auto-generated, sometimes set via API). The app reads both and tries every reasonable variation, so you don’t have to know the exact internal key — matching against the label you typed in the dashboard is enough. Important caveats for Payment Links:
  • One-time payments: the app can only fill in custom fields if “Create invoice” is off on the Payment Link AND Stripe creates the invoice as a draft. In practice, the most reliable path for one-time payments is to disable invoice creation on the Payment Link, capture the payment, and then manually create an invoice referencing the Checkout custom fields via Stripe’s invoice creation flow.
  • Subscriptions: see How it works for subscriptions above. The first invoice can’t be modified, but renewals work automatically via subscription metadata.

​
Billing tab

The Billing tab shows your subscription status and provides links to:
  • Start a subscription (14-day free trial),
  • Manage your existing subscription,
  • View pricing details.
For full billing details, see Pricing & billing.
No subscription is needed if you’re testing the app — both Stripe Sandbox accounts and any regular account in test mode can use the app freely. A subscription is only required when you switch to live mode.