Get brand dependents

Many businesses run more than one brand out of one support team, for example a retailer with two storefronts. In Kustomer each of these is a brand. Admins manage brands in the admin settings, and other configuration hangs off them: chat settings (colors, greeting, business hours and assistant) are set per brand, each knowledge base belongs to a brand, and the web chat SDK takes a brandId to choose which brand's widget to load. Every org starts with one brand, created when the org is registered and marked default: true. Chat uses the default brand when it starts without a brandId.

Brand fields

A brand is small: name and iconUrl are the only fields you write, and both are required when you create or update one. default tells you whether it's the org's default brand. deleted and deletedAt say whether and when the brand was deleted.

Deleting a brand

DELETE /v1/brands/{id} is a soft delete. The brand is flagged deleted: true with a deletedAt time and kept, so conversations and reports that point to it can still resolve its name. It returns 204 with no body. It needs brand write permission or the brand delete permission. There's no way to restore a deleted brand, and PATCH on it returns 404.

Kustomer won't delete a brand that's still in use. Call GET /v1/brands/{id}/dependents first. It returns deletable with two lists: blockers, which says what's in the way, and unknown, which lists what couldn't be checked. These block a delete:

• Being the org's default brand. The default can never be deleted.
• Any knowledge base for the brand, published or not
• Any brand address mapping. Remove them with DELETE /v1/brandAddresses/brand/{brandId}.
• Chat settings with an active assistant, or an active assistant that's the default for a channel
• An enabled assistant rule, or an enabled rule that runs an AI automation, whose criteria name the brand

When the delete is refused you get 409 conflict with source.parameter set to id, and detail tells you which case it is:

detail	meta	What to do
Cannot delete the default brand	None	Nothing. The default brand can't be deleted.
Cannot delete a brand that has dependents	blockers lists what's in the way, and unknown lists any types that couldn't be checked	Remove or reassign each blocker, then try again
Cannot delete a brand while its dependents cannot be checked	blockers is empty, and unknown lists the types that couldn't be checked	Retry later

The check fails closed: if any dependent type can't be checked within a few seconds, the brand isn't deleted. It also isn't atomic with the delete, so something created at the same moment can be missed.

The other errors from the delete:

Status	When
400 badparam	id isn't a valid ID
401 unauthorized	The token is missing or invalid, or lacks org.admin.brand.write or org.permission.brand.delete. For a missing role, source.parameter is roles and detail lists the roles that would work.
404 notfound	No brand with this ID in your org, or it's already deleted
429 too_many_requests	Over the org or user rate limit. Brands have no limit of their own. Retry after x-ratelimit-reset.

After a delete:

• GET /v1/brands and GET /v1/brands/{id} leave the brand out, or return 404 for it by ID. Pass includeDeleted=true to get it back, for example to show the name of a deleted brand on old conversations. GET /v1/brands/default is unaffected, because the default can't be deleted.
• Existing conversations keep their brand ID and can still be updated. Creating a conversation with a deleted or unknown brand ID returns 400 badparam with detail set to Brand not found or deleted and source.parameter set to brand. See POST /v1/conversations.
• PATCH /v1/brands/{id} on the deleted brand returns 404, the same as for an ID that doesn't exist.
• Kustomer cleans up settings tied to the brand in the background, after the 204, and retries if a cleanup step fails. The cleanup starts from an event that's sent after the delete is saved, so in rare cases where that event can't be sent, the delete still succeeds but the cleanup doesn't run. PubNub keysets linked to the brand are unlinked from it and disabled. Brand-specific AI customization profiles (not the org default) are deleted with their tasks. A Shopify store whose storefront chat used the brand has its chat brand cleared, which turns the storefront chat widget off.

A 5xx from the delete doesn't always mean nothing happened: the brand can be deleted even though the response failed. Check with GET /v1/brands/{id}?includeDeleted=true before you retry, since deleting an already deleted brand returns 404.

Brand address mappings

A brand address mapping links an email address to a brand, so Kustomer knows which brand an address belongs to. One address can be mapped to several brands, and each brand can mark at most one of its mapped addresses with isDefault: true. Addresses are matched case-insensitively.

These endpoints behave differently from most write endpoints:

• POST /v1/brandAddresses is idempotent. Posting an address and brand pair that already exists returns the existing mapping with 200 instead of creating a duplicate. A new mapping returns 201.
• POST accepts an optional allBrands flag. When true, the address is shared across every brand, and Kustomer syncs the flag onto every mapping for that address. If you leave it out on create and another mapping for the same address is already shared, the new mapping inherits true.
• PATCH changes only isDefault and allBrands, and needs at least one of them. Setting isDefault to true moves the default from the brand's previous default address. Deleting the default mapping leaves the brand with no default; Kustomer doesn't promote another address automatically.
• Deleting all mappings for an address first checks whether the address is still connected to an email account in Kustomer. If it is, nothing is deleted and the response reports live: true. If Kustomer can't confirm either way, it deletes nothing and returns 503.

Which endpoint to use

To	Call
List brands, for example to find a brandId for chat	GET /v1/brands
Get the org's default brand	GET /v1/brands/default
Create, read or update a brand	POST /v1/brands, GET or PATCH /v1/brands/{id}
See what stops a brand from being deleted	GET /v1/brands/{id}/dependents
Delete a brand	DELETE /v1/brands/{id}
Include deleted brands in a read	includeDeleted=true on GET /v1/brands or GET /v1/brands/{id}
See which brands an email address is mapped to	GET /v1/brandAddresses, with address to look up one address
Map an address to a brand	POST /v1/brandAddresses
Make a mapped address the brand's default, or clear it	PATCH /v1/brandAddresses/{id}
Remove one mapping	DELETE /v1/brandAddresses/{id}
Remove every mapping for an address, or for a brand	DELETE /v1/brandAddresses/address/{address} or DELETE /v1/brandAddresses/brand/{brandId}

Brand reads, including the dependents check, are available to most users. Writing brands needs brand write permission, deleting one needs brand write or the brand delete permission, and brand address mappings use the apps permissions. A brand can have only one default address at a time, so if two requests try to set different defaults for the same brand at once, one of them can fail with 409 Conflict. Read the mappings again and retry.