Categorize products

This guide organizes your catalog with categories. You’ll build a small taxonomy - a tree of categories - and classify a product, so it ends up filed under “Shoes”, then describe it with a color attribute.

A category classifies products and nests under a parent; together, categories form a taxonomy (the tree).

Prerequisites

You need a product on an existing instance. If you don’t have one, follow Create your first product first.

As in the other guides, the commands below use the organization id (shown as <org_id>) and the instance handle (the tenant, shown as <tenant>). The example reuses one product id, 019af93e-... - replace it with your own.

Before you start

You need an OAuth 2.0 bearer token for a partner account. Sign in below and pick your organization and instance: an access token scoped to that instance is generated and dropped into every product-management command on this page. See Authentication for more.

Sign in to drop your real token into the commands below.

Steps

1. Create a top-level category.

   Start the tree with a parent. Capture its @id - the child references it next.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/api/categories' \
     -H 'Authorization: Bearer {access_token}' \
     -H 'Content-Type: application/ld+json' \
     -d '{
       "status": "/api/statuses/ACTIVE",
       "name": "Clothing"
     }'

   A write returns the whole resource; the excerpt below keeps its identity (see Write responses):

   {
     "@context": "/api/contexts/Category",
     "@id": "/api/categories/019afd01-1a2b-7c3d-8e4f-0a1b2c3d4e5f",
     "@type": "Category",
     "id": "019afd01-1a2b-7c3d-8e4f-0a1b2c3d4e5f"
   }

2. Create a child category and classify the product.

   Nest “Shoes” under “Clothing” with parent, and file your product into it with products. Capture the child’s @id.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/api/categories' \
     -H 'Authorization: Bearer {access_token}' \
     -H 'Content-Type: application/ld+json' \
     -d '{
       "status": "/api/statuses/ACTIVE",
       "name": "Shoes",
       "parent": "/api/categories/019afd01-1a2b-7c3d-8e4f-0a1b2c3d4e5f",
       "products": [
         "/api/products/019af93e-420e-79f8-800b-6680f03dce20"
       ]
     }'

   {
     "@context": "/api/contexts/Category",
     "@id": "/api/categories/019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f",
     "@type": "Category",
     "id": "019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f"
   }

Describe products with attributes

Categories can also carry attributes - a Color for “Shoes”, say - that the products filed under them describe themselves with:

• an attribute definition declares the attribute and the categories it applies to. Its type is string for free text, or list for a fixed set of values;
• an attribute option is one allowed value of a list definition (Red, Blue, …);
• a product carries its values in its attributes, each referencing a definition plus either an option (for list definitions) or a value (for string definitions).

Unstable version only

Attribute definitions and options only exist in the unstable version. Every request in this section sends the Flowkiwi-Api-Version: unstable header - without it, these endpoints are not available. See Versions & support.

1. Create a list attribute definition.

   Declare a Color attribute whose values come from a fixed list. code and type are required and, like multiple, cannot be changed afterwards. multiple defaults to true; set it to false so a product carries a single color. Capture the @id.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/api/attribute_definitions' \
     -H 'Authorization: Bearer {access_token}' \
     -H 'Flowkiwi-Api-Version: unstable' \
     -H 'Content-Type: application/ld+json' \
     -d '{
       "code": "color",
       "type": "list",
       "name": "Color",
       "multiple": false
     }'

   {
     "@id": "/api/attribute_definitions/019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70",
     "@type": "AttributeDefinition",
     "id": "019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70"
   }

   See Create an attribute definition.

2. Add its options.

   Options are created under their definition. Create one per allowed value - omit position to append each at the end. Capture the @id of each option.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/api/attribute_definitions/019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70/options' \
     -H 'Authorization: Bearer {access_token}' \
     -H 'Flowkiwi-Api-Version: unstable' \
     -H 'Content-Type: application/ld+json' \
     -d '{
       "value": "Red"
     }'

   {
     "@id": "/api/attribute_options/019afd20-5e6f-7081-8a92-4d5e6f708192",
     "@type": "AttributeOption",
     "id": "019afd20-5e6f-7081-8a92-4d5e6f708192"
   }

   Repeat with "value": "Blue". Only list definitions accept options: creating one under a string definition is rejected with 422. See Create an attribute option.

3. Attach the definition to “Shoes”.

   Update the category’s attributes - the list of attribute definition IRIs attached to it. With JSON Merge Patch, the array replaces the current list, so include every definition the category should keep.

   curl -X PATCH 'https://<tenant>.product-management.flowkiwi.net/api/categories/019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f' \
     -H 'Authorization: Bearer {access_token}' \
     -H 'Flowkiwi-Api-Version: unstable' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "attributes": [
         "/api/attribute_definitions/019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70"
       ]
     }'

   {
     "@id": "/api/categories/019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f",
     "@type": "Category",
     "id": "019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f"
   }

   You can attach it from the other side too: a definition’s categories lists the categories it applies to, and can be set when you create it. See Update a category.

4. Set the product’s value.

   A product carries values for the definitions attached to its category (or one of its ancestors). Set the product’s category to “Shoes”, and add a value to its attributes that references the definition and the chosen option.

   curl -X PATCH 'https://<tenant>.product-management.flowkiwi.net/api/products/019af93e-420e-79f8-800b-6680f03dce20' \
     -H 'Authorization: Bearer {access_token}' \
     -H 'Flowkiwi-Api-Version: unstable' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "category": "/api/categories/019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f",
       "attributes": [
         {
           "definition": "/api/attribute_definitions/019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70",
           "option": "/api/attribute_options/019afd20-5e6f-7081-8a92-4d5e6f708192"
         }
       ]
     }'

   {
     "@id": "/api/products/019af93e-420e-79f8-800b-6680f03dce20",
     "@type": "Product",
     "id": "019af93e-420e-79f8-800b-6680f03dce20"
   }

   attributes replaces all of the product’s values: omit it to keep them, send [] or null to clear them. For a string definition, send a value instead of an option. See Update a product.

Next steps

• Read the tree back. List categories to see each node with its parent and childrens.
• Read the values back. Retrieve the product with the unstable version: each entry of its attributes also mirrors the definition’s code and type.
• Add free-text attributes. Create a string attribute definition - a care note, say - and set its value on the product. A definition can apply to several categories at once through its categories.