Skip to main content
POST
/
v1
/
receipt-types
Create receipt type
curl --request POST \
  --url https://api.truthlocks.com/v1/receipt-types \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "display_name": "<string>",
  "schema": {},
  "description": "<string>"
}
'
{
  "name": "<string>",
  "display_name": "<string>",
  "schema": {},
  "created_at": "<string>"
}
Creates a tenant-custom receipt type with a JSON Schema for payload validation. Platform-defined types (payment_receipt, security_event_receipt, delivery_receipt, compliance_receipt, custom_receipt) are read-only and cannot be overridden or replaced. Custom types are isolated to the authenticated tenant by row-level security. Other tenants cannot see or use your custom types.

​
Request body

FieldTypeRequiredDescription
namestringYesUnique snake_case identifier (e.g. invoice_receipt). Must not conflict with platform type names.
display_namestringYesHuman-readable label shown in the console UI.
versionstringNoSemVer string (default 1.0.0). Create multiple versions to manage schema evolution.
schemaobjectYesValid JSON Schema (draft 2020-12) describing the required payload structure.
descriptionstringNoPlain-text description for documentation.

​
Schema Requirements

The schema field must be a valid JSON Schema (draft 2020-12). Include a required array to enforce mandatory payload fields when minting. 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["invoice_number", "amount", "currency"],
  "properties": {
    "invoice_number": { "type": "string" },
    "amount":         { "type": "integer", "description": "Amount in smallest currency unit" },
    "currency":       { "type": "string", "minLength": 3, "maxLength": 3 }
  },
  "additionalProperties": false
}

​
Versioning

Create multiple versions of the same type by passing different version values (1.0.0, 2.0.0, etc.). Receipts always pin the version at mint time so existing receipts are unaffected when you introduce a new version. To deprecate an old version, use PATCH /v1/receipt-types/{name} with {"status": "deprecated"}.

​
Responses

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
name
string
required

Machine-readable receipt type name

​
display_name
string
required

Human-readable name

​
schema
object
required

JSON Schema for payload validation

​
description
string

Response

Receipt type created

​
name
string
​
display_name
string
​
schema
object
​
created_at
string