Glossary
The terms that appear in paths, scopes and refusal reasons, with the shortest accurate definition — and the pairs that are easy to read as the same thing.
Terms the API uses in a path, a scope name or a refusal reason, defined once.
The model
| Term | What it is |
|---|---|
| Object | A kind of thing a workspace keeps: an account, a quote, a task. Fourteen are standard; more can be added with the custom_objects module |
| Field | One piece of information an object’s records hold, of one of nineteen kinds |
| Record | One instance of an object |
| Relation | A field whose value is a record in another object |
| Revision | The counter a write sends back to prove it read the current state |
| View | Conditions and sorts applied to a record list, at most ten and two of them |
| Cursor | An opaque page marker that carries the ordering it was produced under |
| Workspace | What a token’s organization owns. One token, one workspace |
| Module | A part of the product a workspace can have switched on. Eight exist, and none depends on another |
| Action | The unit permission is granted in. An endpoint’s OAuth scope is its action |
Commerce
| Term | What it is |
|---|---|
| Product | Something sellable, independent of what it costs |
| Price book | A named list of prices in one currency. Prices enter it as imported entries |
| Price agreement | A binding of one account to one price book for a period. When several apply, the highest priority wins and the larger minimum quantity breaks a tie; a tie on both is refused as price_agreement_ambiguous |
| Purchase cost | What the business paid, recorded separately from what it sells for. Some pricing methods read it |
| Quote | A priced offer against an account, in a currency, at an exchange rate as of a date |
| Quote version | A numbered, frozen revision of a quote that can be read back on its own route |
| Quote draft | A version that is not frozen yet. While one is open, revising the quote is refused with quote_draft_open — finish the draft first |
| Gross margin | A rate computed against revenue |
| Markup | A rate computed against cost. Not the same number as the margin |
Pairs that read alike
| These two | Are not the same |
|---|---|
| Object and record | An object is the kind; a record is one of them. /objects/{objectId}/records/{recordId} names both |
| Activity (活動) and Event (行動) | An activity is a logged contact with a channel and a result; an event is a scheduled meeting |
| Revision and version | A revision is the concurrency counter on almost everything; a version is a quote’s deliberate, frozen snapshot |
| Price book and price agreement | The book holds the prices; the agreement says which account gets which book, when |
| Module and scope | A module is configured on the workspace and cannot be requested; a scope is granted to a token and cannot be configured |
| Archived and deleted | Archiving keeps the id and the links, so reads can still name the record. Nothing in this API deletes a record |
field_required and permission_required |
The first is a missing value; the second is a missing scope or role |
Refusals worth recognising
A refusal carries a reason when the server can name one. These come up most:
| Reason | What it means |
|---|---|
record_stale, settings_stale, quote_stale |
The revision you sent is not the current one |
cursor_ordering_mismatch |
The cursor was produced under a different ordering |
filter_unsupported_for_field |
That operator does not apply to that field’s kind |
order_field_unsupported |
That field has no single value to sort on |
field_not_scalar |
A write carried a value for a kind that has no column |
feature_disabled |
The workspace does not have the module on |
permission_required |
The token’s scope or the member’s role does not allow it |
workspace_not_initialized |
The standard objects have not been installed yet |
workspace_session_required |
The path is the web application’s, not this API’s |
Errors covers the shape a refusal arrives in and which ones are worth retrying.