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

# Set metadata

> Create or update metadata for a given entity.

**Set metadata** creates or updates custom metadata for a given entity. This endpoint follows idempotent PUT semantics:

* **Create**: Returns `201 Created` if metadata doesn't exist
* **Replace**: Returns `200 OK` if metadata already exists

The response includes an `ETag` header representing the version of the metadata, which can be used with `If-Match` or `If-None-Match` headers for conditional requests to prevent concurrent update conflicts.

> [!WARNING]
>
> Each PUT request replaces the entire metadata object. Make sure to include all properties you want to retain.


## OpenAPI

````yaml _media/specs/on-off-ramp-openapi.mintlify.json put /on-off-ramp/{entity}/{entityId}/metadata
openapi: 3.1.0
info:
  version: 0.1.0
  title: On & Off Ramp API
  description: >-
    The On & Off Ramp API offers a set of endpoints to move value between fiat
    and crypto through a single atomic order per direction: on-ramp or off-ramp.
  contact:
    name: Uphold API Team
    email: developer@uphold.com
    url: https://developer.uphold.com
servers:
  - url: https://api.enterprise.sandbox.uphold.com
    description: Sandbox
  - url: https://api.enterprise.uphold.com
    description: Production
security:
  - OAuth2: []
tags:
  - name: Orders
    description: On & Off Ramp orders.
  - name: Metadata
    description: Metadata.
  - name: Rails
    description: On & Off Ramp rails.
paths:
  /on-off-ramp/{entity}/{entityId}/metadata:
    put:
      tags:
        - Metadata
      summary: Set metadata
      description: Create or update metadata for a given entity.
      operationId: on-off-ramp.set-metadata
      parameters:
        - $ref: '#/components/parameters/metadata-entity'
        - $ref: '#/components/parameters/metadata-entity-id'
        - $ref: '#/components/parameters/metadata-if-match'
        - $ref: '#/components/parameters/metadata-if-none-match-any'
      requestBody:
        $ref: '#/components/requestBodies/set-metadata-request-body'
      responses:
        '200':
          $ref: '#/components/responses/set-metadata-replaced-response'
        '201':
          $ref: '#/components/responses/set-metadata-created-response'
        '404':
          $ref: '#/components/responses/metadata-not-found'
        '409':
          $ref: '#/components/responses/set-metadata-conflict-response'
        '412':
          $ref: '#/components/responses/metadata-precondition-failed'
        '413':
          $ref: '#/components/responses/metadata-payload-too-large'
components:
  parameters:
    metadata-entity:
      name: entity
      description: The type of entity whose metadata is being accessed.
      in: path
      required: true
      schema:
        type: string
        enum:
          - orders
      examples:
        Order Entity:
          value: orders
    metadata-entity-id:
      name: entityId
      description: The unique identifier of the entity whose metadata is being accessed.
      in: path
      required: true
      schema:
        type: string
      examples:
        Order ID:
          value: 623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0
    metadata-if-match:
      name: If-Match
      description: Ensures conditional update by matching the current metadata revision.
      in: header
      style: simple
      explode: false
      schema:
        type: string
        pattern: ^(?:W\/)?"([A-Fa-f0-9]{64})"$
      examples:
        Metadata Revision:
          value: '"abc123def456789012345678901234567890123456789012345678901234abcd"'
    metadata-if-none-match-any:
      name: If-None-Match
      description: Prevents upsert operation if there is an existing metadata revision.
      in: header
      style: simple
      explode: false
      schema:
        type: string
        enum:
          - '*'
      examples:
        Any Revision:
          value: '*'
  requestBodies:
    set-metadata-request-body:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/metadata'
          examples:
            Set Metadata:
              value:
                externalId: 123
  responses:
    set-metadata-replaced-response:
      description: Metadata replaced.
      headers:
        ETag:
          $ref: '#/components/headers/metadata-etag'
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
          examples:
            Request ID:
              value: a4e390583b3ac581-MRS
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                $ref: '#/components/schemas/metadata'
            required:
              - metadata
          examples:
            Metadata Replaced:
              value:
                metadata:
                  externalId: 123
    set-metadata-created-response:
      description: Metadata created.
      headers:
        ETag:
          $ref: '#/components/headers/metadata-etag'
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
          examples:
            Request ID:
              value: a4e390583b3ac581-MRS
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                $ref: '#/components/schemas/metadata'
            required:
              - metadata
          examples:
            Metadata Created:
              value:
                metadata:
                  externalId: 123
    metadata-not-found:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Not Found:
              value:
                code: entity_not_found
                message: The entity metadata cannot be found
                details:
                  entity: metadata
            Entity Not Found:
              value:
                code: entity_not_found
                message: The <entity> cannot be found
                details:
                  entity: <entity>
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
          examples:
            Request ID:
              value: a4e390583b3ac581-MRS
    set-metadata-conflict-response:
      description: Business logic error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Already Exists:
              value:
                code: duplicate
                message: The entity metadata already exists
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
          examples:
            Request ID:
              value: a4e390583b3ac581-MRS
    metadata-precondition-failed:
      description: Precondition failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Precondition Failed:
              value:
                code: precondition_failed
                message: The If-Match header value does not match the current metadata
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
          examples:
            Request ID:
              value: a4e390583b3ac581-MRS
    metadata-payload-too-large:
      description: Payload too large.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Payload Too Large:
              value:
                code: content_too_large
                message: The entity metadata size is greater than maximum size limit
                details:
                  threshold:
                    unit: characters
                    limit: 1024
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
          examples:
            Request ID:
              value: a4e390583b3ac581-MRS
  schemas:
    metadata:
      type: object
      additionalProperties: true
      minProperties: 1
    error:
      description: The error information.
      allOf:
        - $ref: '#/components/schemas/feedback'
    feedback:
      description: A feedback message with a code and human-readable description.
      type: object
      properties:
        code:
          description: A short string with a brief explanation about the code reported.
          type: string
        message:
          description: A human-readable message providing more details.
          type: string
        details:
          description: Additional information about the feedback reported.
          type: object
          additionalProperties: true
      required:
        - code
        - message
  headers:
    metadata-etag:
      description: The entity metadata revision.
      schema:
        type: string
        pattern: ^"[A-Fa-f0-9]{64}"$
      examples:
        ETag:
          value: '"9ff2666faa58fabfc282eb90016e7182fe785d37dcdb861c6469cccaec13c876"'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /core/oauth2/token
          scopes:
            on-off-ramp.orders:create: Grants access to create orders.
            on-off-ramp.orders:read: Grants access to view orders.
            on-off-ramp.orders.metadata:read: Grants access to view orders metadata.
            on-off-ramp.orders.metadata:write: Grants access to modify orders metadata.
            on-off-ramp.orders.quotes:create: Grants access to create order quotes.

````