Heads up, our devs are blazing ahead—docs are catching up, so some features might not be fully documented yet.
Visit our websiteAPI Documentation

Categories

Categories

List categories

get

List all root categories

Required permission: TENANT.ACCESS

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
withProductsbooleanOptional

Include Product list

categoryParentUidstringOptional

Filter on category parent uid

Pattern: ^[A-Za-z0-9-_]+
categoryExternalIdstringOptional

External reference to a category.

pageNumberintegerOptional

Reference to a specific page in a result set.

pageSizeintegerOptional

The number of items per page in a result set.

sortBystringOptional

Defines which field the resource list is sorted by.

sortDirectionstring · enumOptional
ENUM Description
ASC Sort in ascending order
DESC Sort in descending order
Possible values:
Responses
200
Example response
application/json
get
GET /v2/tenants/{tenantUid}/categories HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Example response

{
  "items": [
    {
      "categories": [
        {
          "categoryUid": "text",
          "createdAt": "2025-06-30T20:26:17.613Z",
          "externalId": "text",
          "lastModifiedAt": "2025-06-30T20:26:17.613Z",
          "name": "text"
        }
      ],
      "categoryUid": "text",
      "createdAt": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "name": "text",
      "parentUid": "text",
      "products": [
        {
          "storeProductDetails": {
            "grossProfitAmount": 1,
            "grossProfitPercentage": 1,
            "costPrice": 1,
            "price": 1,
            "campaignPrice": 1,
            "campaignName": "text",
            "quantityReserved": 1,
            "quantityStock": 1,
            "quantityOrdered": 1
          },
          "allowAddon": true,
          "allowCredit": true,
          "allowPurchase": true,
          "allowQuantity": true,
          "allowSale": "YES",
          "allowSaleDate": "2025-06-30T20:26:17.613Z",
          "allowDelivery": "YES",
          "allowDeliveryDate": "2025-06-30T20:26:17.613Z",
          "availableForWeb": true,
          "brandUid": "text",
          "brandName": "text",
          "calculationFactor": 1,
          "categoryUids": [
            "text"
          ],
          "createdAt": "2025-06-30T20:26:17.613Z",
          "customerAgeRestriction": 1,
          "description": "text",
          "discontinuedFrom": "2025-06-30T20:26:17.613Z",
          "externalId": "text",
          "externalInfo": "text",
          "externalUrl": "text",
          "gtins": [
            {
              "gtin": "text",
              "primary": true,
              "type": "text"
            }
          ],
          "height": 1,
          "internalInfo": "text",
          "lastModifiedAt": "2025-06-30T20:26:17.613Z",
          "ledgerNumber": "text",
          "length": 1,
          "name": "text",
          "optionProperties": [
            {
              "productPropertyUid": "text",
              "propertyName": "text",
              "propertyOptionName": "text",
              "propertyType": "TEXT",
              "propertyText": "text",
              "propertyUid": "text",
              "propertyOptionUid": "text",
              "required": true
            }
          ],
          "priceOverride": true,
          "productGroupUid": "text",
          "productGroupPath": [
            {
              "name": "text",
              "parentUid": "text",
              "productGroupUid": "text"
            }
          ],
          "productUid": "text",
          "productType": "STOCK",
          "recommendedRetailPrice": 1,
          "requiredVariantPropertyUids": [
            "text"
          ],
          "serialNoRequired": "NO",
          "shortDescription": "text",
          "sku": "text",
          "manufacturerSku": "text",
          "suppliers": [
            {
              "name": "text",
              "supplierUid": "text"
            }
          ],
          "textProperties": [
            {
              "productPropertyUid": "text",
              "propertyName": "text",
              "propertyOptionName": "text",
              "propertyType": "TEXT",
              "propertyText": "text",
              "propertyUid": "text",
              "propertyOptionUid": "text",
              "required": true
            }
          ],
          "unitLabel": "text",
          "variantProductUids": [
            "text"
          ],
          "variantParentProductUid": "text",
          "vatCodeUid": "text",
          "weight": 1,
          "width": 1,
          "links": [
            {
              "productLinkUid": "text",
              "linkType": "INSURANCE",
              "productUid": "text"
            }
          ],
          "parents": [
            {
              "productLinkUid": "text",
              "linkType": "INSURANCE",
              "productUid": "text"
            }
          ],
          "requirements": {
            "requireCustomer": true,
            "requireCustomerMobile": true,
            "requireCustomerEmail": true,
            "requireCustomerDeliveryAddress": true
          },
          "coverImage": {
            "productMediaUid": "text",
            "mainUrl": "text",
            "thumbnailUrl": "text"
          },
          "imageCount": 1,
          "relevance": 1,
          "visibility": "ALWAYS_VISIBLE",
          "commission": 1,
          "productWarrantyUid": "text",
          "excludeFromStatistics": true,
          "purchasePrice": 1,
          "numberOfPieces": 1,
          "limitToStoreUids": [
            "text"
          ]
        }
      ]
    }
  ],
  "paging": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalCount": 1
  }
}

Create a new category

post

Create a new category.

Required permission: TENANT.BACKOFFICE

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
Body
externalIdstringOptional
namestringRequired
parentUidstringOptionalPattern: ^[A-Za-z0-9-_]*
categoryUidstringOptionalPattern: ^[A-Za-z0-9-_]+
Responses
200
Example response
application/json
post
POST /v2/tenants/{tenantUid}/categories HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "externalId": "text",
  "name": "text",
  "parentUid": "text",
  "categoryUid": "text"
}
200

Example response

{
  "categories": [
    {
      "categoryUid": "text",
      "createdAt": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "name": "text"
    }
  ],
  "categoryUid": "text",
  "createdAt": "2025-06-30T20:26:17.613Z",
  "externalId": "text",
  "lastModifiedAt": "2025-06-30T20:26:17.613Z",
  "name": "text",
  "parentUid": "text",
  "products": [
    {
      "storeProductDetails": {
        "grossProfitAmount": 1,
        "grossProfitPercentage": 1,
        "costPrice": 1,
        "price": 1,
        "campaignPrice": 1,
        "campaignName": "text",
        "quantityReserved": 1,
        "quantityStock": 1,
        "quantityOrdered": 1
      },
      "allowAddon": true,
      "allowCredit": true,
      "allowPurchase": true,
      "allowQuantity": true,
      "allowSale": "YES",
      "allowSaleDate": "2025-06-30T20:26:17.613Z",
      "allowDelivery": "YES",
      "allowDeliveryDate": "2025-06-30T20:26:17.613Z",
      "availableForWeb": true,
      "brandUid": "text",
      "brandName": "text",
      "calculationFactor": 1,
      "categoryUids": [
        "text"
      ],
      "createdAt": "2025-06-30T20:26:17.613Z",
      "customerAgeRestriction": 1,
      "description": "text",
      "discontinuedFrom": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "externalInfo": "text",
      "externalUrl": "text",
      "gtins": [
        {
          "gtin": "text",
          "primary": true,
          "type": "text"
        }
      ],
      "height": 1,
      "internalInfo": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "ledgerNumber": "text",
      "length": 1,
      "name": "text",
      "optionProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "priceOverride": true,
      "productGroupUid": "text",
      "productGroupPath": [
        {
          "name": "text",
          "parentUid": "text",
          "productGroupUid": "text"
        }
      ],
      "productUid": "text",
      "productType": "STOCK",
      "recommendedRetailPrice": 1,
      "requiredVariantPropertyUids": [
        "text"
      ],
      "serialNoRequired": "NO",
      "shortDescription": "text",
      "sku": "text",
      "manufacturerSku": "text",
      "suppliers": [
        {
          "name": "text",
          "supplierUid": "text"
        }
      ],
      "textProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "unitLabel": "text",
      "variantProductUids": [
        "text"
      ],
      "variantParentProductUid": "text",
      "vatCodeUid": "text",
      "weight": 1,
      "width": 1,
      "links": [
        {
          "productLinkUid": "text",
          "linkType": "INSURANCE",
          "productUid": "text"
        }
      ],
      "parents": [
        {
          "productLinkUid": "text",
          "linkType": "INSURANCE",
          "productUid": "text"
        }
      ],
      "requirements": {
        "requireCustomer": true,
        "requireCustomerMobile": true,
        "requireCustomerEmail": true,
        "requireCustomerDeliveryAddress": true
      },
      "coverImage": {
        "productMediaUid": "text",
        "mainUrl": "text",
        "thumbnailUrl": "text"
      },
      "imageCount": 1,
      "relevance": 1,
      "visibility": "ALWAYS_VISIBLE",
      "commission": 1,
      "productWarrantyUid": "text",
      "excludeFromStatistics": true,
      "purchasePrice": 1,
      "numberOfPieces": 1,
      "limitToStoreUids": [
        "text"
      ]
    }
  ]
}

Category details

get

Get category details

If storeUid is supplied prices and stock from the store will be returned, if no storeUid is supplied the quantityStock will always be 0 and the price will be the reccommended retail price

Required permission: TENANT.ACCESS

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
categoryUidstringRequired

Reference to a Category.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
storeUidstringOptional

Reference to a store uid

Pattern: ^[A-Za-z0-9-_]+
Responses
200
Example response
application/json
get
GET /v2/tenants/{tenantUid}/categories/{categoryUid} HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Example response

{
  "categories": [
    {
      "categoryUid": "text",
      "createdAt": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "name": "text"
    }
  ],
  "categoryUid": "text",
  "createdAt": "2025-06-30T20:26:17.613Z",
  "externalId": "text",
  "lastModifiedAt": "2025-06-30T20:26:17.613Z",
  "name": "text",
  "parentUid": "text",
  "products": [
    {
      "storeProductDetails": {
        "grossProfitAmount": 1,
        "grossProfitPercentage": 1,
        "costPrice": 1,
        "price": 1,
        "campaignPrice": 1,
        "campaignName": "text",
        "quantityReserved": 1,
        "quantityStock": 1,
        "quantityOrdered": 1
      },
      "allowAddon": true,
      "allowCredit": true,
      "allowPurchase": true,
      "allowQuantity": true,
      "allowSale": "YES",
      "allowSaleDate": "2025-06-30T20:26:17.613Z",
      "allowDelivery": "YES",
      "allowDeliveryDate": "2025-06-30T20:26:17.613Z",
      "availableForWeb": true,
      "brandUid": "text",
      "brandName": "text",
      "calculationFactor": 1,
      "categoryUids": [
        "text"
      ],
      "createdAt": "2025-06-30T20:26:17.613Z",
      "customerAgeRestriction": 1,
      "description": "text",
      "discontinuedFrom": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "externalInfo": "text",
      "externalUrl": "text",
      "gtins": [
        {
          "gtin": "text",
          "primary": true,
          "type": "text"
        }
      ],
      "height": 1,
      "internalInfo": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "ledgerNumber": "text",
      "length": 1,
      "name": "text",
      "optionProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "priceOverride": true,
      "productGroupUid": "text",
      "productGroupPath": [
        {
          "name": "text",
          "parentUid": "text",
          "productGroupUid": "text"
        }
      ],
      "productUid": "text",
      "productType": "STOCK",
      "recommendedRetailPrice": 1,
      "requiredVariantPropertyUids": [
        "text"
      ],
      "serialNoRequired": "NO",
      "shortDescription": "text",
      "sku": "text",
      "manufacturerSku": "text",
      "suppliers": [
        {
          "name": "text",
          "supplierUid": "text"
        }
      ],
      "textProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "unitLabel": "text",
      "variantProductUids": [
        "text"
      ],
      "variantParentProductUid": "text",
      "vatCodeUid": "text",
      "weight": 1,
      "width": 1,
      "links": [
        {
          "productLinkUid": "text",
          "linkType": "INSURANCE",
          "productUid": "text"
        }
      ],
      "parents": [
        {
          "productLinkUid": "text",
          "linkType": "INSURANCE",
          "productUid": "text"
        }
      ],
      "requirements": {
        "requireCustomer": true,
        "requireCustomerMobile": true,
        "requireCustomerEmail": true,
        "requireCustomerDeliveryAddress": true
      },
      "coverImage": {
        "productMediaUid": "text",
        "mainUrl": "text",
        "thumbnailUrl": "text"
      },
      "imageCount": 1,
      "relevance": 1,
      "visibility": "ALWAYS_VISIBLE",
      "commission": 1,
      "productWarrantyUid": "text",
      "excludeFromStatistics": true,
      "purchasePrice": 1,
      "numberOfPieces": 1,
      "limitToStoreUids": [
        "text"
      ]
    }
  ]
}

Update category

put

Update a category

Required permission: TENANT.BACKOFFICE

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
categoryUidstringRequired

Reference to a Category.

Pattern: ^[A-Za-z0-9-_]+
Body
externalIdstringOptional
namestringRequired
parentUidstringOptionalPattern: ^[A-Za-z0-9-_]*
productUidsstring[]Optional
Responses
200
Example response
application/json
put
PUT /v2/tenants/{tenantUid}/categories/{categoryUid} HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "externalId": "text",
  "name": "text",
  "parentUid": "text",
  "productUids": [
    "text"
  ]
}
200

Example response

{
  "categories": [
    {
      "categoryUid": "text",
      "createdAt": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "name": "text"
    }
  ],
  "categoryUid": "text",
  "createdAt": "2025-06-30T20:26:17.613Z",
  "externalId": "text",
  "lastModifiedAt": "2025-06-30T20:26:17.613Z",
  "name": "text",
  "parentUid": "text",
  "products": [
    {
      "storeProductDetails": {
        "grossProfitAmount": 1,
        "grossProfitPercentage": 1,
        "costPrice": 1,
        "price": 1,
        "campaignPrice": 1,
        "campaignName": "text",
        "quantityReserved": 1,
        "quantityStock": 1,
        "quantityOrdered": 1
      },
      "allowAddon": true,
      "allowCredit": true,
      "allowPurchase": true,
      "allowQuantity": true,
      "allowSale": "YES",
      "allowSaleDate": "2025-06-30T20:26:17.613Z",
      "allowDelivery": "YES",
      "allowDeliveryDate": "2025-06-30T20:26:17.613Z",
      "availableForWeb": true,
      "brandUid": "text",
      "brandName": "text",
      "calculationFactor": 1,
      "categoryUids": [
        "text"
      ],
      "createdAt": "2025-06-30T20:26:17.613Z",
      "customerAgeRestriction": 1,
      "description": "text",
      "discontinuedFrom": "2025-06-30T20:26:17.613Z",
      "externalId": "text",
      "externalInfo": "text",
      "externalUrl": "text",
      "gtins": [
        {
          "gtin": "text",
          "primary": true,
          "type": "text"
        }
      ],
      "height": 1,
      "internalInfo": "text",
      "lastModifiedAt": "2025-06-30T20:26:17.613Z",
      "ledgerNumber": "text",
      "length": 1,
      "name": "text",
      "optionProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "priceOverride": true,
      "productGroupUid": "text",
      "productGroupPath": [
        {
          "name": "text",
          "parentUid": "text",
          "productGroupUid": "text"
        }
      ],
      "productUid": "text",
      "productType": "STOCK",
      "recommendedRetailPrice": 1,
      "requiredVariantPropertyUids": [
        "text"
      ],
      "serialNoRequired": "NO",
      "shortDescription": "text",
      "sku": "text",
      "manufacturerSku": "text",
      "suppliers": [
        {
          "name": "text",
          "supplierUid": "text"
        }
      ],
      "textProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "unitLabel": "text",
      "variantProductUids": [
        "text"
      ],
      "variantParentProductUid": "text",
      "vatCodeUid": "text",
      "weight": 1,
      "width": 1,
      "links": [
        {
          "productLinkUid": "text",
          "linkType": "INSURANCE",
          "productUid": "text"
        }
      ],
      "parents": [
        {
          "productLinkUid": "text",
          "linkType": "INSURANCE",
          "productUid": "text"
        }
      ],
      "requirements": {
        "requireCustomer": true,
        "requireCustomerMobile": true,
        "requireCustomerEmail": true,
        "requireCustomerDeliveryAddress": true
      },
      "coverImage": {
        "productMediaUid": "text",
        "mainUrl": "text",
        "thumbnailUrl": "text"
      },
      "imageCount": 1,
      "relevance": 1,
      "visibility": "ALWAYS_VISIBLE",
      "commission": 1,
      "productWarrantyUid": "text",
      "excludeFromStatistics": true,
      "purchasePrice": 1,
      "numberOfPieces": 1,
      "limitToStoreUids": [
        "text"
      ]
    }
  ]
}

Delete a category

delete

This will delete a category and all its sub-categories.

Required permission: TENANT.BACKOFFICE

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
categoryUidstringRequired

Reference to a Category.

Pattern: ^[A-Za-z0-9-_]+
Responses
204
No Content
delete
DELETE /v2/tenants/{tenantUid}/categories/{categoryUid} HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
204

No Content

No content
PreviousCampaignNextCompensation

Was this helpful?