List brands · Ownrecord docs

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
`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`	400	A filter or pagination value is malformed.	Fix the fields listed in `details.issues` and send the request again.
`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`	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: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

Every brand of one entity#

Errors#