Attaching Custom Data to Orders

Organizations can attach custom reference data to invites, which then automatically flows through to orders. This allows you to track internal identifiers, custom fields, or any other data needed to integrate orders with your systems.

How It Works

When you create an invite with custom metadata, that data is automatically copied to any order placed using that invite. You can then retrieve this data when fetching order details, making it easy to connect orders back to your internal records.

Flow:

1. Create an invite with your custom metadata
2. User places an order using that invite
3. Metadata is automatically copied to the order
4. Retrieve the metadata from the order details endpoint

Creating an Invite with Metadata

Use the "create invite" endpoint to attach custom data to the invite:

Endpoint: POST /v1/vid/invites - Doc

Request Body:

{
  "metadata": {
    "internal_reference_id": "id",
    "custom_field": "any_value_you_need"
  }
  // ... other invite field
}

The metadata field accepts any valid JSON object. You can include any key-value pairs that make sense for your needs.

Retrieving Metadata from Orders

Once an order is placed using the invite, you can retrieve the metadata from the "order details" endpoint:

Endpoint: GET /v1/orders/{id} - Doc

Response:

{
  "id": "ORD-12345",
  "additionalMetadata": {
    "internal_reference_id": "id",
    "custom_field": "any_value_you_need"
  }
  // ... other order fields
}

The metadata you provided when creating the invite will be available in the additionalMetadata field.

Common Usecases

• Internal User Mapping: Store your organization's internal user ID to map orders back to specific users in your system. This allows you to maintain your own user records while leveraging Cerebrum's API, making it easy to sync order data with your system.
• Internal Reference Tracking: Map orders to your internal systems using custom IDs.

Best Practices

• Keep metadata focused on reference data rather than sensitive information.
• Use consistent key naming conventions across your organization.
• Document your metadata schema internally for your team.
• Consider the size of your metadata objects to keep API responses performant.