---
updatedAt: 2026-09-02T13:22:56.000Z
---

# Add a custom attribute to the catalog

Use the `updateDataSet` mutation to add custom attributes to the catalog. The total number of product attributes within the catalog cannot exceed 2000.

**Typical usage:**

* Add business-specific attributes for inventory tracking
* Create attributes for regional product variations

# Before you begin

The catalog includes predefined attributes that were configured at provisioning. These predefined attributes cannot be edited. The **Product ID** attribute is required and serves as the key field that uniquely identifies products. All other predefined attributes are optional.

Before you start adding custom attributes to the catalog, review the predefined list.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Description
      </th>

      <th>
        Data format
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `availability`
      </td>

      <td>
        Availability status. Examples: "In stock", "Out of stock", "Preorder".
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `brandName`
      </td>

      <td>
        The product brand or manufacturer
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `brandDescription`
      </td>

      <td>
        Brief description of the brand
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `category`
      </td>

      <td>
        Product classification. Examples: "Electronics" or "Electronics/Cables".
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `currency`
      </td>

      <td>
        The currency in which the price is represented. We recommend using ISO 4217 currency codes. Examples: "USD", "EUR", "GBP".
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `dateAdded`
      </td>

      <td>
        Shows when the product was added to the catalog or became available to clients.

        :bulb:There is a related meta attribute in Connect that is populated automatically when you add a product to the catalog - `tracking.createdAt`.
      </td>

      <td>
        Date. Required format: ISO 8601 timestamp. Example: `2025-08-16T14:20:54.574Z`.
      </td>
    </tr>

    <tr>
      <td>
        `discount`
      </td>

      <td>
        Discount amount or percentage applied to the price
      </td>

      <td>
        Number
      </td>
    </tr>

    <tr>
      <td>
        `imageUrls`
      </td>

      <td>
        Product image URLs
      </td>

      <td>
        Array of text values. The text values must be full URLs starting with "http".
      </td>
    </tr>

    <tr>
      <td>
        `inventoryQuantity`
      </td>

      <td>
        Number of units available in stock
      </td>

      <td>
        Number
      </td>
    </tr>

    <tr>
      <td>
        `model`
      </td>

      <td>
        Model name or number
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `msrp`
      </td>

      <td>
        Manufacturer's Suggested Retail Price
      </td>

      <td>
        Number
      </td>
    </tr>

    <tr>
      <td>
        `productDescription`
      </td>

      <td>
        Product description
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `productId`
      </td>

      <td>
        Unique identifier for the product (required)
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `productName`
      </td>

      <td>
        Product name
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `productRating`
      </td>

      <td>
        Average customer rating
      </td>

      <td>
        Number
      </td>
    </tr>

    <tr>
      <td>
        `productStatus`
      </td>

      <td>
        The current status of the product. Examples: Active, Active Mature, Inactive, Discontinued, Obsolete.
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `productUrls`
      </td>

      <td>
        URLs of product pages
      </td>

      <td>
        Array of text values. The text values must be full URLs starting with "http".
      </td>
    </tr>

    <tr>
      <td>
        `sku`
      </td>

      <td>
        Stock Keeping Unit (internal tracking ID for inventory)
      </td>

      <td>
        Text
      </td>
    </tr>

    <tr>
      <td>
        `tags`
      </td>

      <td>
        Keywords or tags for searchability and custom categorization
      </td>

      <td>
        Array of text values
      </td>
    </tr>

    <tr>
      <td>
        `unitPrice`
      </td>

      <td>
        The current price of the product
      </td>

      <td>
        Number
      </td>
    </tr>
  </tbody>
</Table>

# Running the mutation

If you haven't used our API before, see [Using the Connect API](https://developer.goacoustic.com/acoustic-connect/reference/base-url) for instructions. It explains how to authenticate your calls and suggests some tools for testing.

## Using variables

```graphql Mutation
mutation ($dataSetId: ID!, $attributes: [ProductAttributeInput!]!) {
  updateDataSet(
    where: { dataSetId: $dataSetId }
    to: { attributes: { create: $attributes } }
  ) {
    dataSetId
  }
}
```
```json Response
{
  "data": {
    "updateDataSet": {
      "dataSetId": "CAT-2025YG"
    }
  }
}
```

# Basic mutation structure

```graphql
mutation {
  updateDataSet(
    where: { dataSetId: "CAT-2025YG" }
    to: {
      attributes: {
        create: [
          { name: "Available Offline", type: BOOLEAN }
          { name: "Region", type: TEXT }
        ]
      }
    }
  ) {
    dataSetId
  }
}
```

# Mutation arguments

* `where` (required): Object - Identifies the catalog to update
  * `dataSetId` (required): String - The ID of your catalog. If you don't have it, run the `dataSets` query.
* `to` (required): Object - Contains the updates to apply
  * `attributes`: Object - Attribute operations (see **Attributes object** below)

## Attributes object

* `create` (required): Array of objects - Add new attributes to the catalog. Each object represents a single attribute (see **Create attribute object** below).

## Create attribute object

* `name` (required): String - The name of the new product attribute. Case-sensitive and unique within the catalog.
* `type` (required): Enum - The data type. Valid values: `TEXT`, `NUMBER`, `DATE`, `BOOLEAN`, `JSON`, `ARRAY`.
* `validateAs`: Enum - Specifies validation rules for attributes of the `TEXT` and `ARRAY` types. Required for arrays. When you import products to Connect, only properly formatted data will be accepted. Valid values for text attributes: `TEXT` (default), `URL`. Valid values for array attributes: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `URL`.

# Mutation fields

* `dataSetId` (required): String - The ID of your catalog

[Response]() structure

The mutation returns a JSON response with this structure:

* `data`: Object - Root response object
  * `updateDataSet`: Object - Contains all fields from the mutation

# Example

Add custom attributes for offline store availability and regional tracking.

```graphql Mutation
mutation {
  updateDataSet(
    where: { dataSetId: "CAT-2025YG" }
    to: {
      attributes: {
        create: [
          { name: "Requires Assembly", type: BOOLEAN }
          { name: "Ships From", type: TEXT }
          { name: "Compliance Documents", type: TEXT, validateAs: URL }
          { name: "Offline Stores", type: ARRAY, validateAs: TEXT }
        ]
      }
    }
  ) {
    dataSetId
  }
}
```
```json Response
{
  "data": {
    "updateDataSet": {
      "dataSetId": "CAT-2025YG"
    }
  }
}
```