> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List brands

> List all customer-facing brands for the merchant.

Returns every active brand configured for the merchant. Use this endpoint to build brand pickers or to load brand metadata before filtering with `brand_id`.

<Note>
  Requires a Fire spark access token obtained through [token
  exchange](/docs/storefront-api/oauth/exchange/post). The token scopes requests to the
  authenticated customer and merchant.
</Note>

## Request

```bash theme={null}
curl "https://firespark.cloud/api/storefront/v1/brands" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Response

The response wraps an array of brand objects in `data`. Only `ACTIVE` brands are included.

<ResponseExample>
  ```json Success theme={null}
  {
    "data": [
      {
        "id": "0001",
        "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organization_id": "11111111-1111-1111-1111-111111111111",
        "merchant_id": "22222222-2222-2222-2222-222222222222",
        "name": "Burger Co.",
        "status": "ACTIVE",
        "cms_template_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
        "cms": {
          "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
          "name": "Brand landing page",
          "entity": "BRANDS",
          "status": "ACTIVE",
          "fields": [
            {
              "name": "tagline",
              "type": "TEXT",
              "label": { "en_us": "Tagline" },
              "required": false,
              "value": "Flame-grilled since 1987"
            }
          ]
        }
      },
      {
        "id": "0002",
        "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "organization_id": "11111111-1111-1111-1111-111111111111",
        "merchant_id": "22222222-2222-2222-2222-222222222222",
        "name": "Taco Co.",
        "status": "ACTIVE",
        "cms_template_id": null,
        "cms": null
      }
    ]
  }
  ```
</ResponseExample>

## Brand object

| Field             | Type          | Description                                                                                                                                              |
| ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string        | External brand identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. Use this value in `brand_id` when filtering stores and channels. |
| `uid`             | string (UUID) | Fire spark internal identifier.                                                                                                                          |
| `organization_id` | string (UUID) | Fire spark organization identifier.                                                                                                                      |
| `merchant_id`     | string (UUID) | Fire spark merchant identifier.                                                                                                                          |
| `name`            | string        | Display name. 1–100 characters.                                                                                                                          |
| `status`          | string        | `ACTIVE` or `INACTIVE`.                                                                                                                                  |
| `cms_template_id` | string (UUID) | CMS template linked to this brand. `null` when no template is assigned.                                                                                  |
| `cms`             | object        | Read-only. `null` when `cms_template_id` is `null`. When set, the resolved CMS template for this brand, including field definitions and stored values.   |

<AccordionGroup>
  <Accordion title="cms">
    Present only when `cms_template_id` is not `null`. Contains the resolved CMS template assigned to the brand.

    | Field    | Required | Type          | Description                                       |
    | -------- | -------- | ------------- | ------------------------------------------------- |
    | `id`     | Yes      | string (UUID) | Template identifier. Matches `cms_template_id`.   |
    | `name`   | Yes      | string        | Template name. 1–100 characters.                  |
    | `entity` | Yes      | string        | Always `BRANDS` for brand responses.              |
    | `status` | Yes      | string        | `ACTIVE` or `INACTIVE`.                           |
    | `fields` | Yes      | array         | Template fields with their current stored values. |

    Each field in `fields`:

    | Field         | Required | Type    | Description                                              |
    | ------------- | -------- | ------- | -------------------------------------------------------- |
    | `name`        | Yes      | string  | Field key.                                               |
    | `type`        | Yes      | string  | `TEXT`, `SELECT`, `IMAGE`, or `LIST`.                    |
    | `label`       | No       | object  | Optional localized label keyed by locale.                |
    | `required`    | No       | boolean | Whether the field is required.                           |
    | `placeholder` | No       | string  | Optional placeholder text.                               |
    | `options`     | No       | array   | For `SELECT` fields — objects with `label` and `value`.  |
    | `altText`     | No       | string  | For `IMAGE` fields — alternative text.                   |
    | `src`         | No       | string  | For `IMAGE` fields — image URL.                          |
    | `href`        | No       | string  | For `IMAGE` fields — optional link URL.                  |
    | `value`       | No       | varies  | Current stored value for this brand. Omitted when empty. |
  </Accordion>
</AccordionGroup>

## Error responses

| Status | Description                                           |
| ------ | ----------------------------------------------------- |
| `401`  | Missing or invalid access token.                      |
| `403`  | Token does not have access to this merchant's brands. |


## OpenAPI

````yaml GET /brands
openapi: 3.0.1
info:
  title: Fire spark Integrations API
  description: POS and RMS integration endpoints for Fire spark.
  version: 1.0.0
servers:
  - url: https://firespark.cloud/api/integrations/v1
security:
  - bearerAuth: []
paths:
  /brands:
    get:
      summary: List brands
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrandRead'
components:
  schemas:
    BrandRead:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
        uid:
          type: string
          format: uuid
        organization_id:
          type: string
          format: uuid
        merchant_id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
        cms_template_id:
          type: string
          format: uuid
          nullable: true
        cms:
          type: object
          nullable: true
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````