Transaction Type Mappings¶

Map your own POS transaction codes (source_transaction_type) to HQ standard transaction types.

Upload mapping¶

PUT /mappings/transaction-types

Uploads your full mapping. This is a full replacement: always send the complete list. Any previous mapping not included is removed.

Authentication: API key (x-functions-key)

Request body¶

Field	Type	Required	Description
batch_id	UUID	Yes	Idempotency key
mappings	array	Yes	At least 1 item
mappings[].source_code	string	Yes	Your POS code, as sent in `source_transaction_type`. Must be unique within the request.
mappings[].source_name	string	No	Your POS name for the code
mappings[].standard_code	string	Yes	HQ standard code from Transaction Types

{
  "batch_id": "6f1c2e0a-3b7d-4c55-9a0e-1f2b3c4d5e6f",
  "mappings": [
    { "source_code": "Sale",   "source_name": "Sale",   "standard_code": "SALE" },
    { "source_code": "Refund", "source_name": "Refund", "standard_code": "REFUND" },
    { "source_code": "Void",   "source_name": "Void",   "standard_code": "VOID" }
  ]
}

Response¶

202 Accepted

{ "batch_id": "6f1c2e0a-3b7d-4c55-9a0e-1f2b3c4d5e6f", "status": "ACCEPTED", "record_count": 3, "warnings": [] }

Resending the same batch_id returns 200 with "status": "ALREADY_RECEIVED".

Errors¶

HTTP	code	When
400	UNKNOWN_STANDARD_CODE	A `standard_code` is not in the standard list
400	INVALID_PAYLOAD	Missing fields, duplicate `source_code`, etc.
401	UNAUTHORIZED	Missing or invalid API key

Get current mapping¶

GET /mappings/transaction-types

Returns the mapping currently in effect for your account.

Authentication: API key (x-functions-key)

Response¶

200 OK

Field	Type	Description
partner_id	string	Your partner code
batch_id	UUID \| null	`batch_id` of the mapping in effect; `null` if you have never uploaded one
updated_at	timestamp \| null	Last update time (UTC)
mappings	array	Same structure as the upload; `[]` if you have never uploaded one

{
  "partner_id": "US-ADL-001",
  "batch_id": "6f1c2e0a-3b7d-4c55-9a0e-1f2b3c4d5e6f",
  "updated_at": "2026-10-15T09:00:00Z",
  "mappings": [
    { "source_code": "Refund", "source_name": "Refund", "standard_code": "REFUND" }
  ]
}

Notes¶

Note

Transactions with an unmapped source_transaction_type are still accepted, but they are excluded from HQ reports until you upload a mapping for that code. HQ then re-maps them automatically.