> ## 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.

# App manual

> Simple, step-by-step guide to using the Invoice Custom Fields app.

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 label | Source key      | Fallback  |
| ------------- | --------------- | --------- |
| PO Number     | `po_number`     |           |
| Project       | `project_code`  |           |
| Delivery Date | `delivery_date` |           |
| Cost Center   | `cost_center`   | `Default` |

### 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 flow                          | Where to put the data                                                                                                |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Manual invoices in the dashboard   | Invoice metadata or Customer metadata                                                                                |
| Subscriptions started via Checkout | Add custom fields to the Payment Link / Checkout — the app saves them onto the subscription so renewals pick them up |
| Subscriptions created via API      | Set 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.

### Payment Links — how the source key matches

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.

<Tip>
  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.
</Tip>

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.

<Note>
  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.
</Note>

## 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](mailto:support@vinaka-apps.com).