# Categories

Categories can be used to mark [listings](/documentation/by-pillar/global-inventory-hub/listing.md) as belonging to a specific group. A listing can belong to one to many categories. The `categoryRef` on the listing allows assigning categories to a listing. Categories can be used, for example, to define discounts for certain article groups.

Listings can be assigned to an article category by:

1. Creating a category via [API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/categories)
2. Referencing the ID of the category in the respective listing(s)

Categories can be created, edited and deleted via [REST API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/categories). Categories that are assigned to one or more listings cannot be deleted.

{% hint style="info" %}
For a complete overview of the category endpoints, refer to the [API documentation for Categories](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/categories).
{% endhint %}

## Create a category

To create a category, send a `POST` request to the following endpoint with the category data in the request body.

```http
POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/categories
```

**Example request body**

```json
{
  "nameLocalized": {
    "de_DE": "Lebensmittel",
    "en_US": "groceries"
  },
  "tenantCategoryId": "G-01"
}
```

A successful request returns a `201 CREATED` response with a body that includes the `id` of the newly created category.

**Example response body**

```json
{
    "lastModified": "2025-04-25T09:06:54.737Z",
    "version": 1,
    "nameLocalized": {
        "de_DE": "Lebensmittel",
        "en_US": "groceries"
    },
    "tenantCategoryId": "G-01",
    "id": "1f6fe169-893f-4e95-8ac0-38c9e6eca068",
    "created": "2025-04-25T09:06:54.737Z",
    "name": "groceries"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/categories.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.