API reference

Brand Assets and Verification API

Upload brand images, check configured links and test domain-linked email identity.

Start with getting started Explore API docs

Upload the correct asset variant

Use logo, light-logo, dark-logo, icon or default-product-image with one multipart file. JPEG, PNG, WebP and GIF are supported; SVG is rejected. The default image limit is 10 MiB and the configured upload policy remains authoritative. These are public assets: never upload private customer or credential screenshots.

draft=1 returns url, key and draft:true without changing saved branding. Without it the selected brand field is updated and the response includes branding. Uploading a draft is still a storage side effect; it is not a privacy-safe temporary vault. Brand changes require brand.manage and all-products scope.

Separate identity from delivery readiness

links/validate reports whether required brand links are configured. It does not crawl external sites or guarantee their HTTP availability. Missing optional links can still pass.

test-email accepts email or to and sends a real branded notifications email to that address. It requires configured email transport and does not create a marketing campaign, enroll a contact or prove DNS verification. Keep test recipients under your control.

Choose the right domain workflow

verify-domain refreshes the current website domain. verify-email-domain refreshes the first returned sending domain. These compatible Brand Manager actions synchronize the resulting branding state; they are not a replacement for the guided domain setup workflow.

The website-specific storefront-domain API also exposes the current domain, DNS/SSL and routing readiness, creation and explicit refresh by domain ID. Reads may verify legacy records with missing checks. Inspect individual checks and settings.ready, not only a saved verified flag. Website SSL and sending-domain authentication are different checks.

SoundSync

Brand and domain guides

Brand Manager

Identity, visual variants and shared values.

Explore

Domain API

Guided setup plus website-specific readiness calls.

Explore

Sending domains

Email authentication and sender profiles.

Explore

SoundSync

Requests and responses

POST /api/developer/branding/logo

Upload the brand logo

Auth: Account Bearer JWT
Scope: brand.manage and all-products scope.
Request fields: query draft: string
file: string (required)
Returns: HTTP 201: url, key, draft, branding.
Notes: Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.

Request, response and error reference

Query and header parameters

[
  {
    "name": "draft",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "1"
      ]
    },
    "required": false,
    "description": ""
  }
]

Request (multipart/form-data)

{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  },
  "required": [
    "file"
  ],
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "draft": {
      "type": "boolean"
    },
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 413, 415, 500, 503.

POST /api/developer/branding/light-logo

Upload the brand light-logo

Auth: Account Bearer JWT
Scope: brand.manage and all-products scope.
Request fields: query draft: string
file: string (required)
Returns: HTTP 201: url, key, draft, branding.
Notes: Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.

Request, response and error reference

Query and header parameters

[
  {
    "name": "draft",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "1"
      ]
    },
    "required": false,
    "description": ""
  }
]

Request (multipart/form-data)

{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  },
  "required": [
    "file"
  ],
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "draft": {
      "type": "boolean"
    },
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 413, 415, 500, 503.

POST /api/developer/branding/dark-logo

Upload the brand dark-logo

Auth: Account Bearer JWT
Scope: brand.manage and all-products scope.
Request fields: query draft: string
file: string (required)
Returns: HTTP 201: url, key, draft, branding.
Notes: Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.

Request, response and error reference

Query and header parameters

[
  {
    "name": "draft",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "1"
      ]
    },
    "required": false,
    "description": ""
  }
]

Request (multipart/form-data)

{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  },
  "required": [
    "file"
  ],
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "draft": {
      "type": "boolean"
    },
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 413, 415, 500, 503.

POST /api/developer/branding/icon

Upload the brand icon

Auth: Account Bearer JWT
Scope: brand.manage and all-products scope.
Request fields: query draft: string
file: string (required)
Returns: HTTP 201: url, key, draft, branding.
Notes: Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.

Request, response and error reference

Query and header parameters

[
  {
    "name": "draft",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "1"
      ]
    },
    "required": false,
    "description": ""
  }
]

Request (multipart/form-data)

{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  },
  "required": [
    "file"
  ],
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "draft": {
      "type": "boolean"
    },
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 413, 415, 500, 503.

POST /api/developer/branding/default-product-image

Upload the brand default-product-image

Auth: Account Bearer JWT
Scope: brand.manage and all-products scope.
Request fields: query draft: string
file: string (required)
Returns: HTTP 201: url, key, draft, branding.
Notes: Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.

Request, response and error reference

Query and header parameters

[
  {
    "name": "draft",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "1"
      ]
    },
    "required": false,
    "description": ""
  }
]

Request (multipart/form-data)

{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  },
  "required": [
    "file"
  ],
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "draft": {
      "type": "boolean"
    },
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 413, 415, 500, 503.

POST /api/developer/branding/verify-domain

Refresh the connected storefront domain

Auth: Account Bearer JWT
Scope: domains.manage and all-products scope.
Returns: HTTP 200: branding, publicBranding, storefrontDomainResult.
Notes: Compatibility refresh workflow for the connected storefront domain. Website refresh selects the current website domain; email refresh selects the first returned sending domain. Prefer the guided domain API for explicit setup progress. Performs external checks and synchronizes branding. HTTP 200 does not mean DNS/SSL or email authentication is ready.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "publicBranding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "storefrontDomainResult": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500.

POST /api/developer/branding/verify-email-domain

Refresh the connected sending domain

Auth: Account Bearer JWT
Scope: domains.manage and all-products scope.
Returns: HTTP 200: branding, publicBranding, emailDomainResult.
Notes: Compatibility refresh workflow for the connected sending domain. Website refresh selects the current website domain; email refresh selects the first returned sending domain. Prefer the guided domain API for explicit setup progress. Performs external checks and synchronizes branding. HTTP 200 does not mean DNS/SSL or email authentication is ready.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "branding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "publicBranding": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "emailDomainResult": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500.

POST /api/developer/branding/test-email

Send a branded transactional-email test

Auth: Account Bearer JWT
Scope: brand.manage and all-products scope.
Request fields: email: string
to: string
Returns: HTTP 200: ok, email.
Notes: Send email or to. Actually sends to that address using the resolved notifications sender; it is not a marketing campaign, subscription or proof of domain readiness. Requires configured email transport; success does not guarantee inbox delivery.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "to": {
      "type": "string",
      "format": "email"
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 500, 503.

GET /api/developer/branding/links/validate

Inspect configured branding links

Auth: Account Bearer JWT
Scope: brand.view.
Returns: HTTP 200: ok, checks.
Notes: Checks required configured values, not remote HTTP availability. Optional missing values can still report ok:true. It is not proof that every external page is reachable.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          },
          "ok": {
            "type": "boolean"
          },
          "required": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500.