Use the upsertReferenceSetRecords and deleteReferenceSetRecords mutations to manage the rows in a reference set. One call can change up to 100 rows.
upsertReferenceSetRecordsadds new rows or updates rows that already exist.deleteReferenceSetRecordsdeletes rows by their key.
To delete a whole reference set, see Delete a reference set. To load many rows from a file, see Update a reference set.
Preconditions
- You have a reference set in Connect.
- You have an API key.
- You know the ID of the reference set. Use the
dataSetsquery to get it.
If you haven't used our API before, see Use the Connect API for instructions.
Mutation structure
Both mutations take two arguments.
dataSetId(required): ID. The ID of the reference set.records(required): Array of objects. The rows to add, update, or delete. Each row has anattributeslist. Each item in the list has anameand avalue.
Upsert
mutation UpsertRecords($dataSetId: ID!, $records: [ReferenceSetRecordUpsertInput!]!) {
upsertReferenceSetRecords(dataSetId: $dataSetId, records: $records) {
upsertedCount
rejectedCount
records(status: [ACCEPTED, REJECTED]) {
... on AcceptedPayload { status index }
... on RejectedPayload { status index errors { code message attribute } }
}
}
}Variables:
{
"dataSetId": "{REFERENCE_SET_ID}",
"records": [
{
"attributes": [
{ "name": "sku", "value": "A-100" },
{ "name": "price", "value": 9.99 }
]
}
]
}Delete
mutation DeleteRecords($dataSetId: ID!, $records: [ReferenceSetRecordDeleteInput!]!) {
deleteReferenceSetRecords(dataSetId: $dataSetId, records: $records) {
deletedCount
rejectedCount
records { ... on RejectedPayload { index errors { code message attribute } } }
}
}Variables:
{
"dataSetId": "{REFERENCE_SET_ID}",
"records": [
{
"attributes": [
{ "name": "sku", "value": "A-100" }
]
}
]
}The dataSetId must be a reference set in your subscription. If it is unknown, an audience, or a catalog, the call fails with DATA_SET_NOT_FOUND and nothing is written. An unknown reference set and a reference set you cannot access return the same error.
In the examples below, a row is written as a short list, for example { country: "PL", sku: "A-1" }. In a request, write each row as an attributes list with name and value pairs.
How rows are identified
A row is identified by its full key. A key has 1 to 6 key attributes, and all of them are TEXT.
- You can send the key attributes in any order.
- Keys are case-sensitive.
"a-1"and"A-1"are two different rows. - A key part can have up to 4032 characters.
- If the key already exists, the stored row is updated.
- The same key rules apply to upsert and delete.
A row is rejected if a key part is missing, null, empty, only spaces, or not a string. The other rows in the call are still written.
- A key part that is missing, null, empty, or only spaces returns
BLANK_VALUE. The error names the key attribute. - A key part sent as a number, such as
12, returnsTEXT_FORMAT.
How values are written
Updating values
- An attribute you don't send stays unchanged.
nullclears the value.- A cleared value reads as empty, the same as an attribute that was never set. A segment condition "is empty" matches both.
- Sending the same call twice leaves the same rows as sending it once. A retry is safe.
Validation
- Every row is checked against the reference set definition when you send the call.
- A row with any error is rejected on its own. Nothing from that row is written. The other rows are written.
- A row with an attribute that the reference set does not have is rejected with
ATTRIBUTE_NOT_IN_DATASET. You get one error for each such attribute. Names are case-sensitive. - After you add the attribute to the reference set, Connect accepts it from the next call.
- Each failing attribute gets its own error. One row can return several errors.
Repeated keys in one call
- Upsert: rows with the same key are applied in the order you send them. The later row wins for each attribute. Every repeated row is counted in
upsertedCount. - Delete: a key sent twice is deleted once and counted once in
deletedCount.
Delete behavior
- Connect checks only the key. It ignores other attributes in a delete row.
- A key that does not exist is skipped. It is not counted and not listed in
records.
Attribute values by type
Connect converts every value to the attribute type defined in the reference set. This is the same conversion that the file import uses. For example, "12" becomes 12 for a NUMBER attribute, and 12 becomes "12" for a TEXT attribute.
DATE
- Accepted: ISO-8601 with an offset or
Z, for example"2026-10-03T10:00:00+02:00". A date only, such as"2026-10-03", is stored as 00:00 UTC. - Rejected with
TIMESTAMP_FORMAT: a date and time without an offset, week and ordinal formats such as"2026-W40", local formats such as"03/10/2026", a blank value, and a value that is not a string. - Stored as UTC with 3 fractional digits and
Z. For example,"2026-10-03T10:00:00+02:00"is stored as2026-10-03T08:00:00.000Z.
BOOLEAN
- Accepted:
true,false, and the strings"true"and"false"in any letter case. Spaces around the value are ignored. - Rejected with
BOOLEAN_FORMAT: anything else, including1,"yes", and a blank value.
TEXT
- Stored exactly as sent, including spaces and values that start with
$. - A number or a boolean is stored as text.
- Rejected with
MAX_LENGTH: a value over 4032 characters. - An object or a list is not supported. The whole call fails with
INPUT_VALIDATION_FAILED.
NUMBER
- Accepted: a JSON number, or a string with a plain decimal number. A plain decimal number has digits, an optional leading minus sign, at most one decimal point, and an optional exponent. For example,
"9.99"is stored as 9.99 and"1e3"is stored as 1000. - Rejected with
NUMERIC_FORMAT:"+5","1,000","0x1A","-", a blank value, and a boolean. - Rejected with
NUMERIC_RANGE: more than 15 significant digits.
Example
A reference set has the key attributes country and sku. It has the attributes price (NUMBER), colour (TEXT), and validFrom (DATE).
You send one upsert call with four rows:
| Index | Row | Result |
|---|---|---|
| 0 | { country: "PL", sku: "A-1", price: 9, colour: "red" } | Accepted |
| 1 | { country: "PL", sku: "A-2", price: 9, size: "M" } | Rejected with ATTRIBUTE_NOT_IN_DATASET for size |
| 2 | { country: "PL", sku: "A-3", price: "abc" } | Rejected with NUMERIC_FORMAT for price |
| 3 | { country: "PL", sku: "A-4", validFrom: "3/10/26" } | Rejected with TIMESTAMP_FORMAT for validFrom |
The call returns upsertedCount 1 and rejectedCount 3. The rejected rows have the indexes 1, 2, and 3.
Then you send more calls for row A-1:
| Row sent | Result |
|---|---|
{ country: "PL", sku: "A-1", price: 10 } | Accepted. The price is 10. The colour is still "red". |
{ country: "PL", sku: "A-1", colour: null } | Accepted. The colour reads as empty. The price is unchanged. |
{ country: null, sku: "A-1", price: 10 } | Rejected. A key part cannot be empty. |
You can also repeat a key in one call. If you send { country: "PL", sku: "A-1", price: 9 } and then { country: "PL", sku: "A-1", colour: "blue" }, Connect stores price 9 and colour "blue". The call returns upsertedCount 2.
Response
What the call returns
- Upsert returns
upsertedCountandrejectedCount. - Delete returns
deletedCountandrejectedCount. - Both return
records(status: [ACCEPTED, REJECTED]). The default filter isREJECTED. - Each item in
recordsisAcceptedPayload { status index }orRejectedPayload { status index errors }. indexis the position of the row in your call. It starts at 0.errorshas one error for each failing attribute. Each error hascode,message, andattribute.
How rows are counted
- Upsert:
upsertedCountplusrejectedCountequals the number of rows you sent. - Delete:
deletedCountis the number of different keys that existed and were deleted.rejectedCountis the number of invalid keys. - A delete row is rejected only if its key is invalid.
Partial success
- If at least one row is written or deleted, the call succeeds. Connect lists the rejected rows in
records. - If nothing is written or deleted and at least one row is rejected, the call fails with
ALL_ROWS_FAILED. The error includes the counts and the rejected rows. - A key that does not exist is not a rejected row. A delete where no key exists succeeds with
deletedCount0. - If the write fails, every row that passed validation is rejected with
WRITE_FAILED. If no row was written or deleted, the call fails withALL_ROWS_FAILED. You can retry these calls.
When the whole call fails
The whole call fails and nothing is written in these cases:
- Authentication fails.
- The call has more rows than the row limit (
BATCH_LIMIT_EXCEEDED). - A row has more attributes than the attribute limit (
ATTRIBUTES_LIMIT_EXCEEDED). - The reference set is unknown, or the ID is not a reference set (
DATA_SET_NOT_FOUND). - The request is not valid (
INPUT_VALIDATION_FAILED). For example, therecordslist is empty, anattributeslist is empty, a row has the same attribute name twice, an attribute name is empty, or a value is an object or a list. - A temporary error occurs while Connect reads the reference set definition (
SUPER_GRAPH_REQUEST_FAILED). You can retry this call. - The feature is not enabled for your subscription (
UNSUPPORTED_OPERATION).
Examples of results
- An upsert of 3 rows where the third row is not valid returns
upsertedCount2 andrejectedCount1. The rejected row has index 2. - A delete of an existing key, a missing key, and a key with an empty key part returns
deletedCount1 andrejectedCount1. The rejected row has index 2. - A delete of one missing key succeeds with
deletedCount0. - A delete where the only key has an empty key part fails with
ALL_ROWS_FAILED.
When changes are visible
- The latest write wins. A write does not carry a version.
- If a file import is running, Connect applies the API writes that arrive during the import after it ends.
Limits
Rows per call
- A call with more rows than the limit is refused with
BATCH_LIMIT_EXCEEDED. Nothing is written or deleted. - The default limit is 100 rows. The limit can be lower for your subscription. It cannot be higher than 100.
Attributes per row
- A call where any row has more attributes than the limit is refused with
ATTRIBUTES_LIMIT_EXCEEDED. Nothing is written or deleted. - The default limit is 100 attributes. Key attributes count toward the limit.
Differences from a file import
| Topic | API | File import |
|---|---|---|
| Empty key part | BLANK_VALUE | VALIDATION_ERROR |
| Unknown attribute | Rejected at row level | Handled at job level |
| Rows with the same key | Applied in the order you send them. The later row wins. | Run in parallel, in no set order |
| Delete of a key that does not exist | Skipped and not listed | Counted as unmatched |
| Delete that deletes nothing | Returns deletedCount 0 | Counts the keys as unmatched |
| How results arrive | In the response | In the data job and its errors file |
| Options only a file import has | None | dateFormat, overwriteEmptyFields |
| Non-key columns on delete | Ignored | Type-checked |
In a file, an empty cell is left out with overwriteEmptyFields off and treated as null with it on.
Possible error messages
For the full list of error codes, see Error codes.
