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

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Metadata

> Most updatable Augustus objects have a Metadata parameter. You can use this parameter to attach arbitrary key-value data to these Augustus objects.

## Overview

Most updatable Augustus objects have a `metadata` parameter. You can use this parameter to attach arbitrary key-value data to Augustus objects.

You can specify up to 50 keys, with:

* Key names up to 40 characters long
* Values up to 500 characters long

Metadata is useful for storing additional, structured information on an object. For example, you could store your user's corresponding unique identifier from your system on an Augustus Checkout Session object. This allows you to attach information about returning users to an Augustus Payment.

When a user successfully completes the payment flow, all `metadata` parameters transfer from the Augustus Checkout Session to the Augustus Order. By default, Augustus doesn't use Metadata for any processing logic - for example, it's not used to authorize or decline payments. Your users will only see Metadata if you explicitly show it to them.

<Warning>
  Do not store sensitive information (bank account numbers, card details, etc.) in the `metadata` parameter.
</Warning>

## Sample Metadata Use Cases

### Link IDs

Attach your system's unique IDs to an Augustus object for easy lookups:

* Add your order number to a charge
* Add your user ID to a customer or recipient
* Add a unique receipt number to a transfer

### Refund Paper Trails

Store information about:

* Why a refund was created
* Who created the refund
* Any associated internal tracking numbers

### Recognize Returning Customers

Annotate a Checkout Session object by storing an internal ID for later use.

When creating a new Augustus Checkout Session for a payment flow ([See payment flow details](/docs/payin/instant-bank-transfer/payment-integration)), specify your system's internal customer ID in the `metadata` field.

The example below adds an `internalCustomerId` with the value `customer_abcdefg` to the Augustus Checkout Session object:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.getivy.de/api/service/checkout/session/create \
    -H 'Content-Type: application/json' \
    -H 'X-Ivy-Api-Key: <api-key>' \
    -d '{
      "price": {
        "total": 100,
        "currency": "EUR"
      },
      "referenceId": "my-unique-reference-id",
      "metadata": {
        "internalCustomerId": "customer_abcdefg"
      }
    }'
  ```
</CodeGroup>

When receiving status updates ([See payment status details](/docs/payin/instant-bank-transfer/payment-status)), the `metadata` field will be included in the payload. This allows you to easily match a new Order status to an internal user - for example, to fulfill orders more quickly.