Update metadata individually or in batches
Metadata updates accept either one key and value pair or a metadata array. Existing calls continue to work. A batch lets you update several fields in one API call.
| Mutation | Resource identifier |
|---|---|
updateContactMetadata | contactId |
updateBookingMetadata | bookingId |
updateInvoiceMetadata | invoiceId |
updateLocationMetadata | locationId (location group ID) |
updateProductMetadata | productId |
updateUserMetadata | userId |
updatePathwayMetadata | pathwayId |
Single pair
mutation UpdateContactMetadata($id: ID!, $key: String!, $value: String!) {
updateContactMetadata(contactId: $id, key: $key, value: $value) {
data {
id
}
error
}
}
The other mutations use the same arguments with their resource identifier. For backward compatibility, updateProductMetadata.key retains the GraphQL ID scalar: use $key: ID! for product single-pair calls. The other single-pair keys use String. Batch entry keys use String for all available mutations.
Batch
mutation UpdateContactMetadataBatch(
$id: ID!
$metadata: [MetadataEntryInput!]!
) {
updateContactMetadata(contactId: $id, metadata: $metadata) {
data {
id
}
error
}
}
Example variables:
{
"id": "RESOURCE_ID",
"metadata": [
{ "key": "external_reference", "value": "REF-123" },
{ "key": "source", "value": "Connect" }
]
}
Use the corresponding mutation and resource identifier from the table to update another resource. Pathways accept this existing batch form as well as the single-pair form.
Validation and limits
- Supply exactly one form: both
keyandvalue, or a non-emptymetadataarray. Supplying neither form or mixing forms is rejected, including supplying only a key or value alongside a batch. - Omit unused arguments. Explicit
nullarguments andnullarray entries are rejected. - Each entry must contain a non-empty key and value after sanitisation. Existing character validation and sanitisation rules apply, including a maximum key length of 40 characters and value length of 500 characters.
- Duplicate keys within a batch are rejected after key sanitisation. For example,
referenceandreferenceare duplicates. - Each stored resource can contain at most 50 metadata keys. This is the existing limit and applies to the resulting stored metadata, rather than to each API call. Overwriting existing keys does not use additional capacity.
Updates add new keys or overwrite supplied existing keys and preserve all unspecified keys. Every batch succeeds or fails as a whole: an invalid entry or an exceeded limit leaves the metadata unchanged.
For example, if a contact has 49 keys, a batch overwriting one key and adding one new key succeeds. Adding two new keys fails without applying either entry. At 50 keys, updates to existing keys continue to work.