Skip to content
English
  • There are no suggestions because the search field is empty.

Order Custom Properties & Metadata

Every Order in Ambassador comes with standard fields like order ID, revenue amount, and customer email. But sometimes your program needs more — a subscription tier, a product category, a referral type, or any other data point unique to your business. Order Custom Properties let you define and pass that extra information so it's available for automation filtering, reporting, and API responses. 🗂️

What is Order Metadata?

Order metadata allows you to send additional fields with an Order to Ambassador beyond the built-in fields. This custom data travels alongside your orders and is primarily used to:

  • Apply conditions inside Automation triggers and If/Else outcomes (e.g., only trigger a reward if referralType equals "customer")
  • Make the data visible as columns in the Orders table for easy reference
  • Include the data in API responses when retrieving order records

Looking for custom fields stored on the Contact record? That's a separate feature — see Contact Custom Properties.

How to Configure Order Custom Properties

  1. Go to Admin → System Settings and scroll down to Order Custom Properties.
  2. Click Customize to open the property editor.
  3. Enter a Name for the field. Names may only contain letters, numbers, and underscores.
  4. Choose the Type that matches your data: String, Integer, Decimal, or Boolean.
  5. Toggle Required on if this field must always be present — Orders without this field will fail to create.
  6. Click Add Property to add more fields as needed.
  7. Click Save when finished.

Reserved Field Names

The following names are reserved by Ambassador and cannot be used as custom property names:

line_items, commissions, rewards, created_at, updated_at, company_metadata, uid, company_user_uid, campaign_uid, affiliate_uid, advocate, order_id, revenue_amount, currency, source, external_status, ip_address, mbsy_source, inactive_referral_attribution, referral_attribution, flow_execution_uid, hubspot_dealstage, history

How to Pass Metadata via the API

Once your custom properties are configured, you can include them in the company_metadata field when creating an order via the API:

{
  "order_id": "xxxx",
  "customer_email": "customer@example.com",
  "company_metadata": {
    "referralType": "customer",
    "referrerAmount": 150
  }
}

When retrieving an order via the order/get endpoint, your custom fields are returned inside the company_metadata object:

{
  "order_id": "xxxx",
  "customer_email": "customer@example.com",
  "company_metadata": {
    "referralType": "customer",
    "referrerAmount": 150
  }
}

Custom metadata can also be passed via other data-layer integrations (Salesforce, HubSpot, etc.).

How to Use Metadata in Automations

After configuring your custom properties, the fields are available as filter conditions in Automations. For example, you could set up a trigger that fires only when an Order is created and the referralType field equals "customer" — allowing you to apply different automation logic based on your custom order data.

How to View Metadata in the Orders Table

Each configured custom property appears as an additional column in the Orders table, labeled with the property name you defined. This makes it easy to see and filter your orders by your custom data points directly in the Ambassador UI.

Good to Know

  • Custom properties must be configured in Ambassador before you start passing them via the API or integrations.
  • Marking a property as Required means any order creation attempt without that field will fail — use this only for fields your system always sends.
  • Property names are case-sensitive and must match exactly between the Admin configuration and your API calls.
  • For questions or help with Order metadata, contact support@getambassador.com.
  • Related articles: Orders Overview, Automations Overview, System Settings