Categories

Where categories are used#

On a product or bundle, a present category_handles array replaces the whole set, [] clears it, and the change doesn't need expected_version. Handles must match exactly. A handle that no category has returns 404 RESOURCE_NOT_FOUND with param naming the entry, such as category_handles[2], and details[0].resource_type set to category. Nothing is saved.

Handles and names#

The handle is the category's permanent key, and the name is its label.

• handle has 1 to 100 lowercase letters and digits, with single hyphens between words, such as espresso-drinks. No two of your categories share one. It never changes, so store it in your code, rules, and filters.
• Omit handle on create and Flint derives it from name: letters are lowercased, accents are dropped, and each run of other characters becomes one hyphen, so Café & Bakery becomes cafe-bakery. A name with no Latin letters or digits, such as 茶, produces no handle, so send handle with it.
• name has 1 to 100 characters after Flint trims surrounding spaces, and the handle derived from it must also fit in 100 characters. Renaming with PATCH /v1/categories/{category_id} changes only name.
• Neither a name nor a handle can contain >.

To find the category that owns a handle, list with it: GET /v1/categories?handle=espresso-drinks returns that category as the only item in data, or an empty data when no category has the handle. The value must itself be a valid handle, so Espresso-Drinks returns 400 INVALID_REQUEST instead of matching.

Category references on other resources#

Products, bundles, and order and invoice line items return categories as {category_id, handle, name} objects. Products and bundles always show the category's current name. Order line items keep the handle and name from when the order was created, and invoice line items keep them from when the line was billed.

Match a reference to its category by category_id, which never changes. A handle can outlive its category: after a delete, a new category can take the same handle with a new category_id.

Versions and conditional writes#

Every category has a version that starts at 1 and increases with each change to it. Updates increase it, and so do changes to what uses it: assigning or removing a product or bundle, and a promotion, return reason, or return policy starting or stopping to reference it. The categories references on other resources carry no version.

Redeeming a promotion or releasing its reserved use does not change the category's version or targeting_reference_count. A promotion reaching its end time or use limit does not change the count either.

PATCH changes only the fields you send. To refuse the write if the category changed since you read it, send the version you read as expected_version: in the body on PATCH, or as a query parameter on DELETE. Without it, concurrent updates are applied one after the other.

curl -X PATCH https://api.withflintpay.com/v1/categories/ctg_01J00000000000000000000000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expected_version": 4, "name": "Espresso and tea" }'

{
  "data": {
    "assigned_bundle_count": 1,
    "assigned_product_count": 6,
    "category_id": "ctg_01J00000000000000000000000",
    "created_at": "2026-03-17T14:30:00Z",
    "handle": "espresso-drinks",
    "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
    "name": "Espresso and tea",
    "status": "active",
    "targeting_reference_count": 1,
    "updated_at": "2026-03-19T09:12:00Z",
    "version": 5
  },
  "request_id": "req_01KWM615AGC7G311TCBK6QE1Q8"
}

The handle stays espresso-drinks after the rename, so every product, filter, and rule that uses it keeps working.

Status and deletion#

Delete permanently removes a category that nothing uses, such as one created by mistake. assigned_product_count and assigned_bundle_count show how many products and bundles still carry it. targeting_reference_count counts promotions, return reasons, and return policies whose revisions reference it, including historical revisions. Promotions still count after they end or use up their limit; deleted promotions don't count. Each referencing resource counts once, even if several rules or revisions reference the category.

All three counts must be zero before you can delete the category. If any is above zero, the request returns 409 RESOURCE_IN_USE, and details[0].blocking_resources lists up to 25 referencing resources, with the total in blocking_resource_count. Publishing a new return policy revision without the category does not remove a historical revision's reference, so that category still cannot be deleted.

Errors to handle#

Webhook events#

A rename sends only category.updated, even though categories[].name changes on every product and bundle that carries the category. Assigning or removing a product or bundle changes the category's counts and version without a category event. Keep another system in sync covers mirroring categories and backfilling them from the lists, and the catalog events list every copied field that changes without its own event.