Docs / API and agents
Supplier terms API
Write, preview, publish and retire the terms of sale and guaranty wording a supplier sends with its credit agreements.
A supplier writes the wording its customers sign: the terms of sale that go with a credit agreement and the guaranty form that goes with a personal guaranty. Each is a numbered version of Markdown text with merge fields. The supplier publishes a version once its counsel approved it, and every signature request records which version it carried. The editor is in the web app under Settings, Signing terms (how to use it). Sending a request is described in Signatures.
Who can use it#
Everything except the in-use read needs signatures.templates.manage (by default the Owner, Administrator, Account admin and Credit manager). GET /v1/terms/in-use is also open to signatures.send, so whoever sends an agreement can see which wording will go out. Another supplier's version id is a 404, never a 403.
Endpoints#
| Method and path | What it does |
|---|---|
GET /v1/terms | Every version of the supplier, newest first within each kind, without the text, plus starters: the platform template as editable Markdown for each kind. |
GET /v1/terms/in-use | For each kind, whether the next request carries the supplier's current version (source: "supplier", with version and title) or the platform template (source: "platform"). |
GET /v1/terms/:id | One version with its body, returned exactly as saved. |
POST /v1/terms | Creates a draft: { kind, title, body }. The version number is the next one for that kind. |
PUT /v1/terms/:id | Edits a draft. The kind cannot change. |
DELETE /v1/terms/:id | Deletes a draft. |
POST /v1/terms/:id/publish | Publishes a draft: body { "counselConfirmed": true }. |
GET /v1/terms/:id/preview | The whole package as a PDF (schedule page, then the terms) with obvious sample values. Any status. |
kind is terms_of_sale or guaranty_form. A credit agreement carries the terms of sale; a personal guaranty carries the guaranty form.
The text#
- Markdown with headings (
##,###), bold, italic, bullet and numbered lists, block quotes and links. Anything else is shown as plain text in the PDF. The title is at most 120 characters, the body at most 40,000. - Merge fields are plain tokens:
{{customer_name}},{{supplier_name}},{{approved_limit}},{{payment_terms}},{{date}}and{{signer_name}}. They are filled from the approved application when the request is created. A field with no value prints as a blank line, so a gap is noticed. A token that is not in the list is refused when saving (400), so a typo never reaches a customer. - The wording is the supplier's. The platform starters are plain starting text with no review by counsel and are not legal advice. They carry no caution inside the text, so nothing has to be deleted before publishing; the editor warns about it, and publishing needs the counsel confirmation.
States#
A version is a draft, then current, then retired. Publishing runs in one transaction: the previous current version of that kind is retired and this one becomes current, with who approved it and when. The database allows only one current version per supplier and kind. A published version never changes: editing or deleting it is a 409, and a change means a new draft (a new version).
What a request records#
When a signature request is created, it takes the supplier's current version of the matching kind and stores termsId, termsVersion and termsHash (SHA-256 of the title and body). The document the signers see is the schedule page followed by the terms pages, rendered from that exact version, so it can be reproduced from the request alone. Publishing a newer version later does not change a request already sent. Without a published version the platform template goes out as before. The supplier sees version and hash on the request; the customer does not.
Errors#
| Status | When |
|---|---|
| 400 | Empty title or body, a text over the limit, an unknown merge field, a changed kind, or no counselConfirmed: true on publish. The body lists the issues. |
| 403 | The caller lacks signatures.templates.manage (or, for in-use, signatures.send). |
| 404 | The version does not exist or belongs to another supplier. |
| 409 | Editing or deleting a published version, or publishing one that is already published. |
Audit#
Create, edit, publish and delete each record an event (terms.created, terms.updated, terms.published, terms.deleted) in the same transaction, with the actor, the version id, kind, version number and the text lengths. The wording itself is never in an audit row.
Limits#
The PDF uses a built-in Latin font. Common punctuation such as curly quotes and dashes is converted to plain characters, and characters outside Latin text print as
?.
Related#
- Signatures
- Signing terms (editor)