Hostcom Dispatches

Read-only. These endpoints expose the history and status of hostcom dispatches. The hostcom write path — staging a file and sending it to stores — is the fan-out hostcom_batch operation. The direct dispatch/apply POST endpoints were removed; all new writes must go through fan-out.

---

List Hostcom Dispatches

GET /v1/hostcom/dispatches

Authentication: OAuth Token (service_account or user)

Permission: rorcex:hostcom-batches.view

Request Query Parameters

Field	Type	Required	Description
fanout_target_id	string	No	Accepts only the literal string "null" — filters results to pre-fan-out legacy dispatches that were not routed through the fan-out framework. Any other value returns 422.
per_page	integer	No	Results per page, 1–200 (default: 50)

Response

{
  "data": [
    {
      "dispatch_id": "dsp_00000k1L2m3N4o5",
      "apply_mode": "batch",
      "note": "Weekly price change — June week 2",
      "created_at": "2026-06-11T14:35:00Z",
      "applied_at": "2026-06-11T14:37:42Z",
      "target_count": 13,
      "status_rollup": {
        "pending_upload": 0,
        "pending_batch_resolve": 0,
        "pending_apply": 0,
        "applying": 0,
        "polling": 0,
        "completed": 13,
        "errored": 0
      }
    }
  ]
}

Status: 200 OK

Field	Type	Description
data	array	List of dispatch summaries
data[].dispatch_id	string	Unique hostcom dispatch identifier
data[].apply_mode	string	Apply mode used (batch or immediate)
data[].note	string|null	Free-text annotation
data[].created_at	string	ISO 8601 creation timestamp
data[].applied_at	string|null	ISO 8601 timestamp when the last target reached a terminal state
data[].target_count	integer	Number of store targets in this dispatch
data[].status_rollup	object	Count of targets in each hostcom state machine status

Errors

See Errors for shared error envelope format.

---

Get Hostcom Dispatch

Retrieve full detail for a single hostcom dispatch, including per-target state machine status and RORC identifiers.

GET /v1/hostcom/dispatches/{id}

Authentication: OAuth Token (service_account or user)

Permission: rorcex:hostcom-batches.view

Path Parameters

Parameter	Type	Description
id	string	Hostcom dispatch identifier

Response

{
  "dispatch_id": "dsp_00000k1L2m3N4o5",
  "file_id": "hkx_00000k1L2m3N4o5",
  "apply_mode": "batch",
  "note": "Weekly price change — June week 2",
  "created_at": "2026-06-11T14:35:00Z",
  "applied_at": "2026-06-11T14:37:42Z",
  "targets": [
    {
      "store_org_id": "org_00000k1L2m3N4o5",
      "status": "completed",
      "rorc_file_id": 10042,
      "rorc_batch_id": 20017,
      "rorc_operation_id": 30091,
      "record_count_total": 148,
      "record_count_added": 12,
      "record_count_changed": 135,
      "record_count_deleted": 1,
      "record_count_errored": 0
    }
  ]
}

Status: 200 OK

Field	Type	Description
dispatch_id	string	Hostcom dispatch identifier
file_id	string	The staged hostcom file that was dispatched
apply_mode	string	batch or immediate
note	string|null	Free-text annotation
created_at	string	ISO 8601 creation timestamp
applied_at	string|null	ISO 8601 completion timestamp
targets	array	Per-store target records
targets[].store_org_id	string	Store organization hashkey
targets[].status	string	Hostcom state machine status (see table below)
targets[].rorc_file_id	integer|null	RORC file ID assigned by the lane after upload
targets[].rorc_batch_id	integer|null	RORC batch ID assigned when the batch was resolved
targets[].rorc_operation_id	integer|null	RORC operation ID assigned on apply
targets[].record_count_total	integer|null	Total records processed by the lane
targets[].record_count_added	integer|null	Records added
targets[].record_count_changed	integer|null	Records changed
targets[].record_count_deleted	integer|null	Records deleted
targets[].record_count_errored	integer|null	Records rejected by the lane

Hostcom State Machine Status Values

Status	Description
pending_upload	File has not yet been uploaded to the lane
pending_batch_resolve	File uploaded; waiting for the lane to assign a batch ID
pending_apply	Batch resolved; waiting to trigger apply
applying	Apply triggered; lane is processing the file
polling	Apply in progress; polling the lane for completion
completed	Lane confirmed all records processed
errored	Lane reported an error during upload, batch resolution, or apply

Errors

See Errors for shared error envelope format.

---

List Target Error Records

Retrieve the individual record-level errors reported by the RORC lane for a target that reached errored status.

GET /v1/hostcom/dispatches/{dispatch}/targets/{target}/error-records

Authentication: OAuth Token (service_account or user)

Permission: rorcex:hostcom-batches.view

Path Parameters

Parameter	Type	Description
dispatch	string	Hostcom dispatch identifier
target	string	Store organization hashkey

Precondition

The target must be in errored status. If the target is in any other status, the endpoint returns 409 Conflict.

Request Query Parameters

Field	Type	Required	Description
page	integer	No	Page offset (zero-based, default: 0)
per_page	integer	No	Results per page (default: 50)

Response

The response uses RORC's PascalCase paged envelope, passed through as-is from the lane.

{
  "Items": [
    {
      "RecordIndex": 14,
      "RecordType": "ProdRetail",
      "ErrorCode": "INVALID_PRICE",
      "ErrorDescription": "Retail price must be greater than zero"
    },
    {
      "RecordIndex": 27,
      "RecordType": "ProdRetail",
      "ErrorCode": "ITEM_NOT_FOUND",
      "ErrorDescription": "No item found for ItemCode 001234567890"
    }
  ],
  "TotalCount": 2,
  "Offset": 0,
  "Limit": 50
}

Status: 200 OK

Field	Type	Description
Items	array	Error records reported by the lane
Items[].RecordIndex	integer	Zero-based index of the record in the hostcom file
Items[].RecordType	string	Record type of the errored row (e.g., ProdRetail)
Items[].ErrorCode	string	Machine-readable error code from the lane
Items[].ErrorDescription	string	Human-readable description of the error
TotalCount	integer	Total number of error records for this target
Offset	integer	Current page offset
Limit	integer	Page size used for this response

Errors

409 — Target not in errored status:

{
  "error": "hostcom_target_not_errored",
  "message": "Error records are only available for targets in errored status. Current status: completed"
}

See Errors for shared error envelope format.

---

Changelog

Date	Change
2026-06-11	Initial publication.