Add, update, or delete reference set records

Use the upsertReferenceSetRecords and deleteReferenceSetRecords mutations to manage the rows in a reference set. One call can change up to 100 rows.

  • upsertReferenceSetRecords adds new rows or updates rows that already exist.
  • deleteReferenceSetRecords deletes 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 dataSets query 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 an attributes list. Each item in the list has a name and a value.

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, returns TEXT_FORMAT.

How values are written

Updating values

  • An attribute you don't send stays unchanged.
  • null clears 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 as 2026-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, including 1, "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:

IndexRowResult
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 sentResult
{ 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 upsertedCount and rejectedCount.
  • Delete returns deletedCount and rejectedCount.
  • Both return records(status: [ACCEPTED, REJECTED]). The default filter is REJECTED.
  • Each item in records is AcceptedPayload { status index } or RejectedPayload { status index errors }.
  • index is the position of the row in your call. It starts at 0.
  • errors has one error for each failing attribute. Each error has code, message, and attribute.

How rows are counted

  • Upsert: upsertedCount plus rejectedCount equals the number of rows you sent.
  • Delete: deletedCount is the number of different keys that existed and were deleted. rejectedCount is 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 deletedCount 0.
  • If the write fails, every row that passed validation is rejected with WRITE_FAILED. If no row was written or deleted, the call fails with ALL_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, the records list is empty, an attributes list 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 upsertedCount 2 and rejectedCount 1. The rejected row has index 2.
  • A delete of an existing key, a missing key, and a key with an empty key part returns deletedCount 1 and rejectedCount 1. The rejected row has index 2.
  • A delete of one missing key succeeds with deletedCount 0.
  • 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

TopicAPIFile import
Empty key partBLANK_VALUEVALIDATION_ERROR
Unknown attributeRejected at row levelHandled at job level
Rows with the same keyApplied in the order you send them. The later row wins.Run in parallel, in no set order
Delete of a key that does not existSkipped and not listedCounted as unmatched
Delete that deletes nothingReturns deletedCount 0Counts the keys as unmatched
How results arriveIn the responseIn the data job and its errors file
Options only a file import hasNonedateFormat, overwriteEmptyFields
Non-key columns on deleteIgnoredType-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.