Create Receipt Type - Truthlocks Documentation

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>"
}
'

import requests

url = "https://api.truthlocks.com/v1/receipt-types"

payload = {
    "name": "<string>",
    "display_name": "<string>",
    "schema": {},
    "description": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    display_name: '<string>',
    schema: {},
    description: '<string>'
  })
};

fetch('https://api.truthlocks.com/v1/receipt-types', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/receipt-types",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'display_name' => '<string>',
    'schema' => [
        
    ],
    'description' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/receipt-types"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"schema\": {},\n  \"description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.truthlocks.com/v1/receipt-types")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"schema\": {},\n  \"description\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/receipt-types")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"schema\": {},\n  \"description\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "name": "<string>",
  "display_name": "<string>",
  "schema": {},
  "created_at": "<string>"
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

POST

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>"
}
'

import requests

url = "https://api.truthlocks.com/v1/receipt-types"

payload = {
    "name": "<string>",
    "display_name": "<string>",
    "schema": {},
    "description": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    display_name: '<string>',
    schema: {},
    description: '<string>'
  })
};

fetch('https://api.truthlocks.com/v1/receipt-types', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/receipt-types",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'display_name' => '<string>',
    'schema' => [
        
    ],
    'description' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/receipt-types"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"schema\": {},\n  \"description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.truthlocks.com/v1/receipt-types")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"schema\": {},\n  \"description\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/receipt-types")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"schema\": {},\n  \"description\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "name": "<string>",
  "display_name": "<string>",
  "schema": {},
  "created_at": "<string>"
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

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

Field	Type	Required	Description
`name`	string	Yes	Unique snake_case identifier (e.g. `invoice_receipt`). Must not conflict with platform type names.
`display_name`	string	Yes	Human-readable label shown in the console UI.
`version`	string	No	SemVer string (default `1.0.0`). Create multiple versions to manage schema evolution.
`schema`	object	Yes	Valid JSON Schema (draft 2020-12) describing the required `payload` structure.
`description`	string	No	Plain-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

​Request body

​Schema Requirements

​Versioning

​Responses

Authorizations

Body

Response

Request body

Schema Requirements

Versioning

Responses