> For the complete documentation index, see [llms.txt](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/settings-and-config/custom-fields/add-metadata-to-your-records.md).
# Add Metadata to Your Records
Metadata allows you to define custom fields for customers, contracts, invoices, bills, and GL accounts in **Rillet**, bringing context from other systems into your records without waiting on a product change. These fields are also searchable in your reports, usable as conditions in the Income Statement, and accessible through the API.
### Create a Metadata Field
Follow these steps to create a metadata field:
{% stepper %}
{% step %}
Click your organization name at the bottom of the left sidebar.
{% endstep %}
{% step %}
Select **Organization settings**.
{% endstep %}
{% step %}
Open **Metadata** in the Settings sidebar.
{% endstep %}
{% step %}
Click **Add metadata**.
{% endstep %}
{% step %}
Enter a name for the field to auto-fill a permanent **API Identifier**.
{% endstep %}
{% step %}
**(Optional):** Add a description.
{% endstep %}
{% step %}
Check **Contract**, **Customer**, **Invoice**, **Bill**, **Account**, or any combination of the five under **Assign to objects**.
{% endstep %}
{% step %}
**(Optional):** Turn on **Share with new objects** to copy this field's value to related records when they are created.
{% endstep %}
{% step %}
Select **Customer** or **Contract** in **Copy from** to choose where the value comes from.
{% endstep %}
{% step %}
Check the objects under **Copy to when created** that should receive the value.
{% endstep %}
{% step %}
Click **Save metadata** to create the field.
{% endstep %}
{% endstepper %}
The field appears in the Metadata list with its name, API identifier, description, assigned objects, and status. Object assignments are permanent once saved, so choose them carefully. The **Share with new objects** options appear once you assign the field to related objects, such as **Customer** and **Contract**. See [**Share Metadata Values with New Records**](#share-metadata-values-with-new-records) for how sharing works.
### Add a Value to a Customer, Contract, or Invoice
Complete these steps to record a metadata value:
{% stepper %}
{% step %}
Click **Accounts Receivable** in the left sidebar.
{% endstep %}
{% step %}
Select **Customers**, **Contracts**, or **Invoices**, whichever object the field is assigned to.
{% endstep %}
{% step %}
Open the record you want to add a value to.
{% endstep %}
{% step %}
Scroll to the **METADATA** section on the Overview tab.
{% endstep %}
{% step %}
Click the **pencil icon**.
{% endstep %}
{% step %}
Enter a value, then click **Save**.
{% endstep %}
{% endstepper %}
The value appears in that record's **METADATA** section from then on. Metadata values are set independently per record, unless the field is set up to share its value with new records. See [**Share Metadata Values with New Records**](#share-metadata-values-with-new-records).
### Share Metadata Values with New Records
Complete these steps to copy a customer's metadata value to the contracts and invoices created for that customer, so you set it once instead of re-entering it on every record:
{% stepper %}
{% step %}
Create a metadata field assigned to **Customer** and **Contract**, turn on **Share with new objects**, set **Copy from** to **Customer**, and check **Contract** under **Copy to when created**.
{% endstep %}
{% step %}
Add a value to a customer, as described in [**Add a Value to a Customer, Contract, or Invoice**](#add-a-value-to-a-customer-contract-or-invoice).
{% endstep %}
{% step %}
Create a new contract for that customer by following [**Add a Contract**](/EjmEP4KZ9BVp9j2ho4Mh/accounts-receivable/contracts/add-a-contract.md).
{% endstep %}
{% endstepper %}
{% hint style="info" %} **Note:**
Sharing copies the source's current value once, when the new record is created. Existing records and later edits stay unchanged, so changing a customer's value does not update contracts or invoices already created. A value you enter on a new record yourself takes priority over the shared one.
{% endhint %}
The new contract's **METADATA** section shows the customer's value without you entering it.
### Add a Value to a Bill
Complete these steps to record a metadata value on a bill:
{% stepper %}
{% step %}
Click **Accounts Payable** in the left sidebar.
{% endstep %}
{% step %}
Select **Bills**.
{% endstep %}
{% step %}
Open the bill you want to add a value to.
{% endstep %}
{% step %}
Find the **METADATA** section in the column on the right.
{% endstep %}
{% step %}
Click the **pencil icon**.
{% endstep %}
{% step %}
Enter a value, then click **Save**.
{% endstep %}
{% endstepper %}
The value appears in that bill's **METADATA** section from then on.
### Add a Value to a GL Account
Complete these steps to record a metadata value on a GL account, for example to mark it for GAAP or non-GAAP reporting:
{% stepper %}
{% step %}
Click your organization name at the bottom of the left sidebar.
{% endstep %}
{% step %}
Select **Organization settings**.
{% endstep %}
{% step %}
Open **Chart of Accounts** in the Settings sidebar.
{% endstep %}
{% step %}
Click the **three-dot icon** next to the account, then select **Edit account**.
{% endstep %}
{% step %}
Enter a value in the field under **Metadata**.
{% endstep %}
{% step %}
Click **Save**.
{% endstep %}
{% endstepper %}
The value appears under **Metadata** in the account's details from then on. Metadata values are free text, so use the same wording every time you tag an account.
### Use Metadata in Reporting
Metadata fields are available directly as filter and column options in Custom Reports, appearing in the field list alongside standard fields such as Customer, Product, and Status, with no extra setup required. See [**Build a Custom Report**](/EjmEP4KZ9BVp9j2ho4Mh/settings-and-config/custom-fields/viewing-fields-in-reporting/build-a-custom-report.md) for the full report-building workflow.
Metadata on GL accounts can also be used to include or exclude accounts in the Income Statement. See [**Customize the Income Statement**](/EjmEP4KZ9BVp9j2ho4Mh/reporting/financial-statements/customize-the-income-statement.md) for the steps.
{% hint style="info" %} Note:
Metadata can also be read and written through the Rillet API when creating or updating customers, contracts, and invoices. See the [**API Reference**](https://docs.api.rillet.com/reference) for details.
{% endhint %}
### Manage a Metadata Field
Take these steps to edit, archive, review, or delete a metadata field:
{% stepper %}
{% step %}
Click the **three-dot icon** next to the field.
{% endstep %}
{% step %}
Select **Edit**, **Archive**, **Audit history**, or **Delete**.
{% endstep %}
{% endstepper %}
{% hint style="warning" %} **Warning:**
A metadata field cannot be deleted while any record still holds a value for it, since deleting would otherwise discard that data. Rillet blocks the delete and offers to archive the field instead, which stops it from being offered on new entries while keeping every value already recorded. Clear every value first, or archive the field if the recorded values still matter.
{% endhint %}
### See Also
To learn more about custom fields and reporting in **Rillet**, review these articles:
* [**Fields Overview**](/EjmEP4KZ9BVp9j2ho4Mh/settings-and-config/custom-fields/fields-overview.md)
* [**Build a Custom Report**](/EjmEP4KZ9BVp9j2ho4Mh/settings-and-config/custom-fields/viewing-fields-in-reporting/build-a-custom-report.md)
* [**Customize the Income Statement**](/EjmEP4KZ9BVp9j2ho4Mh/reporting/financial-statements/customize-the-income-statement.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/settings-and-config/custom-fields/add-metadata-to-your-records.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
