Customer metadata

Add metadata on customer

Customer metadata stores additional structured information on a customer to provide more context. For example, you could store a customer’s full name and unique identifier from your system on a Customer object by defining a key-value pair. A key cannot exist without its corresponding value, and vice versa. Metadata is set through the metadata array on the customer, using the key, value and display_in_invoice fields:

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
  "customer": {
    "external_id": "hooli_1234",
    "name": "Gavin Belson",
    "metadata": [
      {
        "key": "Purchase Order",
        "value": "123456789",
        "display_in_invoice": true
      }
    ]
  }
}'

Edit and delete metadata on customer

After adding metadata to a customer, you can edit or delete it. To edit metadata, you have two options:

Use the user interface to update the information displayed in the “Edit customer” drawer, and then save the customer changes.
Use the API to target the key-value pair information with the metadata ID in your code snippet and edit the key and value.

To edit a pair through the API, send it back with its id. Any pair you omit is removed, so include every pair you want to keep:

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
  "customer": {
    "external_id": "hooli_1234",
    "metadata": [
      {
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "key": "Purchase Order",
        "value": "987654321",
        "display_in_invoice": true
      }
    ]
  }
}'

Similarly, you can delete a key-value metadata pair by:

Clicking on the trash icon in the user interface, and then saving the customer changes.
Removing the key-value metadata object from your code snippet when using the API.

Display metadata in invoice object

To display customer metadata on invoices, switch on the option in the customer creation/edition drawer or set display_in_invoice to true. Once this option is activated, metadata is displayed on all new finalized and downloaded invoices.

When the customer’s metadata is added/edited/removed, the change only applies to new PDF files. Existing documents are not affected.