Printago API
GET
/v1/custom-metadata-definitions
List custom field definitions
Definitions are reference data: the values editor on every detail page needs them to render the right input and to warn on near-miss keys, so reads are open to any store member. Authoring is gated on routing.manage.
Query Parameters
entityType
optional
string
Filter on
entityType. A bare value is an exact match (entityType=value); use entityType.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.
key
optional
string
Filter on
key. A bare value is an exact match (key=value); use key.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.
label
optional
string
Filter on
label. A bare value is an exact match (label=value); use label.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.
valueType
optional
string
Filter on
valueType. A bare value is an exact match (valueType=value); use valueType.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.
enumValues
optional
string
Filter on
enumValues. A bare value is an exact match (enumValues=value); use enumValues.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.
unit
optional
string
Filter on
unit. A bare value is an exact match (unit=value); use unit.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.
defaultValue
optional
string
Written into a record's `customMetadata` when that record is created, so
the field is on every new record of its type. This is the only way a
definition puts itself on a record: a field with no value is not listed,
because a row the record does not carry is a row that lies about it.
Never applied to records that already exist.
defaultToNow
optional
string
Date/time fields only, and the only default they can carry: the value is
the moment the record was created. A fixed date is almost never the right
default, and there is no way to express "now" as a literal.
id
optional
string
Filter by record ID. A bare value is an exact match; use
id.in=a,b,c for several (up to 100). See Querying Data.
storeId
optional
string
Filter by store ID. Results are always limited to the store your API key belongs to, so this is rarely useful. See Querying Data.
createdAt
optional
string
Filter by creation time. Pass an ISO 8601 timestamp with a comparison operator, e.g.
createdAt.gte=2025-01-01T00:00:00Z. See Querying Data.
updatedAt
optional
string
Filter by last-modified time. Pass an ISO 8601 timestamp with a comparison operator, e.g.
updatedAt.gt=2025-01-01T00:00:00Z to fetch what changed since a checkpoint. See Querying Data.
sort
optional
string
Comma-separated
field:direction pairs, applied in order, e.g. createdAt:desc,name:asc. Direction is asc (the default) or desc. At most 5 clauses; JSON and array fields cannot be sorted on. See Querying Data.
limit
optional
number
Maximum number of records to return, 1–1000. Defaults to 1000; larger values are capped at 1000. See Querying Data.
offset
optional
number
Number of matching records to skip before returning results. Combine with
limit to page through a list, and with meta=true to learn the total. See Querying Data.
fields
optional
string
Comma-separated list of fields to return, e.g.
id,name,updatedAt. Other fields are left out of each record. At most 50 fields. See Querying Data.
include
optional
string
Comma-separated related records to embed in each result, e.g.
linkedParts,linkedParts.part. At most 4 includes, each at most 2 levels deep; only the relations this endpoint supports are accepted, anything else is a 400. See Querying Data.
meta
optional
boolean
Set to
true to wrap the response as { data, meta }, where meta carries total, count, offset, limit, hasMore and executionTime. Without it the response is a bare array. See Querying Data.
hints
optional
boolean
Set to
true to add a hints array of suggested follow-up API calls to the response (aimed at AI agents). A list response is wrapped as { data, meta, hints }. See Querying Data.
Response Schema
CustomMetadataDefinition[] | SearchResponse
Variant 1CustomMetadataDefinition[]
createdAtrequired
string
format: date-time
defaultToNowrequired
boolean
Date/time fields only, and the only default they can carry: the value is
the moment the record was created. A fixed date is almost never the right
default, and there is no way to express "now" as a literal.
defaultValuerequirednullable
string | number | boolean
Written into a record's `customMetadata` when that record is created, so
the field is on every new record of its type. This is the only way a
definition puts itself on a record: a field with no value is not listed,
because a row the record does not carry is a row that lies about it.
Never applied to records that already exist.
entityTyperequired
enum
orderskuprinterpartmaterialmaterialVariantprintJobpartBuildprofilematerialInstancemaintenanceItemcustomerorderItemfolder
enumValuesrequirednullable
string[]
idrequired
string
pattern: ^[a-z0-9]{24}$
keyrequired
string
labelrequired
string
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
unitrequirednullable
string
updatedAtrequired
string
format: date-time
valueTyperequired
"string" | "number" | "boolean" | "enum" | "datetime"
stringnumberbooleanenumdatetime
datarequired
Record<string, any>[]
Array of matching entities
metarequired
object
Pagination and result metadata
countrequired
number
Number of records returned in this response
executionTimerequired
number
Query execution time in milliseconds
hasMorerequired
boolean
Whether there are more records available
limitrequired
number
Maximum number of records requested
offsetrequired
number
Number of records skipped
totalrequired
number
Total number of matching records (before pagination)
Example Response
200 OK — application/json
[
{
"entityType": "order",
"key": "string",
"label": "string",
"valueType": "string",
"enumValues": [
"string"
],
"unit": "string",
"defaultValue": "string",
"defaultToNow": true,
"id": "string",
"storeId": "string",
"createdAt": "2025-01-15T12:00:00.000Z",
"updatedAt": "2025-01-15T12:00:00.000Z"
}
]