Branding

Base URL: $BUSINESS_API

The object

namestring · required
short_namestring · required
legal_namestring · required
copyrightstring · required

Who the copyright line names (© <year> <copyright>). Empty means the legal name; when both are empty, clients show no copyright line rather than assume the product name.

supportobject · required
Show child attributes
emailstring · required
phonestring · required
urlstring · required
linksobject · required
Show child attributes
websitestring · required
termsstring · required
privacystring · required
colorsobject · required
Show child attributes
brandstring · required
brand_foregroundstring · required
accentstring · required
logo_urlstring · required · nullable

Absolute path with a v hash, such as $PUBLIC_API/branding/assets/logo?v=…; null when unset

logo_dark_urlstring · required · nullable
icon_urlstring · required · nullable
updated_atstring (date-time) · required
receipt_footerstring · required
tenantobject · required
Show child attributes
idstring · required
slugstring · required
platformobject · required
Show child attributes
namestring · required
short_namestring · required
icon_urlstring · required · nullable
sourcesobject · required

The platform source keys plus receipt_footer.

The object
{
  "sources": {
    "key": "custom"
  },
  "colors": {
    "brand": "brand",
    "brand_foreground": "brand foreground",
    "accent": "accent"
  },
  "copyright": "copyright",
  "icon_url": "https://example.org/",
  "legal_name": "Ana Matsinhe",
  "links": {
    "website": "website",
    "terms": "terms",
    "privacy": "privacy"
  },
  "logo_dark_url": "https://example.org/",
  "logo_url": "https://example.org/",
  "name": "Ana Matsinhe",
  "platform": {
    "name": "Ana Matsinhe",
    "short_name": "Ana Matsinhe",
    "icon_url": "https://example.org/"
  },
  "receipt_footer": "receipt footer",
  "short_name": "Ana Matsinhe",
  "support": {
    "email": "ana.matsinhe@example.org",
    "phone": "+258841234567",
    "url": "https://example.org/"
  },
  "tenant": {
    "id": "ten_2sYXpy6D7kQ3lIa31QONH8u59Ia",
    "slug": "slug"
  },
  "updated_at": "2026-11-19T09:30:00Z"
}

Get business branding

Logs

GET /branding

The utility's effective brand and where each value comes from

Requires business:branding:read (utility owner and admin).

Returns

200 Utility brand with sources

Show attributes
namestring · required
short_namestring · required
legal_namestring · required
copyrightstring · required

Who the copyright line names (© <year> <copyright>). Empty means the legal name; when both are empty, clients show no copyright line rather than assume the product name.

supportobject · required
Show child attributes
emailstring · required
phonestring · required
urlstring · required
linksobject · required
Show child attributes
websitestring · required
termsstring · required
privacystring · required
colorsobject · required
Show child attributes
brandstring · required
brand_foregroundstring · required
accentstring · required
logo_urlstring · required · nullable

Absolute path with a v hash, such as $PUBLIC_API/branding/assets/logo?v=…; null when unset

logo_dark_urlstring · required · nullable
icon_urlstring · required · nullable
updated_atstring (date-time) · required
receipt_footerstring · required
tenantobject · required
Show child attributes
idstring · required
slugstring · required
platformobject · required
Show child attributes
namestring · required
short_namestring · required
icon_urlstring · required · nullable
sourcesobject · required

The platform source keys plus receipt_footer.

Errors 403

Permissions business:branding:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/branding" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "sources": {
    "key": "custom"
  },
  "colors": {
    "brand": "brand",
    "brand_foreground": "brand foreground",
    "accent": "accent"
  },
  "copyright": "copyright",
  "icon_url": "https://example.org/",
  "legal_name": "Ana Matsinhe",
  "links": {
    "website": "website",
    "terms": "terms",
    "privacy": "privacy"
  },
  "logo_dark_url": "https://example.org/",
  "logo_url": "https://example.org/",
  "name": "Ana Matsinhe",
  "platform": {
    "name": "Ana Matsinhe",
    "short_name": "Ana Matsinhe",
    "icon_url": "https://example.org/"
  },
  "receipt_footer": "receipt footer",
  "short_name": "Ana Matsinhe",
  "support": {
    "email": "ana.matsinhe@example.org",
    "phone": "+258841234567",
    "url": "https://example.org/"
  },
  "tenant": {
    "id": "ten_2sYXpy6D7kQ3lIa31QONH8u59Ia",
    "slug": "slug"
  },
  "updated_at": "2026-11-19T09:30:00Z"
}

Change the utility's brand

Logs

PATCH /branding

Requires business:branding:write. The platform PATCH body plus receipt_footer; null resets a field to the next level down (configuration, business profile, platform). Audited as branding.updated.

Body application/json

namestring · optional · nullable
short_namestring · optional · nullable
legal_namestring · optional · nullable
copyrightstring · optional · nullable

Who the copyright line names; empty uses the legal name.

support_emailstring · optional · nullable
support_phonestring · optional · nullable
support_urlstring · optional · nullable
website_urlstring · optional · nullable
terms_urlstring · optional · nullable
privacy_urlstring · optional · nullable
colorsobject · optional · nullable
Show child attributes
brandstring · optional · nullable
brand_foregroundstring · optional · nullable
accentstring · optional · nullable
receipt_footerstring · optional · nullable

Returns

200 Updated utility brand

Show attributes
namestring · required
short_namestring · required
legal_namestring · required
copyrightstring · required

Who the copyright line names (© <year> <copyright>). Empty means the legal name; when both are empty, clients show no copyright line rather than assume the product name.

supportobject · required
Show child attributes
emailstring · required
phonestring · required
urlstring · required
linksobject · required
Show child attributes
websitestring · required
termsstring · required
privacystring · required
colorsobject · required
Show child attributes
brandstring · required
brand_foregroundstring · required
accentstring · required
logo_urlstring · required · nullable

Absolute path with a v hash, such as $PUBLIC_API/branding/assets/logo?v=…; null when unset

logo_dark_urlstring · required · nullable
icon_urlstring · required · nullable
updated_atstring (date-time) · required
receipt_footerstring · required
tenantobject · required
Show child attributes
idstring · required
slugstring · required
platformobject · required
Show child attributes
namestring · required
short_namestring · required
icon_urlstring · required · nullable
sourcesobject · required

The platform source keys plus receipt_footer.

Errors 400 · 403

Permissions business:branding:write · Roles: admin, owner

curl -X PATCH "$BUSINESS_API/branding" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "short_name": "Ana Matsinhe",
  "legal_name": "Ana Matsinhe",
  "copyright": "copyright",
  "support_email": "ana.matsinhe@example.org",
  "support_phone": "+258841234567",
  "support_url": "https://example.org/",
  "website_url": "https://example.org/",
  "terms_url": "https://example.org/",
  "privacy_url": "https://example.org/",
  "colors": {
    "brand": "brand",
    "brand_foreground": "brand foreground",
    "accent": "accent"
  },
  "receipt_footer": "receipt footer"
}'
Response 200
{
  "sources": {
    "key": "custom"
  },
  "colors": {
    "brand": "brand",
    "brand_foreground": "brand foreground",
    "accent": "accent"
  },
  "copyright": "copyright",
  "icon_url": "https://example.org/",
  "legal_name": "Ana Matsinhe",
  "links": {
    "website": "website",
    "terms": "terms",
    "privacy": "privacy"
  },
  "logo_dark_url": "https://example.org/",
  "logo_url": "https://example.org/",
  "name": "Ana Matsinhe",
  "platform": {
    "name": "Ana Matsinhe",
    "short_name": "Ana Matsinhe",
    "icon_url": "https://example.org/"
  },
  "receipt_footer": "receipt footer",
  "short_name": "Ana Matsinhe",
  "support": {
    "email": "ana.matsinhe@example.org",
    "phone": "+258841234567",
    "url": "https://example.org/"
  },
  "tenant": {
    "id": "ten_2sYXpy6D7kQ3lIa31QONH8u59Ia",
    "slug": "slug"
  },
  "updated_at": "2026-11-19T09:30:00Z"
}

Upload a utility brand file

Logs

PUT /branding/assets/{kind}

Requires business:branding:write. Same types, size cap and SVG sanitising as the platform upload. Audited as branding.asset_uploaded.

Parameters

kindstring · path · required

Which brand file to replace: logo, logo_dark or icon; any other value answers 404.

one of logo, logo_dark, icon

Returns

200 Updated utility brand

Show attributes
namestring · required
short_namestring · required
legal_namestring · required
copyrightstring · required

Who the copyright line names (© <year> <copyright>). Empty means the legal name; when both are empty, clients show no copyright line rather than assume the product name.

supportobject · required
Show child attributes
emailstring · required
phonestring · required
urlstring · required
linksobject · required
Show child attributes
websitestring · required
termsstring · required
privacystring · required
colorsobject · required
Show child attributes
brandstring · required
brand_foregroundstring · required
accentstring · required
logo_urlstring · required · nullable

Absolute path with a v hash, such as $PUBLIC_API/branding/assets/logo?v=…; null when unset

logo_dark_urlstring · required · nullable
icon_urlstring · required · nullable
updated_atstring (date-time) · required
receipt_footerstring · required
tenantobject · required
Show child attributes
idstring · required
slugstring · required
platformobject · required
Show child attributes
namestring · required
short_namestring · required
icon_urlstring · required · nullable
sourcesobject · required

The platform source keys plus receipt_footer.

Errors 400 · 403

Permissions business:branding:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/branding/assets/{kind}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "sources": {
    "key": "custom"
  },
  "colors": {
    "brand": "brand",
    "brand_foreground": "brand foreground",
    "accent": "accent"
  },
  "copyright": "copyright",
  "icon_url": "https://example.org/",
  "legal_name": "Ana Matsinhe",
  "links": {
    "website": "website",
    "terms": "terms",
    "privacy": "privacy"
  },
  "logo_dark_url": "https://example.org/",
  "logo_url": "https://example.org/",
  "name": "Ana Matsinhe",
  "platform": {
    "name": "Ana Matsinhe",
    "short_name": "Ana Matsinhe",
    "icon_url": "https://example.org/"
  },
  "receipt_footer": "receipt footer",
  "short_name": "Ana Matsinhe",
  "support": {
    "email": "ana.matsinhe@example.org",
    "phone": "+258841234567",
    "url": "https://example.org/"
  },
  "tenant": {
    "id": "ten_2sYXpy6D7kQ3lIa31QONH8u59Ia",
    "slug": "slug"
  },
  "updated_at": "2026-11-19T09:30:00Z"
}

Return a utility brand file to the next level down

Logs

DELETE /branding/assets/{kind}

Requires business:branding:write. Audited as branding.asset_removed.

Parameters

kindstring · path · required

Which brand file to remove: logo, logo_dark or icon; any other value answers 404.

one of logo, logo_dark, icon

Returns

200 Updated utility brand

Show attributes
namestring · required
short_namestring · required
legal_namestring · required
copyrightstring · required

Who the copyright line names (© <year> <copyright>). Empty means the legal name; when both are empty, clients show no copyright line rather than assume the product name.

supportobject · required
Show child attributes
emailstring · required
phonestring · required
urlstring · required
linksobject · required
Show child attributes
websitestring · required
termsstring · required
privacystring · required
colorsobject · required
Show child attributes
brandstring · required
brand_foregroundstring · required
accentstring · required
logo_urlstring · required · nullable

Absolute path with a v hash, such as $PUBLIC_API/branding/assets/logo?v=…; null when unset

logo_dark_urlstring · required · nullable
icon_urlstring · required · nullable
updated_atstring (date-time) · required
receipt_footerstring · required
tenantobject · required
Show child attributes
idstring · required
slugstring · required
platformobject · required
Show child attributes
namestring · required
short_namestring · required
icon_urlstring · required · nullable
sourcesobject · required

The platform source keys plus receipt_footer.

Errors 403

Permissions business:branding:write · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/branding/assets/{kind}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "sources": {
    "key": "custom"
  },
  "colors": {
    "brand": "brand",
    "brand_foreground": "brand foreground",
    "accent": "accent"
  },
  "copyright": "copyright",
  "icon_url": "https://example.org/",
  "legal_name": "Ana Matsinhe",
  "links": {
    "website": "website",
    "terms": "terms",
    "privacy": "privacy"
  },
  "logo_dark_url": "https://example.org/",
  "logo_url": "https://example.org/",
  "name": "Ana Matsinhe",
  "platform": {
    "name": "Ana Matsinhe",
    "short_name": "Ana Matsinhe",
    "icon_url": "https://example.org/"
  },
  "receipt_footer": "receipt footer",
  "short_name": "Ana Matsinhe",
  "support": {
    "email": "ana.matsinhe@example.org",
    "phone": "+258841234567",
    "url": "https://example.org/"
  },
  "tenant": {
    "id": "ten_2sYXpy6D7kQ3lIa31QONH8u59Ia",
    "slug": "slug"
  },
  "updated_at": "2026-11-19T09:30:00Z"
}