Skip to main content

Metafield Reporting

The order metafields Velocity writes to Shopify, and how to report on them.

Velocity writes metafields to orders in Shopify so you can report on commission using Shopify's own analytics rather than exporting from Velocity. They are available as dimensions in the freeform report builder, and through the Admin API.

Available metafields

Name

Key

Contents

Commission

commission

Every commission on the order, as JSON

Placed By Rep: Name

placed_by_rep_name

The rep who placed the order in the Rep Portal

Placed By Rep: Email

placed_by_rep_email

That rep's email address

Placed By Rep: Identifier

placed_by_rep_identifier

That rep's identifier

These four use Velocity's reserved app namespace, so you select them by name in the report builder rather than typing a namespace. They are read-only.

Placed By Rep is not the same as the commissioned rep. It records who created the order in the Rep Portal, and is only written for orders that came from a rep's draft order. The commissioned rep is determined separately, by territory, ownership, or override, and is often a different person. To report on who was paid, use the Commission metafield.

Reading the Commission metafield

An order can produce several commissions: one for each rep in the team's hierarchy, in each Commission Program the order touches. The Commission metafield therefore holds a JSON array with one entry per commission, not a single total.

Each entry contains:

  • amount and currency_code, the commission itself. Clawbacks appear as negative amounts.

  • rep_name, rep_email, rep_identifier, and rep_level, identifying the commissioned rep and their level in the team.

  • program_name and program_id, the Commission Program the rules came from.

  • origin, how the rep was assigned: team, ownership, override, rep_override, or manual.

  • event and event_date, one of order_placed, terms_payment, or refund. The date is empty while commission is held as Upcoming....

Velocity rewrites the metafield whenever the order's commissions change, including when a held commission is finalized or a refund is clawed back.

Postal Code Override

Velocity also reads a writable metafield on orders, Postal Code Override, using the namespace velocity and the key postal_code_override. Unlike the metafields above, you set this one. See Postal Code Overrides.

Beyond metafields

Metafields cover reporting on orders inside Shopify. If you need to read commissions outside Shopify, or manage reps, teams, and ownerships programmatically, use the REST API instead. See Velocity API.

Did this answer your question?