Guide

Submissions and records

How a batch becomes a submission, how Fence decides each record, and how to know a batch is done.

You never write to an asset directly. You send a batch, Fence stores it as a submission and checks its shape, then decides each of its records on its own.

From batch to records

You send a batch. Fence stores the original bytes before anything else: that is the submission.
Fence checks the batch's shape against its standard format and answers at once: accepted or refused.
A few seconds later, Fence has decided each record of an accepted batch against your program's rules: new, changed, unchanged or refused.

The submission

The answer to a send is always 201, because the call made a submission. Its status says what happened:

Status	Meaning
`accepted`	The batch has the right shape. `record_count` says how many records it holds.
`refused`	It does not. `reasons` lists the first 1,000 problems, each with a `code`, the `row` and the `field`. Nothing in it was applied.

Every call makes a new submission, even when you send the same body again. A batch holds at most 50,000 records and 10 MiB.

There are four kinds of batch, each with its own route:

Route	Required in each record
`POST …/submissions/asset-groups`	`asset_group_kind`, `asset_group_id`
`POST …/submissions/assets`	`asset_id`, `currency`
`POST …/submissions/payment-plans`	`asset_id`, `currency`, and `terms` or `lines`
`POST …/submissions/payments`	`payment_id`, `type`, `gross_amount`, `currency`, `paid_on`

The body is always {"records": [ … ]}. The API reference has every field.

Records

Each record gets a result:

Result	Meaning
`received`	Not decided yet. Read again shortly.
`new`	It made something Fence did not hold.
`changed`	It changed what Fence held. The earlier version is kept.
`unchanged`	Fence already held exactly this.
`refused`	It broke a rule. `reasons` gives codes and field names, never the values you sent.

A refused record changes nothing, and the rest of the batch still goes through. An accepted payment record may also carry warnings.

Know when a batch is done

Read the submission's records:

curl -s "$FENCE_API/v1/api/asset-programs/$PROGRAM_ID/submissions/$SUBMISSION_ID/records" \
  -H "Authorization: Bearer $TOKEN"

The answer gives total, the batch's record count, and counts, the records per result. The batch is decided when counts.received is 0. Add ?result=refused to list only the refused records.

Every record ever sent for an asset is also kept on the asset, refused ones included: GET …/assets/{id}/records and GET …/assets/{id}/payment-plan/records.