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

# Configuration

> Configure field mapping rules and optional metadata mirroring.

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

| Setting           | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| **Active**        | Toggle individual rules on/off without deleting them               |
| **Invoice label** | The label shown on the invoice header (max 40 characters)          |
| **Source key**    | The metadata key (or Checkout custom field `key`) the app looks up |
| **Fallback**      | Optional 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.

## How it works for Payment Links (Checkout custom fields)

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`

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

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](#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](/legal/pricing-billing).

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