# List brands > The brands.list operation: GET /api/v1/brands in the REST API and the brands_list tool in the MCP server. Lists brands, newest first. What a request sees depends on its scope: an organization-level request every brand of every entity (filter with `entityId`), a request inside one entity all of that entity's brands, and a request inside one brand only that brand. Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/brands` - **MCP tool:** `brands_list` - **Operation ID:** `brands.list` - **Scope:** Organization, or one of its legal entities or brands - **Permission:** `brands:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `brands:read` scope - **Since:** M1 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ------------------ | -------- | ----------- | | `entityId` | `ent_…` ID | No | | | `limit` | integer (1 to 100) | No | | | `starting_after` | `brd_…` ID | No | | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `brd_…` ID | | | `data[].object` | `"brand"` | | | `data[].orgId` | `org_…` ID | | | `data[].entityId` | `ent_…` ID | | | `data[].slug` | string | | | `data[].name` | string | | | `data[].status` | one of `draft`, `test_only`, `live`, `suspended` | | | `data[].isPlatformBrand` | boolean | | | `data[].branding` | object | | | `data[].branding.logoUrl` | string or null | | | `data[].branding.iconUrl` | string or null | | | `data[].branding.primaryColor` | string or null | | | `data[].branding.accentColor` | string or null | | | `data[].branding.supportEmail` | string or null | | | `data[].branding.supportUrl` | string or null | | | `data[].branding.termsUrl` | string or null | | | `data[].branding.privacyUrl` | string or null | | | `data[].statementDescriptor` | string | | | `data[].statementDescriptorSuffix` | string or null | | | `data[].invoiceSeries` | object | | | `data[].invoiceSeries.invoice` | string | | | `data[].invoiceSeries.creditNote` | string | | | `data[].billingSettings` | object | | | `data[].billingSettings.dunning` | object | | | `data[].billingSettings.dunning.retryOffsetsDays` | array of integer | | | `data[].billingSettings.dunning.finalAction` | one of `unpaid`, `canceled` | | | `data[].billingSettings.entitlementGraceDays` | integer | | | `data[].billingSettings.sendInvoice` | object | | | `data[].billingSettings.sendInvoice.graceDays` | integer | | | `data[].billingSettings.cardExpiryReminders` | boolean | | | `data[].billingSettings.pausedEntitlements` | boolean | | | `data[].billingSettings.paymentBehavior` | one of `allow_incomplete`, `pending_if_incomplete` | | | `data[].policies` | object | | | `data[].policies.breakageRecognition` | one of `at_expiry`, `manual` | `at_expiry` (the default) or `manual` (held as expired credits until recognised). | | `data[].policies.supportRefundLimits` | array of object | The support role's refund limit per currency (M8); a currency not listed has the default of 100 of it. | | `data[].policies.supportRefundLimits[].amount` | string | Integer micros as a string. | | `data[].policies.supportRefundLimits[].currency` | string | | | `data[].policies.disputeWalletFreeze` | boolean | Freeze the customer's wallets when a dispute opens (default true; §19.2, M8). | | `data[].policies.taxIdUnavailable` | one of `charge_as_b2c`, `block` | What a sale does when a tax ID couldn't be checked (§9.1 step 1; M13): `charge_as_b2c` (the default) or `block`. | | `data[].portalSettings` | object | | | `data[].portalSettings.allowPlanChanges` | boolean | Customers may switch plans along `planChangeMatrix` (no row: no switch). | | `data[].portalSettings.planChangeMatrix` | array of object | One row per price: a subscription item on `fromPriceId` may switch to any of `toPriceIds` (same mode and currency). | | `data[].portalSettings.planChangeMatrix[].fromPriceId` | `price_…` ID | | | `data[].portalSettings.planChangeMatrix[].toPriceIds` | array of `price_…` ID | | | `data[].portalSettings.allowCancel` | boolean | Customers may cancel their subscriptions. | | `data[].portalSettings.cancelBehavior` | one of `period_end`, `immediate` | A portal cancellation ends the subscription at the period end (default) or at once. | | `data[].portalSettings.collectCancelReason` | boolean | The portal asks why the customer cancels. | | `data[].portalSettings.allowQuantityChanges` | boolean | Customers may change the quantity (seats) of licensed items. | | `data[].checkoutSettings` | object | | | `data[].checkoutSettings.locales` | array of string | The brand's languages, its default first. A default, not a restriction: a customer's own language comes first. | | `data[].checkoutSettings.collectPhone` | boolean | | | `data[].checkoutSettings.requireBusinessDetails` | one of `auto`, `always`, `never` | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `brd_…` ID or null | | ## Examples ### Every brand of one entity ```http GET /api/v1/brands?entityId=ent_01m4tx5nj8emwbyf7y9vcf47x2 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "brd_01m4tx5nj8emwbyf7y9vcf47x5", "object": "brand", "orgId": "org_01m4tx5nj7ekd958x53w4bntcg", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "slug": "acme-labs", "name": "Acme Labs", "status": "test_only", "isPlatformBrand": false, "branding": { "logoUrl": null, "iconUrl": null, "primaryColor": null, "accentColor": null, "supportEmail": null, "supportUrl": null, "termsUrl": null, "privacyUrl": null }, "statementDescriptor": "ACME APP", "statementDescriptorSuffix": null, "invoiceSeries": { "invoice": "LAB", "creditNote": "LAB-CN" }, "billingSettings": { "dunning": { "retryOffsetsDays": [1, 3, 5, 7], "finalAction": "unpaid" }, "entitlementGraceDays": 7, "sendInvoice": { "graceDays": 14 }, "cardExpiryReminders": true, "pausedEntitlements": false, "paymentBehavior": "allow_incomplete" }, "policies": { "breakageRecognition": "at_expiry", "supportRefundLimits": [], "disputeWalletFreeze": true, "taxIdUnavailable": "charge_as_b2c" }, "portalSettings": { "allowPlanChanges": true, "planChangeMatrix": [], "allowCancel": true, "cancelBehavior": "period_end", "collectCancelReason": true, "allowQuantityChanges": false }, "checkoutSettings": { "locales": ["en", "hr"], "collectPhone": false, "requireBusinessDetails": "auto" }, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" }, { "id": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "object": "brand", "orgId": "org_01m4tx5nj7ekd958x53w4bntcg", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "slug": "acme-app", "name": "Acme App", "status": "test_only", "isPlatformBrand": false, "branding": { "logoUrl": null, "iconUrl": null, "primaryColor": null, "accentColor": null, "supportEmail": null, "supportUrl": null, "termsUrl": null, "privacyUrl": null }, "statementDescriptor": "ACME APP", "statementDescriptorSuffix": null, "invoiceSeries": { "invoice": "ACM", "creditNote": "ACM-CN" }, "billingSettings": { "dunning": { "retryOffsetsDays": [1, 3, 5, 7], "finalAction": "unpaid" }, "entitlementGraceDays": 7, "sendInvoice": { "graceDays": 14 }, "cardExpiryReminders": true, "pausedEntitlements": false, "paymentBehavior": "allow_incomplete" }, "policies": { "breakageRecognition": "at_expiry", "supportRefundLimits": [], "disputeWalletFreeze": true, "taxIdUnavailable": "charge_as_b2c" }, "portalSettings": { "allowPlanChanges": true, "planChangeMatrix": [], "allowCancel": true, "cancelBehavior": "period_end", "collectCancelReason": true, "allowQuantityChanges": false }, "checkoutSettings": { "locales": ["en", "hr"], "collectPhone": false, "requireBusinessDetails": "auto" }, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" } ], "has_more": false, "next_cursor": null } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is malformed. | Fix the fields listed in `details.issues` and send the request again. | | [`scope_mismatch`](https://ownrecord.io/docs/reference/errors.md#scope_mismatch) | 403 | `entityId` names an entity outside the request's scope. | Use credentials scoped to that organization, entity or brand, or leave the scope fields out of the request. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't see brands here. | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).