Commands

Commands are sent to the POST /v3/commands endpoint (or the dedicated partner webhook endpoints below) as JSON payloads that extend BaseCommand.

Every command must include the BaseCommand envelope:

Field	Required	Description
`_v`	yes	Command-format version. Currently always `"1.0.0"`.
`_cid`	yes	Caller-generated id, used for idempotency and result polling.
`_type`	yes	One of the command names below.
`_metadata`	no	Optional `{ "ext-*": "..." }` map for caller-side correlation.

Successful execution emits an OrderStatusEvent (or equivalent) on the configured webhook. Polling for the per-command result is described in Polling.

Command index

`_type`	Purpose	Endpoint	Roles
`RefreshOrder`	Re-emit an `OrderStatusEvent` for an existing order.	`/v3/commands`	brand
`RefreshInvoice`	Re-emit an `InvoiceEvent` for an existing invoice.	`/v3/commands`	brand
`UpdateCustomer`	Update customer fields on an existing order.	`/v3/commands`	brand
`UpdateOrderExternalId`	Set the brand-side external order id.	`/v3/commands`	brand
`UpdateOrderInvoicingExternalId`	Set the invoicing-side external id.	`/v3/commands`	brand
`CreateOrderFromMapping`	Create one or more orders from a key/value mapping.	`/v3/commands`	brand
`ApplyCancellation`	Apply a cancellation reason to an order.	`/v3/commands`	brand
`SetJobAppointment`	Set or update a job's appointment (`appointment_confirmed`).	`/v3/commands/partner/appointment`	partner
`SetJobYourOrderId`	Set the partner-side external order id (`Job.extPartnerId`).	`/v3/commands/partner/your-order-id`	partner

Full per-field schemas are in the typedoc class pages — link from each section below.

Brand commands

RefreshOrder

RefreshOrder — explicitly re-emit an OrderStatusEvent for an existing order. Useful for resyncing a brand after webhook-delivery downtime.

{
  "_v": "1.0.0",
  "_cid": "refresh-2026-05-08-001",
  "_type": "RefreshOrder",
  "orderId": "a0Jjob1XXXX"
}

RefreshInvoice

RefreshInvoice — re-emit an InvoiceEvent for an existing invoice.

{
  "_v": "1.0.0",
  "_cid": "refresh-inv-2026-05-08-001",
  "_type": "RefreshInvoice",
  "invoiceId": "a0Iinv1XXXX"
}

UpdateCustomer

UpdateCustomer — update one or more customer fields on an existing order. Only the supplied fields are written; missing fields are left untouched.

UpdateOrderExternalId

UpdateOrderExternalId — set the brand-side external order id (eid) on an order.

UpdateOrderInvoicingExternalId

UpdateOrderInvoicingExternalId — set the invoicing-side external id (invoicing_eid) on an order.

CreateOrderFromMapping — create one or more orders from a list of { key, value } mapping items. Used when the integrator's payload doesn't naturally match the GID order shape and needs translation via a configured mapping.

ApplyCancellation

ApplyCancellation — apply a cancellation reason to an order. The resulting status depends on the specific cancellation reason (some go to cancelled, some to a brand-cancellation-pending interim state).

{
  "_v": "1.0.0",
  "_cid": "cancel-2026-05-08-001",
  "_type": "ApplyCancellation",
  "orderId": "a0Jjob1XXXX",
  "cancellationReason": "customer-no-longer-interested"
}

Partner commands

Partner endpoints require a PARTNER-role JWT (issued from /v3/auth/login → /v3/auth/access-token) and enforce partner ownership on the target job: the calling account must equal Job.partner.id or Job.partner.parentId (master/child support).

If the partner has an HMAC key configured on their WebhookConfiguration, the request must also include an x-webhook-signature header containing the SHA-256 HMAC (hex) of the raw request body computed with that key. Without a configured key, the header is optional.

SetJobAppointment

SetJobAppointment — set or update a job's appointment. Transitions the job to appointment_confirmed with inputs.appointment_date={ start, end }.

Endpoint: POST /v3/commands/partner/appointment

Identifier (one of the four):

Body field	Matches	Example
`jobApiId`	`Job.apiId`	`01-1234567`
`invoicingEid`	`Job.invoicingEid`	`4900063115`
`gidOrderNumber`	`Job.name`	`O-0000040381`
`yourOrderID`	`Job.extPartnerId`	`S4C-ORDER-42`

Plus:

appointmentStart (ISO8601, required)
appointmentEnd (ISO8601, optional)

{
  "_v": "1.0.0",
  "_cid": "partner-appt-2026-05-08-001",
  "_type": "SetJobAppointment",
  "jobApiId": "01-1234567",
  "appointmentStart": "2026-05-15T09:00:00Z",
  "appointmentEnd": "2026-05-15T11:00:00Z"
}

SetJobYourOrderId

SetJobYourOrderId — set (or overwrite) the partner-side external order id on a specific job. Writes Job.extPartnerId (column partner_eid__c); does not change the job's status.

Endpoint: POST /v3/commands/partner/your-order-id

Identifier (one of three; yourOrderID is the value being set, so it can't double as the lookup key here):

Body field	Matches	Example
`jobApiId`	`Job.apiId`	`01-1234567`
`invoicingEid`	`Job.invoicingEid`	`4900063115`
`gidOrderNumber`	`Job.name`	`O-0000040381`

Plus:

yourOrderID (string, required) — the new value to store on Job.extPartnerId.

{
  "_v": "1.0.0",
  "_cid": "partner-yorderid-2026-05-08-001",
  "_type": "SetJobYourOrderId",
  "jobApiId": "01-1234567",
  "yourOrderID": "S4C-ORDER-42"
}

Errors

HTTP status	Meaning
`400`	Body validation failed (missing required field, no identifier supplied, etc.)
`401`	Missing or invalid HMAC signature when one is configured.
`403`	Authenticated, but the calling account is not the partner on the target job (partner endpoints).
`404`	No job matched the supplied identifier (partner endpoints).

Asynchronous failures during command execution are reported via CommandErrorEvent and can be polled per _cid (see Polling).