Actor Object

Overview

The actor object says who placed the order when it was not the customer: someone from your team, or a program of yours.

Send it only on those orders. On an ordinary customer order, leave it out.

Typical cases:

• a call-centre agent placed the order for a customer over the phone
• a back-office user created it manually
• someone at a physical store rang it up
• your ERP imported it, or a subscription renewed itself

Properties

All optional. Send what you have.

• name — which person, team or process, as you call them
• id — the actor's identifier in your system
• location — the physical place they worked from

Complete Reference

actor object

name string recommended

info

Which actor, as you call them: a person (ana.maria), a team (callcenter) or a process (sync_erp). Never the customer.

Lowercase, a-z 0-9 . _ + -, up to 64 characters.

name: "ana.maria"

id string recommended

info

The actor's identifier in your system — an operator id, a staff account id. Never the customer's id; that belongs in user.

Up to 128 characters.

id: "AG-7742"

location string optional

info

The physical place the actor worked from: depozit, showroom, or a branch name. Use the same spelling every time.

Lowercase, a-z 0-9 . _ + -, up to 64 characters.

location: "showroom"

Examples

Agent id

{
  "id": "AG-7742"
}

Agent with a name

{
  "name": "ana.maria",
  "id": "AG-7742"
}

Agent in a store

{
  "id": "OP-18",
  "location": "showroom"
}

Process

{
  "name": "sync_erp"
}

Where it goes in the payload

actor is a top-level key, next to user.

{
  "event":   { "name": "checkout_completed" },
  "context": { "environment": "prod", "data_source": "phone" },
  "actor":   { "id": "AG-7742" },
  "user":    { "email": "[email protected]" },
  "products": [ /* ... */ ]
}

user is the customer; actor is whoever placed the order.

Best Practices

• Leave it out for customer orders
• Send id whenever you have one
• One granularity for name — either individual agents (ana.maria, george) or the team (callcenter), not a mix
• name and location in plain lowercase — a-z 0-9 . _ + -, no spaces or diacritics
• Use dev while integrating — set context.environment to dev, or use the /test endpoint, and check the validation response before going live