FAQ & troubleshooting

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.

​

Why are custom fields not appearing on my invoice?

In most cases, one of these is missing:

1. The app is not enabled in Configuration.
2. No field mapping rules are configured or saved.
3. The metadata key (or Checkout custom field key) doesn’t match the source key in your rule.
4. Stripe finalized the invoice before the app could touch it (most common: the very first invoice for a new subscription, which Stripe finalizes immediately at checkout — see below).
5. Subscription is not active in Billing (production only).

​

Why doesn’t the very first subscription invoice have custom fields?

Stripe creates and finalizes the first invoice for a new subscription immediately at checkout. There’s no draft window for the app to add custom fields. The app handles this by saving the customer’s checkout custom field values as subscription metadata. From the second invoice onward (the first renewal), those values are read from subscription metadata and the custom fields appear automatically.

​

Can I use Payment Links with this app?

Partially.

• Subscription Payment Links: yes, fully supported from the first renewal onward (see above).
• One-time-payment Payment Links: the app cannot reliably fill custom fields on every one-time-payment invoice. The behavior depends on whether “Create invoice” is enabled on the link and Stripe’s timing. If you need custom fields on one-time-payment invoices, the recommended path is to create the invoice manually in Stripe after the payment — the app then fills it in while it’s still a draft.

​

How do I map a Payment Link custom field to a rule?

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’s mapping rules, set the Source key to match that label — or a slugified version of it. Matching is flexible, so all of these source keys will pick up a custom field labeled “Delivery Date”:

• Delivery Date, delivery date, delivery_date, delivery-date

Recommended: use snake_case (delivery_date). It matches Stripe’s metadata convention, so the same rule also picks up matching invoice/customer/subscription metadata.

​

Can I use different metadata keys for different customers?

No. Field mapping rules are account-wide. All invoices use the same set of source keys. However, if a customer doesn’t have a particular metadata key set, the app falls through the priority chain and uses subscription / checkout / customer metadata, or the static fallback if none are set.

​

What’s the source priority?

For each rule, the app uses the first non-empty match from this list:

1. Invoice metadata
2. Subscription metadata / Checkout custom fields
3. Customer metadata
4. Static fallback

​

What’s the difference between “custom fields” and “save as invoice metadata”?

• Custom fields appear on the invoice itself (visible to customers, on the PDF, on the hosted invoice page).
• Invoice metadata is invisible to customers but searchable via the Stripe API — useful for exports, BI, and downstream integrations.

The “Enable saving custom fields as invoice metadata” toggle mirrors the same values into both. Existing metadata keys are never overwritten.

​

What happens when I have more than 4 custom fields?

Stripe invoices support a maximum of 4 custom fields. The app enforces this limit in the field mapping configuration.

​

What happens when the app is disabled?

• No automatic syncing occurs.
• Existing custom fields on invoices are not removed.
• Configuration is preserved and can be re-enabled later.

​

What happens when my subscription expires?

• The app is automatically disabled.
• No syncing occurs until the subscription is renewed and the app is re-enabled.
• Configuration and field mapping rules are preserved.

​

Is a subscription required?

​

Where does the invoice drawer get its source attribution from?

For draft invoices, the drawer runs the engine live and shows the current source for each value. For finalized invoices, the drawer reads the source from the application history — the source recorded at the moment the app applied the field. This means the drawer always shows the original source (Subscription, Checkout, Customer, etc.), even if the “save as invoice metadata” toggle has since mirrored the value into invoice metadata.

​

Where can I find setup documentation?

Use the full documentation on this site, starting with Introduction.

​

How do I contact support?

Email: support@vinaka-apps.com