> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice metadata

## Add metadata on invoice

Adding metadata to an `invoice` object can provide additional structured information and context. For example, after finalizing the invoice, you can define a key-value pair in the `invoice` object to store your local invoice ID from your government invoicing system. To do so:

1. Navigate to the Invoice detail page to target a specific invoice;
2. Click on "Add metadata";
3. Add the information (a key cannot exist without its value, and vice versa); and
4. Save to confirm.

<Info>
  The invoice metadata will be included in the `invoice` object but will not be displayed on the PDF file.
</Info>

## Edit metadata on invoice

**To edit metadata from the user interface:**

1. Navigate to the Invoice detail page to target a specific invoice;
2. Click on "Edit metadata";
3. Add, edit, or remove information (a key cannot exist without its value, and vice versa); and
4. Save to confirm.

**To edit metadata using the API:**

1. In your payload, locate the key-value pair with the metadata ID you want to edit; and
2. Modify the key and/or value as needed.

<CodeGroup>
  ```bash Update invoice metadata theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"
  INVOICE_ID="__YOUR_INVOICE_ID__"

  curl --location --request PUT "$LAGO_URL/api/v1/invoices/$INVOICE_ID" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "invoice": {
        "metadata": [
          {
            "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "key": "digital_ref_id",
            "value": "INV-0123456-98765"
          },
          {
            "key": "purchase_order",
            "value": "PO-4567"
          }
        ]
      }
    }'
  ```
</CodeGroup>

The first item updates an existing key-value pair, identified by its `id`. The second has no `id`, so Lago creates it.

<Tip>
  When editing invoice metadata through the API, make sure to include the existing metadata in your payload to avoid removing it.
</Tip>

## Delete metadata on invoice

**To delete a metadata key-value pair from the user interface:**

1. Navigate to the Invoice detail page for the specific invoice;
2. Click on "Edit metadata";
3. Click on the trash icon next to the metadata you want to remove; and
4. Save to confirm.

**To delete a metadata key-value pair from the API:**

1. Do not include the metadata ID you want to delete in your payload.

## Invoice metadata limitations

1. You can add up to 5 metadata key-value pairs;
2. Keys must be unique within an invoice;
3. Keys must be strings of 20 characters maximum; and
4. Values must be strings of 140 characters maximum.