createCategoryTree

Create a full category taxonomy (tops + subs + sub-subs) in one call. - Wrapper-native synthetic tool. Creates member categories — top categories, their sub-categories, and third-tier sub-sub-categories — in one call.

Use when: creating a category at any level, including adding to a structure that already exists. Use createTopCategory or createSubCategory only for a single category that needs desc, keywords, icon, sort_order, lead_price, image, master_id, or a filename other than the default slug set at create time. For every other category create, use createCategoryTree.

Required: groups — an array of { top_category, sub_categories }, 25 entries maximum per call.

Send the whole taxonomy in one call. A top category named again is matched by name and reused, so a later call adds to it. Never issue two calls concurrently: a top category named in both is created twice, because BD's category list does not reflect a row written by a call still in flight. A second call is safe once the first call's response has returned.

The three shapes, all the same input:

• New top plus its subs: { top_category: "Surf Shops", sub_categories: ["Surfboards", "Wetsuits"] }

• Subs under a top that already exists: the same shape, naming that top. It is reused; only the listed subs are added, and existing subs are left alone.

• Top only: omit sub_categories or pass [].

Third tier — Parent=>Child: a sub_categories entry containing => creates Child under Parent, and Parent under the group's top_category. An existing Parent is reused. Exactly one => per entry: "Surf Camps=>Kids Camps". A=>B=>C is rejected — send A=>B in this call, then "B=>C" in a second call naming the same top_category once this call's response has returned.

Sub-category names must not contain commas — this tool writes them through BD's comma-separated services field, which would split one name into several. Replace the comma with a hyphen. To create the parts as separate categories instead, send each as its own sub_categories entry. One comma anywhere in sub_categories rejects the call. Top category names may contain commas.

Nothing is written until every name validates. Writing itself is not atomic: a failure part-way leaves earlier groups created. groups_completed and each group's top_status / sub_status name exactly what landed — read them before retrying. Re-send a group only when its top_status is error, or its sub_status is error or not attempted; created, existing, and none requested all mean that part landed.

Building sub-categories requires a temporary member, which this tool creates and deletes for you. temp_member reports what happened to it; the categories are unaffected either way.

See also: createTopCategory, createSubCategory, listTopCategories, listSubCategories.

Returns: { status, message: { groups_requested, groups_completed, sub_categories_created, temp_member, groups: [{ top_category, profession_id, top_status, sub_categories, sub_status }] } }. top_status is created, existing, or error. sub_status is created, error, none requested, or not attempted. sub_categories_created is the total across all groups — report it rather than counting names. temp_member is one of: temporary member deleted — cleanup succeeded; not needed (no sub-categories requested); no temporary member was created — no sub-category was written and every sub_status is error; or a user_id — sub-categories were written but cleanup failed, so pass that id to deleteUser. Each group carries the resolved profession_id, ready for updateUser.profession_id. Sub-category ids are not returned — read them with listSubCategories filtered on that profession_id before assigning members via updateUser.services or createMemberSubCategoryLink.