Brands · Docs

A partner manages client brands. GET /v1/brands lists the ones its key reaches; act for one by sending its ID in Lucra-Account. A brand's own key gets an empty list.

Create a brand

A partner creates a brand with POST /v1/brands. It becomes an active client right away, so every key of the partner reaches it. Send an Idempotency-Key so a retry doesn't create it twice:

TypeScript

const { data: brand } = await lucra.brands.create({
  body: { name: "Acme", email: "ops@acme.com", brandFee: { of: "ad_spend", percent: 10 } },
  headers: { "Idempotency-Key": "acme-onboarding" },
})

Leave out brandFee to use your default from GET /v1/account.

The brand pays for its own programs and creator payments. Until a brand member adds a card at the URL from POST /v1/connections (provider: "card"), those writes return 409 requirement_payment_method. The onboarding embed walks them through it.

Update a brand

PATCH /v1/brands/:id sets its name, description, logo (profilePicture) and brandFee. A new fee applies to spend from then on.

Endpoints

GET/v1/brands

read

List the brands this key reaches, and a partner's brands whose relationship ended

const { data } = await lucra.brands.list({
  query: { status: "active" },
})

Query parameters

statusenum
activeended

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 21 fields each, and nextCursorShow

idacct_…
typeenum
brandpartner
namestring
statusenum
ended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeended
managedByacct_…nullable
brandFeeobjectnullable
The managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account partner.brandFee).
Show 2 child fieldsHide child fields
- ofenum
  ad_spendgmv
- percentnumber
partnerobjectnullable
A partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
- creatorTakeRateobjectnullable
  Show 1 child fieldHide child fields
  percentnumber
- brandFeeobjectnullable
  Show 2 child fieldsHide child fields
  ofenum
  ad_spendgmv
  percentnumber
emailstringnullable
phonestringnullable
profilePicturefile_…nullable
imageobjectnullable
The account's logo, with a short-lived url.
Show 5 child fieldsHide child fields
- fileIdfile_…nullable
- urlstring
- widthnumbernullable
- heightnumbernullable
- blurHashstringnullable
paymentMethodobjectnullable
A brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
- statusstring
  active
- brandstringnullable
- last4stringnullable
payoutsobject
Where it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
- identityobject
  Show 1 child fieldHide child fields
  statusenum
  requiredpendingverified
- bankAccountobjectnullable
  Show 1 child fieldHide child fields
  statusenum
  missingadded
brandsobjectnullable
The brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
creatorsobjectnullable
The account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
descriptionstringnullable
recruitmentobject
Show 2 child fieldsHide child fields
- headlinestringnullable
- descriptionstringnullable
listingobjectnullable
A partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
- listedboolean
- headlinestringnullable
- categoriesstring[]
- registeredAtstringnullable
versioninteger
createdAtstring
updatedAtstring

GET/v1/brands/:id

read

Get a brand

const { data } = await lucra.brands.retrieve({
  path: { id: "acct_…" },
})

Path parameters

idacct_…· required

Response20021 fieldsShow

idacct_…
typeenum
brandpartner
namestring
statusenum
ended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeended
managedByacct_…nullable
brandFeeobjectnullable
The managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account partner.brandFee).
Show 2 child fieldsHide child fields
- ofenum
  ad_spendgmv
- percentnumber
partnerobjectnullable
A partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
- creatorTakeRateobjectnullable
  Show 1 child fieldHide child fields
  percentnumber
- brandFeeobjectnullable
  Show 2 child fieldsHide child fields
  ofenum
  ad_spendgmv
  percentnumber
emailstringnullable
phonestringnullable
profilePicturefile_…nullable
imageobjectnullable
The account's logo, with a short-lived url.
Show 5 child fieldsHide child fields
- fileIdfile_…nullable
- urlstring
- widthnumbernullable
- heightnumbernullable
- blurHashstringnullable
paymentMethodobjectnullable
A brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
- statusstring
  active
- brandstringnullable
- last4stringnullable
payoutsobject
Where it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
- identityobject
  Show 1 child fieldHide child fields
  statusenum
  requiredpendingverified
- bankAccountobjectnullable
  Show 1 child fieldHide child fields
  statusenum
  missingadded
brandsobjectnullable
The brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
creatorsobjectnullable
The account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
descriptionstringnullable
recruitmentobject
Show 2 child fieldsHide child fields
- headlinestringnullable
- descriptionstringnullable
listingobjectnullable
A partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
- listedboolean
- headlinestringnullable
- categoriesstring[]
- registeredAtstringnullable
versioninteger
createdAtstring
updatedAtstring

POST/v1/brands

write

Create a brand a partner manages

const { data } = await lucra.brands.create({
  body: { name: "…" },
})

Body

namestring· required
brandFeeobject
Show 2 child fieldsHide child fields
- ofenum· required
  ad_spendgmv
- percentnumber· required
emailstring
phonestring

Response20121 fieldsShow

idacct_…
typeenum
brandpartner
namestring
statusenum
ended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeended
managedByacct_…nullable
brandFeeobjectnullable
The managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account partner.brandFee).
Show 2 child fieldsHide child fields
- ofenum
  ad_spendgmv
- percentnumber
partnerobjectnullable
A partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
- creatorTakeRateobjectnullable
  Show 1 child fieldHide child fields
  percentnumber
- brandFeeobjectnullable
  Show 2 child fieldsHide child fields
  ofenum
  ad_spendgmv
  percentnumber
emailstringnullable
phonestringnullable
profilePicturefile_…nullable
imageobjectnullable
The account's logo, with a short-lived url.
Show 5 child fieldsHide child fields
- fileIdfile_…nullable
- urlstring
- widthnumbernullable
- heightnumbernullable
- blurHashstringnullable
paymentMethodobjectnullable
A brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
- statusstring
  active
- brandstringnullable
- last4stringnullable
payoutsobject
Where it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
- identityobject
  Show 1 child fieldHide child fields
  statusenum
  requiredpendingverified
- bankAccountobjectnullable
  Show 1 child fieldHide child fields
  statusenum
  missingadded
brandsobjectnullable
The brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
creatorsobjectnullable
The account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
descriptionstringnullable
recruitmentobject
Show 2 child fieldsHide child fields
- headlinestringnullable
- descriptionstringnullable
listingobjectnullable
A partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
- listedboolean
- headlinestringnullable
- categoriesstring[]
- registeredAtstringnullable
versioninteger
createdAtstring
updatedAtstring

PATCH/v1/brands/:id

write

Update a brand a partner manages

const { data } = await lucra.brands.update({
  path: { id: "acct_…" },
  body: { brandFee: {} },
})

Path parameters

idacct_…· required

Body

brandFeeobjectnullable
Show 2 child fieldsHide child fields
- ofenum· required
  ad_spendgmv
- percentnumber· required
profilePicturefile_…nullable
namestring
descriptionstringnullable
recruitmentobject
Show 2 child fieldsHide child fields
- headlinestringnullable
- descriptionstringnullable
versioninteger

Response20021 fieldsShow

idacct_…
typeenum
brandpartner
namestring
statusenum
ended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeended
managedByacct_…nullable
brandFeeobjectnullable
The managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account partner.brandFee).
Show 2 child fieldsHide child fields
- ofenum
  ad_spendgmv
- percentnumber
partnerobjectnullable
A partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
- creatorTakeRateobjectnullable
  Show 1 child fieldHide child fields
  percentnumber
- brandFeeobjectnullable
  Show 2 child fieldsHide child fields
  ofenum
  ad_spendgmv
  percentnumber
emailstringnullable
phonestringnullable
profilePicturefile_…nullable
imageobjectnullable
The account's logo, with a short-lived url.
Show 5 child fieldsHide child fields
- fileIdfile_…nullable
- urlstring
- widthnumbernullable
- heightnumbernullable
- blurHashstringnullable
paymentMethodobjectnullable
A brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
- statusstring
  active
- brandstringnullable
- last4stringnullable
payoutsobject
Where it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
- identityobject
  Show 1 child fieldHide child fields
  statusenum
  requiredpendingverified
- bankAccountobjectnullable
  Show 1 child fieldHide child fields
  statusenum
  missingadded
brandsobjectnullable
The brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
creatorsobjectnullable
The account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
- countinteger
descriptionstringnullable
recruitmentobject
Show 2 child fieldsHide child fields
- headlinestringnullable
- descriptionstringnullable
listingobjectnullable
A partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
- listedboolean
- headlinestringnullable
- categoriesstring[]
- registeredAtstringnullable
versioninteger
createdAtstring
updatedAtstring

Create a brand

Payment method

Update a brand

Endpoints

Query parameters

Path parameters

Body

Path parameters

Body