Hostcom Files

Stage hostcom files for delivery to RORC lanes — either by uploading a finished pipe-delimited file, or by authoring one from structured JSON rows. The file_id returned by either endpoint is the input to the fan-out hostcom_batch operation, which distributes the file to one or more store lanes.

---

Upload Hostcom File

Upload a finished pipe-delimited hostcom Formatter file.

POST /v1/hostcom/files

Authentication: OAuth Token (service_account or user)

Permission: rorcex:hostcom-batches.create

Request Body

Multipart form-data.

Field	Type	Required	Description
file	file	Yes	A pipe-delimited hostcom Formatter file

Response

{
  "file_id": "hkx_00000k1L2m3N4o5",
  "original_filename": "price-update-2026-06-11.txt",
  "byte_size": 14823,
  "content_hash": "sha256:a3f1c8...",
  "created_at": "2026-06-11T14:30:00Z"
}

Status: 201 Created

Field	Type	Description
file_id	string	Unique identifier for this staged file — pass to fan-out hostcom_batch
original_filename	string	Original name of the uploaded file
byte_size	integer	File size in bytes
content_hash	string	SHA-256 digest of the file contents
created_at	string	ISO 8601 timestamp

Errors

See Errors for shared error envelope format.

---

Author Hostcom File

Author a hostcom file from structured JSON rows. RORCex serialises the rows into a valid pipe-delimited Formatter file and returns a file_id you can immediately pass to fan-out.

POST /v1/hostcom/files/author

Authentication: OAuth Token (service_account or user)

Permission: rorcex:hostcom-batches.create

Request Body

Two accepted shapes — the multi-record shape is recommended for new integrations.

Multi-record (recommended)

{
  "records": [
    {
      "record_type": "ProdRetail",
      "action_code": "C",
      "apply_via": "B",
      "rows": [
        { "ItemCode": "001234567890", "RetailPrice": "3.99", "... ": "..." }
      ]
    },
    {
      "record_type": "ShelfTag",
      "action_code": "A",
      "apply_via": "I",
      "rows": [
        { "ItemCode": "001234567890", "... ": "..." }
      ]
    }
  ],
  "note": "Weekly price change — June week 2"
}

Field	Type	Required	Description
records	array	Yes	One or more record blocks (see below)
records[].record_type	string	Yes	One of the 29 registered record types (see table below)
records[].action_code	string	Yes	A (Add), C (Change), D (Delete). ProdLabel also accepts O (Open) and L (Close)
records[].apply_via	string	Yes	B (Batch) or I (Immediate). Immediate-only record types accept only I — see allowed_apply_via in GET /v1/hostcom/record-types
records[].rows	array	Yes	Row objects for this record type — see GET /v1/hostcom/record-types for the per-type row schema
note	string	No	Free-text annotation stored with the file

Legacy single-record shape

{
  "record_type": "ProdRetail",
  "rows": [
    { "ItemCode": "001234567890", "RetailPrice": "3.99", "... ": "..." }
  ],
  "note": "Price fix"
}

Field	Type	Required	Description
record_type	string	Yes	One of the 29 registered record types
apply_via	string	No	B or I. Defaults to B, or I for an Immediate-only record type
rows	array	Yes	Row objects — see GET /v1/hostcom/record-types
note	string	No	Free-text annotation

The legacy shape defaults action_code to C, and apply_via to B (I for an Immediate-only record type). Prefer the multi-record shape for new work.

Registered Record Types

Record Type	Description
ProdRetail	Retail price maintenance
ItemDeal	Deal/sale pricing
Department	Department configuration
ProdMaint	Product maintenance
Vendor	Vendor records
VendorItem	Vendor–item linkage
ShelfTag	Shelf tag printing
ProdTagLoc	Product tag location
ProdLabel	Product label printing (also accepts O Open and L Close action codes)
Category	Category records
ProdNonRtl	Non-retail product attributes
ProdTax	Tax rate assignments
ProdScale	Scale product configuration
Premium	Premium pricing rules
Discount	Discount rules
DiscountDept	Department-level discount rules
ProdPremium	Product–premium linkage
ReceiptGroup	Receipt group configuration
UOM	Unit of measure configuration (code, description, price-per-unit code and divisor)
MiscVar	Store system variable (C only, I only)
SalesRes	Sales restriction definition (I only)
SalesResAge	Sales restriction age check (I only)
SalesResHour	Sales restriction restricted hours (I only)
SalesResVal	Sales restriction tracking-value maximum (I only)
SalesResDate	Sales restriction restricted-date prompt (I only)
SalesResDay	Sales restriction restricted date (A/D only, I only)
SalesResVis	Sales restriction visual check (I only)
Dept-SlsRstr	Enable or disable a sales restriction on a department (C only)
ProdSlsRstr	Enable or disable a sales restriction on a product (C only)

Category, ShelfTag, Discount, DiscountDept, every SalesRes* type and MiscVar are Immediate-only: a record block for one of them with apply_via: "B" is rejected with 422 hostcom_record_validation_failed (errors.apply_via).

Row schemas — the required keys, field types, and allowed action codes for each record type are not enumerated here to avoid documentation drift. Use GET /v1/hostcom/record-types to retrieve the live machine-readable schema catalog before building author payloads.

Response

{
  "file_id": "hkx_00000a1B2c3D4e5",
  "generated_filename": "authored-prodretail-20260611T143000Z.txt",
  "byte_size": 3241,
  "content_hash": "sha256:b7e2d1...",
  "dedup_hit": false,
  "row_count": 47
}

Status: 201 Created

Field	Type	Description
file_id	string	Unique identifier for this staged file — pass to fan-out hostcom_batch
generated_filename	string	Auto-generated filename for the serialised Formatter file
byte_size	integer	Size of the generated file in bytes
content_hash	string	SHA-256 digest of the generated file
dedup_hit	boolean	true if identical content was already staged; the existing file_id is returned
row_count	integer	Total number of data rows across all record blocks

Errors

Validation failures return 422 hostcom_record_validation_failed:

{
  "error": "hostcom_record_validation_failed",
  "record_type": "SalesRes",
  "row_index": 0,
  "group_index": 1,
  "errors": { "apply_via": ["SalesRes accepts apply_via I only."] },
  "message": "Row 0 of record 'SalesRes' failed validation."
}

Field	Type	Description
record_type	string	Record type of the failing block
row_index	integer	0-based row within that block (0 for a block-level failure such as apply_via)
group_index	integer	0-based position of the failing block in records (0 for the legacy shape)
errors	array | object	A list of row-schema messages, or an object keyed by what failed (apply_via, rows, semantic, action)

See Errors for the shared error envelope.

---

List Record Types

Retrieve the machine-readable schema catalog for all registered hostcom record types. Use this endpoint to discover the row schema (required keys, field types, allowed action codes) for each record type before building author payloads.

GET /v1/hostcom/record-types

Authentication: OAuth Token (service_account or user)

Permission: rorcex:hostcom-batches.view

Response

{
  "data": [
    {
      "record_type": "ProdRetail",
      "label": "Retail Price Maintenance",
      "allowed_actions": ["A", "C", "D"],
      "allowed_apply_via": ["B", "I"],
      "row_schema": {
        "type": "object",
        "required": ["ItemCode", "RetailPrice"],
        "properties": {
          "ItemCode": { "type": "string", "maxLength": 13 },
          "RetailPrice": { "type": "string" }
        }
      },
      "sequence_hint": 10
    }
  ]
}

Status: 200 OK

Field	Type	Description
data	array	One entry per registered record type
data[].record_type	string	Record type identifier — use as record_type in author payloads
data[].label	string	Human-readable display name
data[].allowed_actions	array	Action codes valid for this record type (A, C, D, and for ProdLabel also O, L)
data[].allowed_apply_via	array	apply_via values this record type accepts — ["I"] for Immediate-only types, otherwise ["B", "I"]
data[].row_schema	object	JSON Schema object describing row fields — use this to validate row objects before calling author
data[].sequence_hint	integer	Suggested ordering when multiple record types appear in the same file

Errors

See Errors for shared error envelope format.

---

Changelog

Date	Change
2026-06-11	Initial publication.
2026-10-07	Added 12 control-file record types (Receipt Group, UOM, MiscVar, Sales Restrictions). Immediate-only types now reject apply_via: "B"; allowed_apply_via added to the record-types catalog; group_index added to the validation error; the legacy shape accepts apply_via.