# Category import

Learn about the headers and values supported for importing Categories from CSV files.

## Supported headers and values

You can update a Category only if it has a `key`. You can assign a `key` to a Category either from the Category list or by using the [Categories API](/api/projects/categories.md#set-key).

When updating Categories, include only the headers and values for the fields you are updating.

| Header | Value | Required/Optional |
| --- | --- | --- |
| `data-object` | An annotation for the imported data. It is ignored during import. | Optional |
| `key` | A unique identifier for the Category that is imported. The key must only include letters, numbers, underscores (\_), or dashes (-). If a Category with the provided `key` exists, the Category is updated with the provided value—otherwise, a new Category is created. | Required |
| `name.en` | A localized name for the Category. You can provide multiple headers to include different languages values. | Required, when creating a new Category. |
| `slug.en` | A localized slug for the Category. You can provide multiple headers to include different languages values. | Required, when creating a new Category. |
| `description.en` | A localized description for the Category. You can provide multiple headers to include different languages values. | Optional |
| `externalId` | An additional identifier for the Category—for example, if the Category exists in external systems. | Optional |
| `orderHint` | Decimal value between 0 and 1. Frontend applications can use this value for ordering Categories within the same level in the category tree. This value must always use a point (`.`) as the decimal separator. | Optional |
| `metaTitle.en` | A localized name for the Category for search engines. You can provide multiple headers to include different languages values. | Optional |
| `metaDescription.en` | A localized description for the Category for search engines. You can provide multiple headers to include different languages values. | Optional |
| `metaKeywords.en` | A localized keyword for the Category for improved search engine performance. You can provide multiple headers to include different languages values. | Optional |
| `parent.key` | A unique identifier for a Category used as the parent, if the imported Category is a child Category. Before importing, a Category with this `key` must exist. | Required, when updating a parent Category. |
| `parent.typeId` | `category` | Required, if `parent.key` is provided. |
| `custom.type.key` | A unique identifier for the Type referenced in a Custom Field. | Required, when importing Custom Fields to a Category. |
| `custom.type.typeId` | `type` | Required, if `custom.type.key` is provided. |
| `custom.fields.{nameOfCustomField}` | Replace `{nameOfCustomField}` with the name of the Custom Field, as defined in the respective [FieldDefinition](/search.md?urn=ctp:api:type:FieldDefinition). The value must conform to the [FieldType](/api/projects/types.md#fieldtype) of the Custom Field. For more information, see [Custom Fields](/merchant-center/import-categories.md#custom-fields). | Optional |
| `assets.key` | A unique identifier for the Asset. The key must only include letters, numbers, underscores (\_), or dashes (-). If an Asset with the provided `key` exists in the Category, the Asset is updated with the provided value—otherwise, a new Asset is created. | Required, when importing Assets. |
| `assets.name.en` | A localized name for the Asset. You can provide multiple headers to include different languages values. | Required, when importing Assets. |
| `assets.description.en` | A localized description for the Asset. You can provide multiple headers to include different languages values. | Optional |
| `assets.sources.uri` | A URI for the Asset. | Required, when importing Assets. |
| `assets.tags` | A semicolon-separated list of keywords used for categorizing and organizing Assets. | Optional |
| `assets.custom.type.key` | A unique identifier for the Type referenced in a Custom Field. | Required, when importing Custom Fields to a Asset. |
| `assets.custom.type.typeId` | `type` | Required, if `assets.custom.type.key` is provided. |
| `assets.custom.fields.{nameOfCustomField}` | Replace `{nameOfCustomField}` with the name of the Custom Field, as defined in the respective [FieldDefinition](/search.md?urn=ctp:api:type:FieldDefinition). The value must conform to the [FieldType](/api/projects/types.md#fieldtype) of the Custom Field. For more information, see [Custom Fields](/merchant-center/import-categories.md#custom-fields). | Optional |

### Custom Fields

Replace `{nameOfCustomField}` with the name of the Custom Field, as defined in the respective [FieldDefinition](/api/projects/types#fielddefinition). The name of the Custom Field is case-sensitive.

When importing LocalizedString Custom Fields, provide headers and values for each language. For example, for English and German, provide `custom.fields.{nameOfCustomField}.en` and `custom.fields.{nameOfCustomField}.de` respectively.

When importing boolean Custom Fields, the values must be lowercase.

For Money Custom Fields, provide the following additionally:

| Header | Value | Required/Optional |
| --- | --- | --- |
| `custom.fields.{nameOfCustomField}.currencyCode` | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)-compliant currency code such as `USD`, `EUR`, or `GBP`. | Required |
| `custom.fields.{nameOfCustomField}.centAmount` | An amount in the smallest indivisible unit for a currency. For example, `500` can be equal to USD 5.00 or JPY 500. | Required |
| `custom.fields.{nameOfCustomField}.type` | `centPrecision` | Required |
| `custom.fields.{nameOfCustomField}.fractionDigits` | The number of digits after the decimal separator. For example, `2` for USD or `0` for JPY. | Required |

#### Sets of Custom Fields

For sets of simple Custom Fields (such as numbers, text, and booleans) the header would contain the Custom Fields name, and value would be a semicolon-separated list. The following example demonstrates how to import sets of text and numbers.

| `custom.fields.colorCombination` | `custom.fields.numberSet` |
| --- | --- |
| `red;green;blue` | `10;5;32` |

##### Sets of complex Custom Fields

For sets of complex values (such as localized text, references, and money), you can import single set values by defining the index and the subfields in the header. The following example demonstrates how to update the first entry of a set of Custom Fields called `relatedCategories` that references Categories.

| `custom.fields.relatedCategories.1.key` | `custom.fields.relatedCategories.1.typeId` |
| --- | --- |
| `red-shirts` | `category` |

To update the second entry, include the same headers but change `1` to `2`.

You can also import multiple set values by using `*` instead of a number. With this approach, the values of set items are entered into sequential rows.

The following example demonstrates how to create a set of Custom Fields called `relatedCategories` with four entries.

| `custom.fields.relatedCategories.*.key` | `custom.fields.relatedCategories.*.typeId` |
| --- | --- |
| `red-shirts` | `category` |
| `summer-collection` | `category` |
| `new-arrivals` | `category` |
| `red-accessories` | `category` |

## Delete data

When updating resources, you can remove data for optional fields. To remove data, in the CSV file, enter `[DELETE]` as the value for the header (field). When deleting values for reference fields or multi-value fields, you must add a new column with the common prefix as the header, and enter `[DELETE]` as the value.

For example, to delete data for a parent Category, add a new column, `parent`, with `[DELETE]` as its value.

| `key` | `name.en-US` | `name.de-DE` | `parent` |
| --- | --- | --- | --- |
| `category-key-1` | `New Category name` | `Neuer Kategorie Name` | `[DELETE]` |

## Related pages

- [Area overview page with navigation](/merchant-center.md)
- [Previous page: Business Units](/merchant-center/import-business-units.md)
- [Next page: Custom Objects](/merchant-center/import-custom-objects.md)
- [Search documentation and API specs](/search.md)