Skip to content
Browse the documentation
Reference

Publish evidence: quickstart, source bindings and atomic batches

This page is generated from the application (scripts/gen_evidence_docs.py): the programs, the tables and the error codes below are the ones the product serves. In the product, step 5 of the refund setup shows the…

Last changed Markdown versionllms.txt

This page is generated from the application (scripts/gen_evidence_docs.py): the programs, the tables and the error codes below are the ones the product serves. In the product, step 5 of the refund setup shows the same programs with your workspace's own source ids.

CommitLayer verifies what an agent did against records the agent cannot write. Two processes take part, each with its own key:

  • the recorder runs in the agent's runtime and records what the agent is about to do (POST /v1/actions);
  • the evidence publisher runs in your backend and publishes what your systems of record say happened (POST /v1/evidence/batches).

Quickstart

  1. In the product, choose the refund workflow, name the system behind each role and confirm the contract.
  2. Create the two keys and download their environment files. Each file holds one key and is read by one process.
  3. Attest each source your backend sends (Owner or Admin, signed in). Until then its records are stored as agent-reported and cannot satisfy the contract.
  4. Run the recorder program with the order and the amount.
  5. Run the evidence program with the same order and amount. It checks the batch, then publishes it whole.

The two environment files, as the product serves them. The key line is empty; the browser fills it with the key it just created and sends it nowhere.

commitlayer-recorder.env

# CommitLayer recorder process (the agent runtime).
# Keep this file server-side. Never put the Evidence pipeline key in this process.
COMMITLAYER_API_URL=https://api.commitlayer.ai
COMMITLAYER_WORKSPACE_ID=ten_your_workspace
COMMITLAYER_CONTRACT_ID=scop_refund_order
COMMITLAYER_RECORDER_KEY=

commitlayer-evidence.env

# CommitLayer evidence process (the evidence backend).
# Keep this file server-side. Never put the Runtime recorder key in this process.
COMMITLAYER_API_URL=https://api.commitlayer.ai
COMMITLAYER_WORKSPACE_ID=ten_your_workspace
COMMITLAYER_CONTRACT_ID=scop_refund_order
COMMITLAYER_EVIDENCE_KEY=

Every program takes ORDER_ID AMOUNT and does nothing without them: it prints its usage and exits 2. A program for a real integration carries no sample order and no sample amount; sample values belong to the workspace sample.

Language Install Record Publish evidence Checkpoints alone
Python pip install -r requirements.txt python record_refund.py ORDER_ID AMOUNT python publish_evidence.py ORDER_ID AMOUNT python publish_evidence.py --checkpoint-only
TypeScript npm install npm run record -- ORDER_ID AMOUNT npm run evidence -- ORDER_ID AMOUNT npm run evidence -- --checkpoint-only
REST needs bash and curl bash record-action.sh ORDER_ID AMOUNT bash publish-evidence.sh ORDER_ID AMOUNT bash publish-evidence.sh --checkpoint-only

The programs pin commitlayer==0.1.5 (PyPI) and commitlayer@0.1.6 (npm), the published versions they are certified on (scripts/certify_quickstart.py runs these exact files in two workspaces before every release).

Publish what your systems actually have

Run with an order and an amount, an evidence program publishes every record of the refund once; running it again for the same order is the same records, and stores nothing twice. A real backend does not always have every record. After ORDER_ID AMOUNT the three programs take the same two options:

Option What it publishes
--reported SOURCE[,SOURCE] Only the records those sources have for the order. The source ids are your workspace's own (here: stripe, shopify, zendesk). A source with no record yet is left out, and its checkpoint is still sent: that is how a missing record settles FAIL at the deadline.
--reported SOURCE --record-id ID One more record of that source, under the source's own id for it. A second refund on the same order is a second record, with its own reference, never a replay of the first.
--checkpoint-only The checkpoints alone, after a scan that found nothing new.

A source id the program has no record for, or --record-id without exactly one source, is refused with the usage (exit 2) before anything is sent. Every run is still one preflight and one atomic batch.

The product shows the following beside the programs (the evidence publisher's page of the checklist, and Connections, "Integration files"), with your workspace's own source ids; INSTALL.md carries the same text, and GET /v1/onboarding/refund/quickstart serves it as situations. With Stripe, Shopify and Zendesk:

A refund that completed

The agent refunded the order and every system has its record.

  1. Record the action:
    • Python: python record_refund.py ORDER_ID AMOUNT
    • TypeScript: npm run record -- ORDER_ID AMOUNT
    • REST (curl): bash record-action.sh ORDER_ID AMOUNT
  2. Publish:
    • Python: python publish_evidence.py ORDER_ID AMOUNT
    • TypeScript: npm run evidence -- ORDER_ID AMOUNT
    • REST (curl): bash publish-evidence.sh ORDER_ID AMOUNT

Result: Pending until the records arrive, then PASS: every expected effect was observed.

A refund above the contract's limit

The agent refunds more than the largest refund the contract allows.

  1. Record the action:
    • Python: python record_refund.py ORDER_ID AMOUNT_ABOVE_THE_LIMIT
    • TypeScript: npm run record -- ORDER_ID AMOUNT_ABOVE_THE_LIMIT
    • REST (curl): bash record-action.sh ORDER_ID AMOUNT_ABOVE_THE_LIMIT
  2. Publish:
    • Python: python publish_evidence.py ORDER_ID AMOUNT_ABOVE_THE_LIMIT
    • TypeScript: npm run evidence -- ORDER_ID AMOUNT_ABOVE_THE_LIMIT
    • REST (curl): bash publish-evidence.sh ORDER_ID AMOUNT_ABOVE_THE_LIMIT

Result: FAIL at once on policy (the amount is above the limit); the outcome is judged apart, and reads PASS once the records arrive.

A system has no record: the refund never reached stripe

The agent says it refunded the order, and stripe has no refund for it. Publish what the other systems have, and keep sending checkpoints after every scan.

  1. Record the action:
    • Python: python record_refund.py ORDER_ID AMOUNT
    • TypeScript: npm run record -- ORDER_ID AMOUNT
    • REST (curl): bash record-action.sh ORDER_ID AMOUNT
  2. Publish:
    • Python: python publish_evidence.py ORDER_ID AMOUNT --reported shopify,zendesk
    • TypeScript: npm run evidence -- ORDER_ID AMOUNT --reported shopify,zendesk
    • REST (curl): bash publish-evidence.sh ORDER_ID AMOUNT --reported shopify,zendesk
  3. Publish (after every later scan):
    • Python: python publish_evidence.py --checkpoint-only
    • TypeScript: npm run evidence -- --checkpoint-only
    • REST (curl): bash publish-evidence.sh --checkpoint-only

Result: Pending while the settlement window is open. Once stripe's checkpoint passes the settlement deadline with no refund, FAIL: the expected stripe refund is missing.

A second refund on the same order

stripe reports another refund for an order that was already refunded. Publish it under stripe's own id for that refund.

  1. Publish:
    • Python: python publish_evidence.py ORDER_ID AMOUNT --reported stripe --record-id SECOND_REFUND_ID
    • TypeScript: npm run evidence -- ORDER_ID AMOUNT --reported stripe --record-id SECOND_REFUND_ID
    • REST (curl): bash publish-evidence.sh ORDER_ID AMOUNT --reported stripe --record-id SECOND_REFUND_ID

Result: The order's action is verified again by itself. A settled PASS becomes FAIL: a duplicate refund, with the earlier PASS kept in its version history.

Records for a different order

Your systems report a refund for another order than the one the agent acted on.

  1. Record the action:
    • Python: python record_refund.py ORDER_ID AMOUNT
    • TypeScript: npm run record -- ORDER_ID AMOUNT
    • REST (curl): bash record-action.sh ORDER_ID AMOUNT
  2. Publish:
    • Python: python publish_evidence.py OTHER_ORDER_ID AMOUNT
    • TypeScript: npm run evidence -- OTHER_ORDER_ID AMOUNT
    • REST (curl): bash publish-evidence.sh OTHER_ORDER_ID AMOUNT
  3. Publish (after every later scan):
    • Python: python publish_evidence.py --checkpoint-only
    • TypeScript: npm run evidence -- --checkpoint-only
    • REST (curl): bash publish-evidence.sh --checkpoint-only

Result: Nothing of the other order is attributed to this action. It stays pending and, once the checkpoints pass its settlement deadline, settles FAIL: no record for its own order.

Records published before the sources are attested

The publisher runs before an Owner or Admin attested the evidence sources.

  1. Record the action:
    • Python: python record_refund.py ORDER_ID AMOUNT
    • TypeScript: npm run record -- ORDER_ID AMOUNT
    • REST (curl): bash record-action.sh ORDER_ID AMOUNT
  2. Publish:
    • Python: python publish_evidence.py ORDER_ID AMOUNT
    • TypeScript: npm run evidence -- ORDER_ID AMOUNT
    • REST (curl): bash publish-evidence.sh ORDER_ID AMOUNT
  3. Attest the evidence sources (checklist step 3, or Connections).

Result: Pending: the records are received and not yet eligible. Attesting verifies the action again by itself, and it settles PASS.

The settlement window is the contract's (one hour here). "Once the checkpoints pass the deadline" means: your pipeline keeps running --checkpoint-only after its scans, and the first one after the deadline settles the verdict. Nobody asks for a verification.

Source bindings

A contract names roles. The refund contract has three: the payment, the order and the support case. Your workspace binds each role to one exact source id when you name the system behind it. A provider's display name is never a source id: the id is the one your workspace's contract reads.

With Stripe, Shopify and Zendesk:

Role Provider Source id Fact types the contract reads Identity link
payment stripe stripe refund, refund_failed payment_to_order: stripe to shopify
order shopify shopify order_cancelled, fulfillment_created, order_reopened none (the action's subject)
support zendesk zendesk status_change, reopen ticket_to_order: zendesk to shopify

With "My backend will send it" for the order and the support case:

Role Provider Source id Fact types the contract reads Identity link
payment stripe stripe refund, refund_failed payment_to_order: stripe to orders
order backend orders order_cancelled, fulfillment_created, order_reopened none (the action's subject)
support backend support status_change, reopen ticket_to_order: support to orders

In the second workspace a record sent as shopify or zendesk is refused: those sources do not exist there, and the evidence key is bound to orders, stripe, support. The support case is resolved with the status resolved, not solved.

One record holds the bindings, and everything else is generated from it:

  • the evidence key's scope (fact_sources);
  • the source of every fact and both ends of every identity link, in the programs and the per-source helpers;
  • the sources a checkpoint is sent for;
  • the rows of the attestation screen, the contract's coverage and the Connections page.

Read it with GET /v1/evidence/source-bindings (any member), or from the preflight with the evidence key (source_bindings, allowed_sources). record is null before a workflow is chosen.

{
  "record": {
    "contract": {
      "contract_id": "scop_refund_order",
      "version": 1,
      "subject_kind": "order"
    },
    "source_ids": [
      "stripe",
      "orders",
      "support"
    ],
    "evidence_key": {
      "scopes": [
        "facts:write"
      ],
      "fact_sources": [
        "orders",
        "stripe",
        "support"
      ],
      "evidence_class": "customer_backend"
    },
    "checkpoint_sources": [
      "orders",
      "stripe",
      "support"
    ],
    "links": [
      {
        "link_type": "payment_to_order",
        "left": {
          "source": "stripe",
          "subject_kind": "payment"
        },
        "right": {
          "source": "orders",
          "subject_kind": "order"
        }
      },
      {
        "link_type": "ticket_to_order",
        "left": {
          "source": "support",
          "subject_kind": "ticket"
        },
        "right": {
          "source": "orders",
          "subject_kind": "order"
        }
      }
    ],
    "bindings": [
      {
        "role": "payment",
        "provider": "stripe",
        "source_id": "stripe",
        "path": "facts_api",
        "pushed": true,
        "required": true,
        "subject_kind": "payment",
        "subject_match": "linked",
        "fact_types": [
          "refund",
          "refund_failed"
        ],
        "expected_effects": [
          {
            "code": "stripe.refund",
            "fact_type": "refund",
            "where": {}
          }
        ],
        "link": {
          "link_type": "payment_to_order",
          "source": "stripe",
          "subject_kind": "payment",
          "linked_source": "orders",
          "linked_subject_kind": "order"
        },
        "evidence_key_scope": true,
        "checkpoint": true
      }
    ]
  }
}

The same records() function in that workspace's Python program:

def records(order_id: str, amount: float, at: str, reported=None, record_id=None) -> tuple:
    """(identity links, facts) for one refunded order: every source's, or those of the sources in `reported`.
    `record_id` is the source's own id of the one record published (a second refund has its own)."""
    payment = f"pay-{order_id}"
    ticket = f"ticket-{order_id}"
    links = [
        {"subject_id": payment, "source": "stripe", "linked_subject_id": order_id, "linked_source": "orders", "link_type": "payment_to_order"},
        {"subject_id": ticket, "source": "support", "linked_subject_id": order_id, "linked_source": "orders", "link_type": "ticket_to_order"},
    ]
    facts = [
        {"source": "stripe", "subject_id": payment, "subject_kind": "payment", "fact_type": "refund", "occurred_at": at,
         "attributes": {"amount": amount, "currency": "usd", "status": "succeeded"}, "raw_ref": f"stripe:refund:{payment}"},
        {"source": "orders", "subject_id": order_id, "subject_kind": "order", "fact_type": "order_cancelled", "occurred_at": at,
         "attributes": {"reason": "customer"}, "raw_ref": f"orders:order_cancelled:{order_id}"},
        {"source": "support", "subject_id": ticket, "subject_kind": "ticket", "fact_type": "status_change", "occurred_at": at,
         "attributes": {"from": "open", "to": "resolved"}, "raw_ref": f"support:status_change:{ticket}"},
    ]
    if reported is not None:
        links = [ln for ln in links if ln["source"] in reported]
        facts = [f for f in facts if f["source"] in reported]
    if record_id is not None:
        for f in facts:
            f["raw_ref"] = f"{f['source']}:{f['fact_type']}:{record_id}"
    return links, facts


def options(args: list) -> tuple:
    """(reported sources or None, record id or None) from what follows ORDER_ID AMOUNT. ValueError on anything else."""
    reported, record_id = None, None
    while args:
        name, value = args[0], (args[1].strip() if len(args) > 1 else "")
        if not value or value.startswith("-"):
            raise ValueError(f"{name} needs a value")
        if name == "--reported" and reported is None:
            reported = [s.strip() for s in value.split(",") if s.strip()]
            unknown = [s for s in reported if s not in RECORD_SOURCES]
            if unknown or not reported:
                raise ValueError(f"unknown source: {', '.join(unknown) or value}. This workspace's sources with records: {', '.join(RECORD_SOURCES)}")
        elif name == "--record-id" and record_id is None:
            record_id = value
        else:
            raise ValueError(f"unknown option: {name}")
        args = args[2:]
    if record_id is not None and (reported is None or len(reported) != 1):
        raise ValueError("--record-id names one record: give its one source with --reported SOURCE")
    return reported, record_id

Key scopes

Key Scopes Bound to Can Cannot
Runtime recorder actions:record, actions:read nothing record an action, read its verdict publish evidence (403 insufficient_scope)
Evidence pipeline facts:write the binding record's pushed source ids publish links, records and checkpoints for those sources record an action (403), publish for any other source (403 source_not_allowed)

The product creates the evidence key with exactly the source ids of the binding record. A source a CommitLayer connector reads is not in the key's scope, and nothing can be published for it.

Attestation

A record from an evidence key counts toward a contract only once an Owner or Admin, signed in, has attested that key for that source (POST /v1/evidence/attestations, or the attestation dialog on the evidence step). No API key can attest. Before the attestation the batch is still accepted: its records are stored as agent-reported and the verdict stays pending. After it, the pending actions are re-verified with no new record needed.

Once a source is attested for a key, only that key may send its checkpoint or link its records. Another evidence key's batch for that source is rejected whole (checkpoint_not_permitted, link_not_permitted).

The atomic evidence batch: POST /v1/evidence/batches

Scope facts:write. Answers 201.

{
  "workspace_id": "ten_your_workspace",
  "contract_id": "scop_refund_order",
  "action_id": "refund-order-1001",
  "links": [{"subject_id": "pay-order-1001", "source": "stripe", "linked_subject_id": "order-1001", "linked_source": "shopify", "link_type": "payment_to_order"}],
  "facts": [{"source": "stripe", "subject_id": "pay-order-1001", "subject_kind": "payment", "fact_type": "refund", "occurred_at": "2026-11-18T10:42:09Z", "attributes": {"amount": 40.0, "currency": "usd", "status": "succeeded"}, "raw_ref": "stripe:refund:pay-order-1001"}],
  "observed_through": {"stripe": "2026-11-18T10:45:00Z", "shopify": "2026-11-18T10:45:00Z", "zendesk": "2026-11-18T10:45:00Z"}
}
Field
links Identity links: which payment and which ticket belong to the order. Same items as POST /v1/facts links.
facts Records. Same items as POST /v1/facts facts.
observed_through Source id to the time that source was scanned through: the checkpoint. A source with no record in the batch is still a valid checkpoint.
workspace_id Optional. Checked against the key's workspace.
contract_id Optional. When given, every record's source and type is checked against what that contract reads.
action_id Optional. The action the batch is evidence for; it must exist. Evidence is matched to actions by subject and identity link either way, so a pipeline that does not know the action leaves it out.

What the endpoint guarantees:

  1. The whole request is validated before anything is written.
  2. If any item is invalid or not permitted, the whole request is rejected. No identity link is written when a fact is unauthorized, no fact when a link is invalid, no checkpoint when the batch fails.
  3. Links, facts and checkpoints are committed in one transaction.
  4. Re-verification is queued by that same transaction, so only a committed batch queues one.
  5. The answer has one result per item.

A committed batch answers status: "committed", written: true, and:

Field
links[] index, accepted: true, status (created or exists), link_type, source, linked_source
facts[] The POST /v1/facts row, plus index, accepted: true, status (stored or duplicate), duplicate
checkpoints[] source, observed_through, accepted: true, status, current_observed_through, affected_action_ids
counts links, facts, facts_stored, facts_duplicate, checkpoints
affected_actions, reverify_scheduled, snapshot_versions, reverification_jobs The actions the batch changes, whether their re-verification is queued, and each one's current snapshot version

Sending the same batch again is safe: a record already stored comes back accepted with status: "duplicate", and a link that exists comes back exists.

Checkpoint statuses:

status
advanced The source's checkpoint moved to the declared time.
unchanged The source's checkpoint already stood at the declared time.
already_covered A later checkpoint already stands (current_observed_through), so the declared one adds nothing. Not a failure.

Preflight: POST /v1/evidence/batches/preflight

Scope facts:write. Takes the same body and writes nothing. It runs the checks workspace, contract, key_scopes, sources, fact_types, identity_links, checkpoint_permissions exactly as the batch endpoint does before it writes, and answers 200:

{"ok": true, "written": false, "workspace_id": "ten_your_workspace",
 "contract": {"contract_id": "scop_refund_order", "version": 1, "status": "active"},
 "key": {"id": "key_...", "scopes": ["facts:write"], "fact_sources": ["shopify", "stripe", "zendesk"]},
 "allowed_sources": ["shopify", "stripe", "zendesk"],
 "checks": [{"check": "workspace", "ok": true, "errors": 0}],
 "received": {"links": 2, "facts": 3, "checkpoints": 3},
 "source_bindings": [], "checkpoint_sources": ["shopify", "stripe", "zendesk"]}

An empty body checks the key, the workspace and the contract alone, and is how a program reads the source ids it may publish for. A batch that would be rejected answers with the same structured error as the batch endpoint, with the code preflight_failed. The batch endpoint validates again by itself: the preflight is a convenience, never a permission.

Source checkpoints

A checkpoint says "this source was scanned through this time". It is what lets a verdict settle: with a current checkpoint for every source, an expected effect that never happened settles FAIL at the deadline. Without one, CommitLayer can evaluate the records it has, but it cannot tell a missing record from a late one.

  • Send observed_through for every source you scanned, in every batch, including a source with nothing new.
  • After a scan that found nothing at all, send the checkpoints alone (--checkpoint-only in the programs).
  • A checkpoint only moves forward. An older one is already_covered, not an error.
  • Only the key a source is attested for may send its checkpoint.

The generated programs and the per-source helpers send a checkpoint with every batch.

Error messages

A rejected batch answers batch_rejected (the preflight: preflight_failed). The status is 403 when a permission is among the reasons, else 422. details holds everything a program has to print:

{
  "error": {
    "code": "batch_rejected",
    "message": "Nothing was written: 3 problems in this batch. This key may publish evidence for orders, stripe, support, not for shopify.",
    "details": {
      "written": false,
      "reason": "source_not_allowed",
      "summary": [
        "invalid source: shopify, zendesk",
        "allowed sources: orders, stripe, support",
        "failed link 0 (payment_to_order stripe to shopify): source_not_allowed",
        "failed checkpoint zendesk: source_not_allowed"
      ],
      "errors": [
        {
          "kind": "fact",
          "index": 1,
          "code": "source_not_allowed",
          "message": "This key may publish evidence for orders, stripe, support, not for shopify.",
          "source": "shopify",
          "allowed_sources": [
            "orders",
            "stripe",
            "support"
          ],
          "fact_type": "order_cancelled"
        },
        {
          "kind": "link",
          "index": 0,
          "code": "source_not_allowed",
          "message": "The link names shopify, which is not a source of this workspace. This key publishes for orders, stripe, support.",
          "link_type": "payment_to_order",
          "source": "stripe",
          "linked_source": "shopify",
          "allowed_sources": [
            "orders",
            "stripe",
            "support"
          ],
          "unknown_sources": [
            "shopify"
          ]
        },
        {
          "kind": "checkpoint",
          "index": null,
          "code": "source_not_allowed",
          "message": "This key may publish evidence for orders, stripe, support, not for zendesk.",
          "source": "zendesk",
          "allowed_sources": [
            "orders",
            "stripe",
            "support"
          ],
          "observed_through": "2026-11-18T10:45:00Z"
        }
      ],
      "checks": [
        {
          "check": "workspace",
          "ok": true,
          "errors": 0
        },
        {
          "check": "contract",
          "ok": true,
          "errors": 0
        },
        {
          "check": "key_scopes",
          "ok": true,
          "errors": 0
        },
        {
          "check": "sources",
          "ok": false,
          "errors": 1
        },
        {
          "check": "fact_types",
          "ok": true,
          "errors": 0
        },
        {
          "check": "identity_links",
          "ok": false,
          "errors": 1
        },
        {
          "check": "checkpoint_permissions",
          "ok": false,
          "errors": 1
        }
      ],
      "invalid_sources": [
        "shopify",
        "zendesk"
      ],
      "allowed_sources": [
        "orders",
        "stripe",
        "support"
      ],
      "invalid_fact_types": [],
      "failed_links": [
        {
          "index": 0,
          "code": "source_not_allowed",
          "link_type": "payment_to_order",
          "source": "stripe",
          "linked_source": "shopify",
          "message": "The link names shopify, which is not a source of this workspace. This key publishes for orders, stripe, support."
        }
      ],
      "failed_checkpoints": [
        {
          "code": "source_not_allowed",
          "source": "zendesk",
          "observed_through": "2026-11-18T10:45:00Z",
          "message": "This key may publish evidence for orders, stripe, support, not for zendesk."
        }
      ],
      "received": {
        "links": 2,
        "facts": 3,
        "checkpoints": 3
      },
      "accepted": {
        "links": 0,
        "facts": 0,
        "checkpoints": 0
      }
    }
  }
}

summary is the same error as lines to print: no line holds a double quote, a square bracket or a vertical bar, so a shell script can split the list without a JSON parser. The generated programs print it, then exit 1.

errors[].code About Status Meaning What to do
workspace_mismatch request 403 workspace_id is not the workspace the key belongs to. Use the environment file that was downloaded with this key.
unknown_contract request 422 contract_id names no contract of this workspace, or not the contract the action was recorded under. Send the contract id of the workspace's refund workflow (COMMITLAYER_CONTRACT_ID).
not_an_action_contract request 422 contract_id names an outcome contract, which reads no pushed evidence. Send an action contract's id.
contract_not_active request 422 The contract is a draft or was archived. Activate the contract, then send the batch again.
action_not_found request 422 action_id names no action recorded in this workspace. Record the action first, or leave action_id out: evidence is matched by subject and identity link.
source_not_allowed fact, link or checkpoint 403 The source is outside the evidence key's scope; for a link, one end names a source the workspace never configured. Use the workspace's configured source ids (allowed_sources), or bind the key to the source.
source_served_by_connector fact or checkpoint 422 A CommitLayer connector reads this source, so nothing can be published for it. Send nothing for that source.
source_not_in_contract fact 422 The contract named in the request reads no record from this source. Send records for the sources the contract reads, or leave contract_id out.
fact_type_not_read fact 422 The contract named in the request reads no record of this type from this source. Use one of allowed_fact_types.
invalid_fact fact 422 The record does not match the record schema: a field is missing, too long or not an identifier. Fix the field the message names.
invalid_timestamp fact 422 occurred_at is not a time CommitLayer reads. Send an RFC 3339 time in UTC, such as 2026-11-18T10:42:09Z.
future_timestamp fact 422 occurred_at is further in the future than the allowed clock skew. Send the time the record was made in its system.
invalid_link link 422 The link does not match the link schema, or joins a record to itself. Send two different ids and lowercase source names.
link_not_permitted link 403 Neither end of the link is a source this key publishes for, or one end is attested for another key. Send the link with the key that publishes one of its two sources.
invalid_checkpoint checkpoint 422 The checkpoint's source is not an identifier, or its time cannot be read or is in the future. Send observed_through as source to RFC 3339 time, no later than now.
checkpoint_not_permitted checkpoint 403 The source is attested for another evidence key: only that key may say how far it was scanned. Send the checkpoint with the attested key, or attest this key for the source.

Other answers of these two routes:

Status Code When
400 invalid_batch The batch holds no link, no fact and no checkpoint (the preflight accepts an empty body).
403 insufficient_scope The key has no facts:write scope: a recorder key.
403 sample_authorization_not_accepted The workspace sample's short-lived authorization was sent.
422 validation_error The body is not an object of the fields above (an unknown field, a list where an object belongs).

What the generated programs print and exit with:

Exit When
0 Every link, record and checkpoint sent is accepted in the answer.
1 The API refused the batch (the structured error is printed), the answer does not account for every item sent, the other process's key is in this process, or there is no record to publish.
2 The order or the amount is missing or not valid: the usage is printed and nothing is sent.

POST/v1/evidence/batch (deprecated)

The 0.9.56 route is kept, unchanged, for the client versions that call it (publish_batch in PyPI commitlayer 0.1.4, publishBatch in npm 0.1.5). It answers per item and is not atomic across a refused checkpoint: a caller has to read every accepted. Every answer carries Deprecation: true and Link: </v1/evidence/batches>; rel="successor-version". New code uses POST /v1/evidence/batches.

Python guide

Python 3.10 or later. Put the files in one folder with the two environment files beside them.

pip install -r requirements.txt
python record_refund.py ORDER_ID AMOUNT
python publish_evidence.py ORDER_ID AMOUNT

requirements.txt

commitlayer==0.1.5

record_refund.py

"""Record one refund action with the Runtime recorder key (CommitLayer quickstart, scop_refund_order v1).

Run:   pip install -r requirements.txt
       python record_refund.py ORDER_ID AMOUNT
Reads: commitlayer-recorder.env (COMMITLAYER_API_URL, COMMITLAYER_WORKSPACE_ID, COMMITLAYER_CONTRACT_ID, COMMITLAYER_RECORDER_KEY).
In your agent, call record_refund() just before the refund is issued, with the order the agent is refunding.
Both arguments are required: without them nothing is recorded.
"""

import os
import sys

import commitlayer
from commitlayer import CommitLayerError

USAGE = "Usage: python record_refund.py ORDER_ID AMOUNT   (the order being refunded and the refund's amount, e.g. 40.00)"

def load_env(path: str, forbidden: str) -> None:
    """Read KEY=value lines from the environment file next to this program (no dependency needed)."""
    here = os.path.join(os.path.dirname(os.path.abspath(__file__)), path)
    if os.path.exists(here):
        with open(here, encoding="utf-8") as f:
            for raw in f:
                line = raw.strip()
                if line and not line.startswith("#") and "=" in line:
                    k, v = line.split("=", 1)
                    os.environ.setdefault(k.strip(), v.strip())
    if os.environ.get(forbidden):
        sys.exit(f"{forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.")


def record_refund(order_id: str, amount: float) -> dict:
    rec = commitlayer.recorder()  # COMMITLAYER_RECORDER_KEY; the contract is COMMITLAYER_CONTRACT_ID
    return rec.record_action(
        subject_id=order_id,
        subject_kind="order",
        action_type="refund_order",
        workflow_id="refund_order",
        action_id=f"refund-{order_id}",  # idempotent: recording the same refund again changes nothing
        params={"amount": amount, "currency": "USD", "customer_id": f"customer-{order_id}"},
    )


def arguments(argv: list) -> tuple:
    """(order id, amount), or exit 2 with the usage: no order and no amount is ever made up."""
    try:
        order_id, amount = argv[0].strip(), float(argv[1])
        if len(argv) != 2 or not order_id or order_id.startswith("-") or amount <= 0:
            raise ValueError
    except (IndexError, ValueError):
        print(USAGE, file=sys.stderr)
        sys.exit(2)
    return order_id, amount


def main() -> int:
    order_id, amount = arguments(sys.argv[1:])
    load_env("commitlayer-recorder.env", forbidden="COMMITLAYER_EVIDENCE_KEY")
    try:
        out = record_refund(order_id, amount)
    except CommitLayerError as e:
        print(f"CommitLayer refused the action: {e.status} {e.code}: {e.message}", file=sys.stderr)
        return 1
    except ValueError as e:
        print(f"Setup problem: {e}", file=sys.stderr)
        return 1
    action = out["action"]
    print(f"action recorded: {action['id']} (action_id {action['action_id']}, contract {action['contract_id']})")
    print(f"verification: {out['verification']['status']}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

publish_evidence.py

"""Publish the refund's evidence as one atomic batch with the Evidence pipeline key (CommitLayer quickstart,
scop_refund_order v1).

Run:   pip install -r requirements.txt
       python publish_evidence.py ORDER_ID AMOUNT       identity links, records and a checkpoint for every source
       python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE[,SOURCE]
                                                        only the records those sources have for the order (a source
                                                        with no record yet is left out; its checkpoint is still sent)
       python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE --record-id ID
                                                        one more record of that source under the source's own id for
                                                        it: a second refund on the same order is a second record
       python publish_evidence.py --checkpoint-only     the checkpoints alone: "scanned, nothing new"
Reads: commitlayer-evidence.env (COMMITLAYER_API_URL, COMMITLAYER_WORKSPACE_ID, COMMITLAYER_CONTRACT_ID, COMMITLAYER_EVIDENCE_KEY).
Source ids are this workspace's own, the evidence key's scope: shopify, stripe, zendesk.
In your backend, build these records from what your systems report for the order, and send a checkpoint for every
source you scanned, even one with nothing new: that is how a missing refund settles FAIL on time.
The batch is checked first (the preflight writes nothing) and then stored whole or not at all. This program exits
nonzero when anything is refused, and when there is no record to publish.
"""

import os
import sys
from datetime import datetime, timezone

import commitlayer
from commitlayer import CommitLayerError

USAGE = (
    "Usage: python publish_evidence.py ORDER_ID AMOUNT     (the refunded order and the refund's amount)\n"
    "       python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE[,SOURCE]   (only the records those sources have: stripe, shopify, zendesk)\n"
    "       python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE --record-id ID   (one more record of that source, under its own id)\n"
    "       python publish_evidence.py --checkpoint-only   (checkpoints alone, no record)"
)
SOURCES = ["shopify", "stripe", "zendesk"]  # this workspace's configured source ids
RECORD_SOURCES = ["stripe", "shopify", "zendesk"]  # the sources this program has a record for

def load_env(path: str, forbidden: str) -> None:
    """Read KEY=value lines from the environment file next to this program (no dependency needed)."""
    here = os.path.join(os.path.dirname(os.path.abspath(__file__)), path)
    if os.path.exists(here):
        with open(here, encoding="utf-8") as f:
            for raw in f:
                line = raw.strip()
                if line and not line.startswith("#") and "=" in line:
                    k, v = line.split("=", 1)
                    os.environ.setdefault(k.strip(), v.strip())
    if os.environ.get(forbidden):
        sys.exit(f"{forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.")


def records(order_id: str, amount: float, at: str, reported=None, record_id=None) -> tuple:
    """(identity links, facts) for one refunded order: every source's, or those of the sources in `reported`.
    `record_id` is the source's own id of the one record published (a second refund has its own)."""
    payment = f"pay-{order_id}"
    ticket = f"ticket-{order_id}"
    links = [
        {"subject_id": payment, "source": "stripe", "linked_subject_id": order_id, "linked_source": "shopify", "link_type": "payment_to_order"},
        {"subject_id": ticket, "source": "zendesk", "linked_subject_id": order_id, "linked_source": "shopify", "link_type": "ticket_to_order"},
    ]
    facts = [
        {"source": "stripe", "subject_id": payment, "subject_kind": "payment", "fact_type": "refund", "occurred_at": at,
         "attributes": {"amount": amount, "currency": "usd", "status": "succeeded"}, "raw_ref": f"stripe:refund:{payment}"},
        {"source": "shopify", "subject_id": order_id, "subject_kind": "order", "fact_type": "order_cancelled", "occurred_at": at,
         "attributes": {"reason": "customer"}, "raw_ref": f"shopify:order_cancelled:{order_id}"},
        {"source": "zendesk", "subject_id": ticket, "subject_kind": "ticket", "fact_type": "status_change", "occurred_at": at,
         "attributes": {"from": "open", "to": "solved"}, "raw_ref": f"zendesk:status_change:{ticket}"},
    ]
    if reported is not None:
        links = [ln for ln in links if ln["source"] in reported]
        facts = [f for f in facts if f["source"] in reported]
    if record_id is not None:
        for f in facts:
            f["raw_ref"] = f"{f['source']}:{f['fact_type']}:{record_id}"
    return links, facts


def options(args: list) -> tuple:
    """(reported sources or None, record id or None) from what follows ORDER_ID AMOUNT. ValueError on anything else."""
    reported, record_id = None, None
    while args:
        name, value = args[0], (args[1].strip() if len(args) > 1 else "")
        if not value or value.startswith("-"):
            raise ValueError(f"{name} needs a value")
        if name == "--reported" and reported is None:
            reported = [s.strip() for s in value.split(",") if s.strip()]
            unknown = [s for s in reported if s not in RECORD_SOURCES]
            if unknown or not reported:
                raise ValueError(f"unknown source: {', '.join(unknown) or value}. This workspace's sources with records: {', '.join(RECORD_SOURCES)}")
        elif name == "--record-id" and record_id is None:
            record_id = value
        else:
            raise ValueError(f"unknown option: {name}")
        args = args[2:]
    if record_id is not None and (reported is None or len(reported) != 1):
        raise ValueError("--record-id names one record: give its one source with --reported SOURCE")
    return reported, record_id


def refused(e: CommitLayerError) -> int:
    """The server's structured error: nothing was written."""
    print(f"CommitLayer refused the evidence: {e.status} {e.code}: {e.message}", file=sys.stderr)
    details = e.details if isinstance(e.details, dict) else {}
    for line in details.get("summary") or []:
        print(f"  {line}", file=sys.stderr)
    if details.get("written") is False:
        print("  nothing was written: no link, no record, no checkpoint", file=sys.stderr)
    return 1


def main() -> int:
    args = sys.argv[1:]
    checkpoint_only = args == ["--checkpoint-only"]
    links, facts = [], []
    now = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
    if not checkpoint_only:
        try:
            order_id, amount = args[0].strip(), float(args[1])
            if not order_id or order_id.startswith("-") or amount <= 0:
                raise ValueError
            reported, record_id = options(args[2:])
        except (IndexError, ValueError) as e:
            if str(e) and not isinstance(e, IndexError) and "float" not in str(e):
                print(str(e), file=sys.stderr)
            print(USAGE, file=sys.stderr)
            return 2
        links, facts = records(order_id, amount, now, reported, record_id)
        if record_id is not None and len(facts) != 1:
            print("--record-id names one record, and that source has none or several for an order.", file=sys.stderr)
            print(USAGE, file=sys.stderr)
            return 2
        if not facts:
            print("No record to publish. To send checkpoints alone, run: python publish_evidence.py --checkpoint-only", file=sys.stderr)
            return 1
    load_env("commitlayer-evidence.env", forbidden="COMMITLAYER_RECORDER_KEY")
    batch = {
        "workspace_id": os.environ.get("COMMITLAYER_WORKSPACE_ID"),
        "contract_id": os.environ.get("COMMITLAYER_CONTRACT_ID"),
        "links": links,
        "facts": facts,
        "observed_through": {source: now for source in SOURCES},
    }
    try:
        ev = commitlayer.evidence()  # COMMITLAYER_EVIDENCE_KEY
        ev.preflight_batches(**batch)  # checks everything, writes nothing
        out = ev.publish_batches(**batch)  # one transaction: all of it or none of it
    except CommitLayerError as e:
        return refused(e)
    except ValueError as e:
        print(f"Setup problem: {e}", file=sys.stderr)
        return 1
    for ln in out.get("links", []):
        print(f"link {ln.get('link_type')} {ln.get('source')} -> {ln.get('linked_source')}: {ln.get('status')}")
    for f in out.get("facts", []):
        print(f"fact {f.get('fact_id')} {f.get('source_id')}/{f.get('fact_type')}: {f.get('status')}")
    for c in out.get("checkpoints", []):
        print(f"checkpoint {c.get('source')} through {c.get('observed_through')}: {c.get('status')}")
    print(f"affected actions: {', '.join(out.get('affected_actions') or []) or 'none'}; reverification scheduled: {out.get('reverify_scheduled')}")
    # Success is every item accounted for, never the status code alone.
    ok = (
        out.get("written") is True
        and len([x for x in out.get("links", []) if x.get("accepted")]) == len(links)
        and len([x for x in out.get("facts", []) if x.get("accepted")]) == len(facts)
        and {c.get("source") for c in out.get("checkpoints", []) if c.get("accepted")} == set(SOURCES)
    )
    if not ok:
        print("The answer does not account for every link, record and checkpoint sent. Treat the batch as failed.", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())

The program calls the two endpoints by name, preflight_batches(...) and publish_batches(...), which commitlayer has from 0.1.5. On an earlier version the same calls go through Client.request("POST", path, batch), with the batch in the API's own field names.

TypeScript guide

Node 20 or later. The project is complete: package.json, tsconfig.json, record-refund.ts and publish-evidence.ts, and no file is named that is not in it. tsconfig.json compiles every .ts file in the folder, so a per-source helper put beside the programs is built with them.

npm install
npm run record -- ORDER_ID AMOUNT
npm run evidence -- ORDER_ID AMOUNT

package.json

{
  "name": "commitlayer-refund-quickstart",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=20"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "record": "tsc -p tsconfig.json && node dist/record-refund.js",
    "evidence": "tsc -p tsconfig.json && node dist/publish-evidence.js"
  },
  "dependencies": {
    "commitlayer": "0.1.6"
  },
  "devDependencies": {
    "@types/node": "22.19.1",
    "typescript": "5.9.3"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "types": [
      "node"
    ],
    "outDir": "dist",
    "rootDir": "."
  },
  "include": [
    "*.ts"
  ]
}

record-refund.ts

// Record one refund action with the Runtime recorder key (CommitLayer quickstart, scop_refund_order v1).
// Run: npm install
//      npm run record -- ORDER_ID AMOUNT
// Reads commitlayer-recorder.env. In your agent, call recordRefund() just before the refund is issued.
// Both arguments are required: without them nothing is recorded.
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { CommitLayerError, recorder } from "commitlayer";

const USAGE = "Usage: npm run record -- ORDER_ID AMOUNT   (the order being refunded and the refund's amount, e.g. 40.00)";

function loadEnv(file: string, forbidden: string): void {
  // Read KEY=value lines from the environment file in the project folder (no dependency needed).
  const path = join(process.cwd(), file);
  if (existsSync(path)) {
    for (const raw of readFileSync(path, "utf8").split("\n")) {
      const line = raw.trim();
      if (!line || line.startsWith("#") || !line.includes("=")) continue;
      const i = line.indexOf("=");
      const k = line.slice(0, i).trim();
      if (process.env[k] === undefined) process.env[k] = line.slice(i + 1).trim();
    }
  }
  if (process.env[forbidden]) {
    console.error(`${forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.`);
    process.exit(1);
  }
}

export async function recordRefund(orderId: string, amount: number) {
  const rec = recorder(); // COMMITLAYER_RECORDER_KEY; the contract is COMMITLAYER_CONTRACT_ID
  return rec.recordAction(null, orderId, {
    subjectKind: "order",
    actionType: "refund_order",
    workflowId: "refund_order",
    actionId: `refund-${orderId}`, // idempotent: recording the same refund again changes nothing
    params: { amount, currency: "USD", customer_id: `customer-${orderId}` },
  });
}

async function main(): Promise<number> {
  const args = process.argv.slice(2);
  const orderId = (args[0] ?? "").trim();
  const amount = Number(args[1]);
  if (args.length !== 2 || !orderId || orderId.startsWith("-") || !Number.isFinite(amount) || amount <= 0) {
    console.error(USAGE); // no order and no amount is ever made up
    return 2;
  }
  loadEnv("commitlayer-recorder.env", "COMMITLAYER_EVIDENCE_KEY");
  try {
    const out = (await recordRefund(orderId, amount)) as { action: Record<string, string>; verification: Record<string, string> };
    console.log(`action recorded: ${out.action.id} (action_id ${out.action.action_id}, contract ${out.action.contract_id})`);
    console.log(`verification: ${out.verification.status}`);
    return 0;
  } catch (e) {
    if (e instanceof CommitLayerError) console.error(`CommitLayer refused the action: ${e.status} ${e.code}: ${e.message}`);
    else console.error(`Setup problem: ${(e as Error).message}`);
    return 1;
  }
}

main().then((code) => process.exit(code));

publish-evidence.ts

// Publish the refund's evidence as one atomic batch with the Evidence pipeline key (CommitLayer quickstart,
// scop_refund_order v1).
// Run: npm install
//      npm run evidence -- ORDER_ID AMOUNT       identity links, records and a checkpoint for every source
//      npm run evidence -- ORDER_ID AMOUNT --reported SOURCE[,SOURCE]
//                                                only the records those sources have for the order (a source with
//                                                no record yet is left out; its checkpoint is still sent)
//      npm run evidence -- ORDER_ID AMOUNT --reported SOURCE --record-id ID
//                                                one more record of that source under the source's own id for it:
//                                                a second refund on the same order is a second record
//      npm run evidence -- --checkpoint-only     the checkpoints alone: "scanned, nothing new"
// Reads commitlayer-evidence.env.
// Source ids are this workspace's own, the evidence key's scope: shopify, stripe, zendesk.
// The batch is checked first (the preflight writes nothing) and then stored whole or not at all. This program exits
// nonzero when anything is refused, and when there is no record to publish.
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { CommitLayerError, evidence } from "commitlayer";

const USAGE =
  "Usage: npm run evidence -- ORDER_ID AMOUNT     (the refunded order and the refund's amount)\n" +
  "       npm run evidence -- ORDER_ID AMOUNT --reported SOURCE[,SOURCE]   (only the records those sources have: stripe, shopify, zendesk)\n" +
  "       npm run evidence -- ORDER_ID AMOUNT --reported SOURCE --record-id ID   (one more record of that source, under its own id)\n" +
  "       npm run evidence -- --checkpoint-only   (checkpoints alone, no record)";
const SOURCES: string[] = ["shopify", "stripe", "zendesk"]; // this workspace's configured source ids
const RECORD_SOURCES: string[] = ["stripe", "shopify", "zendesk"]; // the sources this program has a record for
type Item = Record<string, unknown>;

function loadEnv(file: string, forbidden: string): void {
  // Read KEY=value lines from the environment file in the project folder (no dependency needed).
  const path = join(process.cwd(), file);
  if (existsSync(path)) {
    for (const raw of readFileSync(path, "utf8").split("\n")) {
      const line = raw.trim();
      if (!line || line.startsWith("#") || !line.includes("=")) continue;
      const i = line.indexOf("=");
      const k = line.slice(0, i).trim();
      if (process.env[k] === undefined) process.env[k] = line.slice(i + 1).trim();
    }
  }
  if (process.env[forbidden]) {
    console.error(`${forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.`);
    process.exit(1);
  }
}

/** The identity links and the facts for one refunded order: every source's, or those of the sources in `reported`.
 * `recordId` is the source's own id of the one record published (a second refund has its own). */
function records(orderId: string, amount: number, at: string, reported: string[] | null = null, recordId: string | null = null): { links: Item[]; facts: Item[] } {
  const payment = `pay-${orderId}`;
  const ticket = `ticket-${orderId}`;
  let links: Item[] = [
    { subject_id: payment, source: "stripe", linked_subject_id: orderId, linked_source: "shopify", link_type: "payment_to_order" },
    { subject_id: ticket, source: "zendesk", linked_subject_id: orderId, linked_source: "shopify", link_type: "ticket_to_order" },
  ];
  let facts: Item[] = [
    { source: "stripe", subject_id: payment, subject_kind: "payment", fact_type: "refund", occurred_at: at, attributes: { amount, "currency": "usd", "status": "succeeded" }, raw_ref: `stripe:refund:${payment}` },
    { source: "shopify", subject_id: orderId, subject_kind: "order", fact_type: "order_cancelled", occurred_at: at, attributes: { "reason": "customer" }, raw_ref: `shopify:order_cancelled:${orderId}` },
    { source: "zendesk", subject_id: ticket, subject_kind: "ticket", fact_type: "status_change", occurred_at: at, attributes: { "from": "open", "to": "solved" }, raw_ref: `zendesk:status_change:${ticket}` },
  ];
  if (reported !== null) {
    links = links.filter((ln) => reported.includes(String(ln.source)));
    facts = facts.filter((f) => reported.includes(String(f.source)));
  }
  if (recordId !== null) for (const f of facts) f.raw_ref = `${f.source}:${f.fact_type}:${recordId}`;
  return { links, facts };
}

/** The reported sources and the record id from what follows ORDER_ID AMOUNT. Throws on anything else. */
function options(args: string[]): { reported: string[] | null; recordId: string | null } {
  let reported: string[] | null = null;
  let recordId: string | null = null;
  for (let i = 0; i < args.length; i += 2) {
    const name = args[i];
    const value = (args[i + 1] ?? "").trim();
    if (!value || value.startsWith("-")) throw new Error(`${name} needs a value`);
    if (name === "--reported" && reported === null) {
      reported = value.split(",").map((s) => s.trim()).filter(Boolean);
      const unknown = reported.filter((s) => !RECORD_SOURCES.includes(s));
      if (unknown.length || !reported.length) throw new Error(`unknown source: ${unknown.join(", ") || value}. This workspace's sources with records: ${RECORD_SOURCES.join(", ")}`);
    } else if (name === "--record-id" && recordId === null) {
      recordId = value;
    } else {
      throw new Error(`unknown option: ${name}`);
    }
  }
  if (recordId !== null && (reported === null || reported.length !== 1)) throw new Error("--record-id names one record: give its one source with --reported SOURCE");
  return { reported, recordId };
}

/** The server's structured error: nothing was written. */
function refused(e: CommitLayerError): number {
  console.error(`CommitLayer refused the evidence: ${e.status} ${e.code}: ${e.message}`);
  const details = (e.details ?? {}) as { summary?: string[]; written?: boolean };
  for (const line of details.summary ?? []) console.error(`  ${line}`);
  if (details.written === false) console.error("  nothing was written: no link, no record, no checkpoint");
  return 1;
}

async function main(): Promise<number> {
  const args = process.argv.slice(2);
  const checkpointOnly = args.length === 1 && args[0] === "--checkpoint-only";
  const now = new Date(Math.floor(Date.now() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
  let links: Item[] = [];
  let facts: Item[] = [];
  if (!checkpointOnly) {
    const orderId = (args[0] ?? "").trim();
    const amount = Number(args[1]);
    if (args.length < 2 || !orderId || orderId.startsWith("-") || !Number.isFinite(amount) || amount <= 0) {
      console.error(USAGE);
      return 2;
    }
    let chosen: { reported: string[] | null; recordId: string | null };
    try {
      chosen = options(args.slice(2));
    } catch (e) {
      console.error((e as Error).message);
      console.error(USAGE);
      return 2;
    }
    ({ links, facts } = records(orderId, amount, now, chosen.reported, chosen.recordId));
    if (chosen.recordId !== null && facts.length !== 1) {
      console.error("--record-id names one record, and that source has none or several for an order.");
      console.error(USAGE);
      return 2;
    }
    if (facts.length === 0) {
      console.error("No record to publish. To send checkpoints alone, run: npm run evidence -- --checkpoint-only");
      return 1;
    }
  }
  loadEnv("commitlayer-evidence.env", "COMMITLAYER_RECORDER_KEY");
  const batch = {
    workspaceId: process.env.COMMITLAYER_WORKSPACE_ID,
    contractId: process.env.COMMITLAYER_CONTRACT_ID,
    links,
    facts,
    observedThrough: Object.fromEntries(SOURCES.map((source) => [source, now])),
  };
  type Row = { accepted?: boolean; status?: string; source?: string; [k: string]: unknown };
  let out: { written?: boolean; links?: Row[]; facts?: Row[]; checkpoints?: Row[]; affected_actions?: string[]; reverify_scheduled?: boolean };
  try {
    const ev = evidence(); // COMMITLAYER_EVIDENCE_KEY
    await ev.preflightBatches(batch); // checks everything, writes nothing
    out = (await ev.publishBatches(batch)) as typeof out; // one transaction: all of it or none of it
  } catch (e) {
    if (e instanceof CommitLayerError) return refused(e);
    console.error(`Setup problem: ${(e as Error).message}`);
    return 1;
  }
  for (const ln of out.links ?? []) console.log(`link ${ln.link_type} ${ln.source} -> ${ln.linked_source}: ${ln.status}`);
  for (const f of out.facts ?? []) console.log(`fact ${f.fact_id} ${f.source_id}/${f.fact_type}: ${f.status}`);
  for (const c of out.checkpoints ?? []) console.log(`checkpoint ${c.source} through ${c.observed_through}: ${c.status}`);
  console.log(`affected actions: ${(out.affected_actions ?? []).join(", ") || "none"}; reverification scheduled: ${out.reverify_scheduled}`);
  // Success is every item accounted for, never the status code alone.
  const accepted = new Set((out.checkpoints ?? []).filter((c) => c.accepted).map((c) => c.source));
  const ok =
    out.written === true &&
    (out.links ?? []).filter((x) => x.accepted).length === links.length &&
    (out.facts ?? []).filter((x) => x.accepted).length === facts.length &&
    accepted.size === SOURCES.length &&
    SOURCES.every((s) => accepted.has(s));
  if (!ok) {
    console.error("The answer does not account for every link, record and checkpoint sent. Treat the batch as failed.");
    return 1;
  }
  return 0;
}

main().then((code) => process.exit(code));

The program calls the two endpoints by name, preflightBatches(...) and publishBatches(...), which commitlayer has from 0.1.6. On an earlier version the same calls go through Client.request("POST", path, batch), with the batch in the API's own field names.

REST guide

Needs bash and curl.

bash record-action.sh ORDER_ID AMOUNT
bash publish-evidence.sh ORDER_ID AMOUNT

record-action.sh

#!/usr/bin/env bash
# Record one refund action with the Runtime recorder key (CommitLayer quickstart, scop_refund_order v1).
# Run: bash record-action.sh ORDER_ID AMOUNT   (reads commitlayer-recorder.env; needs curl)
# Both arguments are required: without them nothing is recorded.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
usage() {
  echo "Usage: bash record-action.sh ORDER_ID AMOUNT   (the order being refunded and the refund's amount, e.g. 40.00)" >&2
  exit 2
}
MODE="records"
if [ "$MODE" = "records" ]; then
  [ "$#" -ge 2 ] || usage
  ORDER_ID="$1"
  AMOUNT="$2"
  case "$ORDER_ID" in ''|-*|*[!A-Za-z0-9_.:-]*) usage ;; esac
  case "$AMOUNT" in ''|*[!0-9.]*|*.*.*) usage ;; esac
  shift 2
  [ "$#" -eq 0 ] || usage
fi
if [ -f "$HERE/commitlayer-recorder.env" ]; then
  set -a
  # shellcheck disable=SC1090
  . "$HERE/commitlayer-recorder.env"
  set +a
fi
for name in COMMITLAYER_API_URL COMMITLAYER_WORKSPACE_ID COMMITLAYER_CONTRACT_ID COMMITLAYER_RECORDER_KEY; do
  if [ -z "${!name:-}" ]; then echo "Missing $name: put commitlayer-recorder.env next to this script." >&2; exit 1; fi
done
if [ -n "${COMMITLAYER_EVIDENCE_KEY:-}" ]; then
  echo "COMMITLAYER_EVIDENCE_KEY is set in this process. Keep the recorder and evidence keys in separate processes." >&2
  exit 1
fi
NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

field() {  # field NAME JSON: the first string value of that name
  printf '%s' "$2" | grep -o "\"$1\": *\"[^\"]*\"" | head -n 1 | sed 's/^[^:]*: *"//; s/"$//'
}

post() {  # post PATH BODY: prints the response body; a refusal prints the server's structured error and exits 1
  local out status
  out="$(curl -sS -w '\n%{http_code}' -X POST "${COMMITLAYER_API_URL%/}$1" \
    -H "X-API-Key: ${COMMITLAYER_RECORDER_KEY}" -H "Content-Type: application/json" --data "$2")"
  status="${out##*$'\n'}"
  out="${out%$'\n'*}"
  if [ "$status" -ge 400 ]; then
    echo "CommitLayer refused $1: $status $(field code "$out"): $(field message "$out")" >&2
    printf '%s' "$out" | grep -o '"summary": *\[[^]]*\]' | sed 's/^[^[]*\[//; s/\]$//; s/^"//; s/"$//; s/", *"/|/g' \
      | tr '|' '\n' | sed '/^$/d; s/^/  /' >&2 || true
    if printf '%s' "$out" | grep -q '"written": *false'; then
      echo "  nothing was written: no link, no record, no checkpoint" >&2
    fi
    exit 1
  fi
  printf '%s\n' "$out"
}

BODY="$(cat <<JSON
{"action_id": "refund-$ORDER_ID", "contract_id": "$COMMITLAYER_CONTRACT_ID", "action_type": "refund_order",
 "workflow_id": "refund_order", "subject_id": "$ORDER_ID", "subject_kind": "order", "requested_at": "$NOW",
 "params": {"amount": $AMOUNT, "currency": "USD", "customer_id": "customer-$ORDER_ID"}}
JSON
)"
OUT="$(post /v1/actions "$BODY")"
ACTION="$(printf '%s' "$OUT" | sed -n 's/.*"action": *{"id": *"\([^"]*\)".*/\1/p')"
echo "action recorded: $ACTION (action_id refund-$ORDER_ID, contract $COMMITLAYER_CONTRACT_ID)"

publish-evidence.sh

#!/usr/bin/env bash
# Publish the refund's evidence as one atomic batch with the Evidence pipeline key (CommitLayer quickstart, scop_refund_order v1).
# Run: bash publish-evidence.sh ORDER_ID AMOUNT       identity links, records and a checkpoint for every source
#      bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE[,SOURCE]
#                                                only the records those sources have for the order (a source with
#                                                no record yet is left out; its checkpoint is still sent)
#      bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE --record-id ID
#                                                one more record of that source under the source's own id for it:
#                                                a second refund on the same order is a second record
#      bash publish-evidence.sh --checkpoint-only     the checkpoints alone: "scanned, nothing new"
# Reads commitlayer-evidence.env; needs curl.
# Source ids are this workspace's own, the evidence key's scope: shopify, stripe, zendesk.
# The batch is checked first (the preflight writes nothing) and then stored whole or not at all. This script exits
# nonzero when anything is refused, and when there is no record to publish.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
usage() {
  echo "Usage: bash publish-evidence.sh ORDER_ID AMOUNT   (the refunded order and the refund's amount)" >&2
  echo "       bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE[,SOURCE]   (only the records those sources have: ${RECORD_SOURCES// /, })" >&2
  echo "       bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE --record-id ID   (one more record of that source, under its own id)" >&2
  echo "       bash publish-evidence.sh --checkpoint-only   (checkpoints alone, no record)" >&2
  exit 2
}
RECORD_SOURCES="stripe shopify zendesk"  # the sources this script has a record for
REPORTED=""
RECORD_ID=""
MODE="records"
if [ "$#" -eq 1 ] && [ "$1" = "--checkpoint-only" ]; then MODE="checkpoints"; fi
if [ "$MODE" = "records" ]; then
  [ "$#" -ge 2 ] || usage
  ORDER_ID="$1"
  AMOUNT="$2"
  case "$ORDER_ID" in ''|-*|*[!A-Za-z0-9_.:-]*) usage ;; esac
  case "$AMOUNT" in ''|*[!0-9.]*|*.*.*) usage ;; esac
  shift 2
  while [ "$#" -gt 0 ]; do
    [ "$#" -ge 2 ] || { echo "$1 needs a value" >&2; usage; }
    case "$2" in ''|-*|*[!A-Za-z0-9_.:,-]*) echo "$1 needs a value" >&2; usage ;; esac
    case "$1" in
      --reported) [ -z "$REPORTED" ] || usage; REPORTED="$2" ;;
      --record-id) [ -z "$RECORD_ID" ] || usage; RECORD_ID="$2" ;;
      *) echo "unknown option: $1" >&2; usage ;;
    esac
    shift 2
  done
  if [ -n "$REPORTED" ]; then
    for s in ${REPORTED//,/ }; do
      case " $RECORD_SOURCES " in
        *" $s "*) ;;
        *) echo "unknown source: $s. This workspace's sources with records: ${RECORD_SOURCES// /, }" >&2; usage ;;
      esac
    done
  fi
  if [ -n "$RECORD_ID" ]; then
    case "$REPORTED" in
      ''|*,*) echo "--record-id names one record: give its one source with --reported SOURCE" >&2; usage ;;
    esac
    case "$RECORD_ID" in *,*) usage ;; esac
  fi
fi
if [ -f "$HERE/commitlayer-evidence.env" ]; then
  set -a
  # shellcheck disable=SC1090
  . "$HERE/commitlayer-evidence.env"
  set +a
fi
for name in COMMITLAYER_API_URL COMMITLAYER_WORKSPACE_ID COMMITLAYER_CONTRACT_ID COMMITLAYER_EVIDENCE_KEY; do
  if [ -z "${!name:-}" ]; then echo "Missing $name: put commitlayer-evidence.env next to this script." >&2; exit 1; fi
done
if [ -n "${COMMITLAYER_RECORDER_KEY:-}" ]; then
  echo "COMMITLAYER_RECORDER_KEY is set in this process. Keep the recorder and evidence keys in separate processes." >&2
  exit 1
fi
NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

field() {  # field NAME JSON: the first string value of that name
  printf '%s' "$2" | grep -o "\"$1\": *\"[^\"]*\"" | head -n 1 | sed 's/^[^:]*: *"//; s/"$//'
}

post() {  # post PATH BODY: prints the response body; a refusal prints the server's structured error and exits 1
  local out status
  out="$(curl -sS -w '\n%{http_code}' -X POST "${COMMITLAYER_API_URL%/}$1" \
    -H "X-API-Key: ${COMMITLAYER_EVIDENCE_KEY}" -H "Content-Type: application/json" --data "$2")"
  status="${out##*$'\n'}"
  out="${out%$'\n'*}"
  if [ "$status" -ge 400 ]; then
    echo "CommitLayer refused $1: $status $(field code "$out"): $(field message "$out")" >&2
    printf '%s' "$out" | grep -o '"summary": *\[[^]]*\]' | sed 's/^[^[]*\[//; s/\]$//; s/^"//; s/"$//; s/", *"/|/g' \
      | tr '|' '\n' | sed '/^$/d; s/^/  /' >&2 || true
    if printf '%s' "$out" | grep -q '"written": *false'; then
      echo "  nothing was written: no link, no record, no checkpoint" >&2
    fi
    exit 1
  fi
  printf '%s\n' "$out"
}

# This workspace's configured source ids: a checkpoint is sent for each.
THROUGH='"shopify": "@NOW@", "stripe": "@NOW@", "zendesk": "@NOW@"'
THROUGH="${THROUGH//@NOW@/$NOW}"
LINKS=""
FACTS=""
N_LINKS=0
N_FACTS=0
reported() {  # reported SOURCE: whether that source's records are published (all of them unless --reported names some)
  [ -z "$REPORTED" ] && return 0
  case ",$REPORTED," in *",$1,"*) return 0 ;; esac
  return 1
}
link() {  # link JSON: one more identity link in the batch
  LINKS="${LINKS:+$LINKS,
}$1"
  N_LINKS=$((N_LINKS + 1))
}
fact() {  # fact JSON: one more record in the batch
  FACTS="${FACTS:+$FACTS,
}$1"
  N_FACTS=$((N_FACTS + 1))
}
if [ "$MODE" = "records" ]; then
  PAYMENT="pay-$ORDER_ID"
  TICKET="ticket-$ORDER_ID"
  if reported "stripe"; then
    link "$(cat <<JSON
 {"subject_id": "$PAYMENT", "source": "stripe", "linked_subject_id": "$ORDER_ID", "linked_source": "shopify", "link_type": "payment_to_order"}
JSON
)"
  fi
  if reported "zendesk"; then
    link "$(cat <<JSON
 {"subject_id": "$TICKET", "source": "zendesk", "linked_subject_id": "$ORDER_ID", "linked_source": "shopify", "link_type": "ticket_to_order"}
JSON
)"
  fi
  if reported "stripe"; then
    fact "$(cat <<JSON
 {"source": "stripe", "subject_id": "$PAYMENT", "subject_kind": "payment", "fact_type": "refund", "occurred_at": "$NOW",
  "attributes": {"amount": $AMOUNT, "currency": "usd", "status": "succeeded"}, "raw_ref": "stripe:refund:${RECORD_ID:-$PAYMENT}"}
JSON
)"
  fi
  if reported "shopify"; then
    fact "$(cat <<JSON
 {"source": "shopify", "subject_id": "$ORDER_ID", "subject_kind": "order", "fact_type": "order_cancelled", "occurred_at": "$NOW",
  "attributes": {"reason": "customer"}, "raw_ref": "shopify:order_cancelled:${RECORD_ID:-$ORDER_ID}"}
JSON
)"
  fi
  if reported "zendesk"; then
    fact "$(cat <<JSON
 {"source": "zendesk", "subject_id": "$TICKET", "subject_kind": "ticket", "fact_type": "status_change", "occurred_at": "$NOW",
  "attributes": {"from": "open", "to": "solved"}, "raw_ref": "zendesk:status_change:${RECORD_ID:-$TICKET}"}
JSON
)"
  fi
  if [ -n "$RECORD_ID" ] && [ "$N_FACTS" -ne 1 ]; then
    echo "--record-id names one record, and that source has none or several for an order." >&2
    usage
  fi
  if [ "$N_FACTS" -eq 0 ]; then
    echo "No record to publish. To send checkpoints alone, run: bash publish-evidence.sh --checkpoint-only" >&2
    exit 1
  fi
fi
BATCH="$(cat <<JSON
{"workspace_id": "$COMMITLAYER_WORKSPACE_ID", "contract_id": "$COMMITLAYER_CONTRACT_ID",
 "links": [$LINKS],
 "facts": [$FACTS],
 "observed_through": {$THROUGH}}
JSON
)"
post /v1/evidence/batches/preflight "$BATCH" >/dev/null   # checks everything, writes nothing
OUT="$(post /v1/evidence/batches "$BATCH")"        # one transaction: all of it or none of it
count() {  # count NAME: that number in the answer's "counts"
  printf '%s' "$OUT" | sed -n "s/.*\"counts\": *{[^}]*\"$1\": *\([0-9]*\).*/\1/p"
}
echo "links accepted: $(count links) of $N_LINKS"
echo "facts accepted: $(count facts) of $N_FACTS (stored $(count facts_stored), already stored $(count facts_duplicate))"
echo "checkpoints accepted: $(count checkpoints) of 3 (shopify, stripe, zendesk)"
echo "reverification scheduled: $(printf '%s' "$OUT" | sed -n 's/.*"reverify_scheduled": *\(true\|false\).*/\1/p')"
# Success is every item accounted for, never the status code alone.
if ! printf '%s' "$OUT" | grep -q '"written": *true' || [ "$(count links)" != "$N_LINKS" ] \
  || [ "$(count facts)" != "$N_FACTS" ] || [ "$(count checkpoints)" != "3" ]; then
  echo "The answer does not account for every link, record and checkpoint sent. Treat the batch as failed." >&2
  exit 1
fi

Per-source helpers

The evidence step also shows one helper per source your backend sends, in each language, for a backend that publishes one system at a time (GET /v1/onboarding/evidence-snippet). Each call is one atomic batch: the record, the identity link to your configured order source and the source's checkpoint. Each helper also sends the checkpoint alone. In the REST helper every ${NAME} is a value your system holds for the record; export them and run the line for the record you send. A value that is not set stops the script before it sends anything.

send_stripe_records.sh

#!/usr/bin/env bash
# Sends the stripe records the contract scop_refund_order (version 1) reads, each as one atomic batch
# (POST /v1/evidence/batches): the record, the identity link it needs and the stripe checkpoint are stored
# together or not at all. A refused batch writes nothing.
# 1. Send each record from the backend of the system that owns it, never from the agent being checked.
# 2. Send it when the record is created or changes in that system, with the time it happened there.
# 3. Keep raw_ref the same on every retry of one record, so a retry is stored once.
# 4. Send the checkpoint after every scan of the source, also when it found nothing new: it is how a missing record settles on time.
# Run: bash send_stripe_records.sh refund
#      bash send_stripe_records.sh refund_failed
#      bash send_stripe_records.sh checkpoint
# Every value written as a dollar sign and a name in braces is one your own system holds for the record.
# Export them, then run the call for the record you send. A value that is not set stops the script before it sends.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
if [ -f "$HERE/commitlayer-evidence.env" ]; then
  set -a
  # shellcheck disable=SC1090
  . "$HERE/commitlayer-evidence.env"
  set +a
fi
if [ -z "${COMMITLAYER_EVIDENCE_KEY:-}" ]; then echo "Missing COMMITLAYER_EVIDENCE_KEY: put commitlayer-evidence.env next to this script." >&2; exit 1; fi
API="${COMMITLAYER_API_URL:-https://api.commitlayer.ai}"
# The time through which every stripe record has been sent. Now, unless you say otherwise.
OBSERVED_THROUGH="${OBSERVED_THROUGH:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"

send() {  # send: the batch on stdin. Prints the answer; a refusal prints the server's error and exits 1.
  local out status
  out="$(curl -sS -w '\n%{http_code}' -X POST "${API%/}/v1/evidence/batches" \
    -H "X-API-Key: ${COMMITLAYER_EVIDENCE_KEY}" \
    -H "Content-Type: application/json" \
    --data-binary @-)"
  status="${out##*$'\n'}"
  out="${out%$'\n'*}"
  if [ "$status" -ge 400 ]; then echo "CommitLayer refused the batch ($status), nothing was written: $out" >&2; exit 1; fi
  printf '%s\n' "$out"
}

case "${1:-}" in
  refund)
    # A refund record: send it when your system records one.
    send <<JSON
{
  "contract_id": "scop_refund_order",
  "links": [
    {
      "subject_id": "${PAYMENT_ID}",
      "source": "stripe",
      "linked_subject_id": "${ORDER_ID}",
      "linked_source": "shopify",
      "link_type": "payment_to_order"
    }
  ],
  "facts": [
    {
      "source": "stripe",
      "fact_type": "refund",
      "subject_id": "${PAYMENT_ID}",
      "subject_kind": "payment",
      "occurred_at": "${OCCURRED_AT}",
      "raw_ref": "${RECORD_ID}",
      "attributes": {
        "amount": ${AMOUNT}
      }
    }
  ],
  "observed_through": {"stripe": "${OBSERVED_THROUGH}"}
}
JSON
    ;;
  refund_failed)
    # A refund_failed record: send it when your system records one.
    send <<JSON
{
  "contract_id": "scop_refund_order",
  "links": [
    {
      "subject_id": "${PAYMENT_ID}",
      "source": "stripe",
      "linked_subject_id": "${ORDER_ID}",
      "linked_source": "shopify",
      "link_type": "payment_to_order"
    }
  ],
  "facts": [
    {
      "source": "stripe",
      "fact_type": "refund_failed",
      "subject_id": "${PAYMENT_ID}",
      "subject_kind": "payment",
      "occurred_at": "${OCCURRED_AT}",
      "raw_ref": "${RECORD_ID}",
      "attributes": {}
    }
  ],
  "observed_through": {"stripe": "${OBSERVED_THROUGH}"}
}
JSON
    ;;
  checkpoint)
    # The checkpoint alone: send it after every scan of stripe, also when it found nothing new.
    send <<JSON
{
  "contract_id": "scop_refund_order",
  "observed_through": {"stripe": "${OBSERVED_THROUGH}"}
}
JSON
    ;;
  *)
    echo "Usage: bash send_stripe_records.sh refund" >&2
    echo "       bash send_stripe_records.sh refund_failed" >&2
    echo "       bash send_stripe_records.sh checkpoint" >&2
    exit 2
    ;;
esac