Payments · Docs

Brands pay creators through Lucra. As soon as the brand's payment goes through, the creator's share goes to their own Stripe balance. It's paid out to their bank every week, and they can withdraw anytime (instantly, for a fee).

Amounts are in cents. On money objects, amount is the gross, fee comes out of it, and net is what's left. Every write that moves money needs an Idempotency-Key.

Fees

These are the standard plan's defaults. An account's plan or agreed terms can differ; Settings → Billing shows its own.

Fee	Default	Paid by
Payment to a creator	Free
Lucra fee	1.25% of the first $100,000 a month, 1% up to $300,000, 0.75% up to $1,000,000, 0.5% above, of ad spend, or of attributed sales for revenue-share programs	The brand
Retainer pay	Free
Standard withdrawal	Free
Instant withdrawal	1.5% (min 50¢)	Creator
Payout converted from USD	1%	Creator

Pay a creator

Send the creator and the net they should receive. The brand is charged exactly that:

TypeScript

await lucra.payments.create({
  body: { creator: "crtr_026UYfiw1Y6OvUpuKWiOpeL", net: 50000, note: "Launch bonus" },
  headers: { "Idempotency-Key": "launch-bonus-crtr_026UYfiw1Y6OvUpuKWiOpeL" },
})

The payment is pending until Stripe confirms the charge, then succeeded, or failed with a payment.failed webhook. A retry with the same Idempotency-Key returns the same payment and never charges twice.

A payment waiting on the brand (pending_approval) is released with PATCH /v1/payments/:id and { "status": "approved" }. Until it's sent to the creator (within minutes of the charge), the brand can dispute a payment with { "status": "disputed", "reason": "…" }; once sent, the payment is final.

Pay

One pay object describes how programs and retainers pay. This one guarantees $500 a month, plus $8 per 1,000 views and $50 per approved video, up to $2,000:

JSON

{
  "base": 50000,
  "rules": [
    { "per": "view", "amount": 800, "unit": 1000 },
    { "on": "approved_submission", "amount": 5000 }
  ],
  "cap": 200000,
  "schedule": { "every": "month" }
}

base is guaranteed each period. Programs don't take one.
rules pay per result (per), per event (on), a percent of ad spend or revenue (percentOf), or per conversion credited to the creator (conversion, with an amount or a percent of its value).
cap is the most paid per period.
schedule says when it pays: { "every": "week" } (or day, month, quarter, event), or { "after": "measurement", "days": 7 } for organic programs.
approval: "manual" holds each period's payment for you to approve (retainers only).

Pay that can't be paid

Pay is checked when it's saved. If it couldn't be paid as set, you get 422 invalid_pay listing every problem:

`code`	When
`pay_invalid_value`	An `amount` under 1 cent, a `percent` not above 0 and at most 100, or a `unit` under 1.
`pay_cap_zero`	`cap` is 0. Send `null` for no cap.
`pay_cap_below_amount`	`cap` is below an amount paid in one go (an `on` rule's amount, a `per` rule's amount for one unit, or `base`), so it could never be paid.
`pay_cap_required`	An organic program without a `cap`.
`pay_base_needs_period`	A `base` on a program, or with an `event` or `measurement` schedule. A base needs a schedule of every `day`, `week`, `month`, or `quarter`.
`pay_schedule_mismatch`	A retainer not paid every `day`, `week`, `month`, or `quarter`; a program on another schedule than its type's; or an organic program paying on ad results (ad spend, attributed revenue, impressions, clicks, installs, leads, purchases), which organic programs never have.
`pay_duplicate_rule`	Two rules on the same results (the same metric and `scope`), which would pay them twice; combine them into one.
`pay_scope_invalid`	A `scope.campaign` that isn't one of the brand's campaigns, or for a program, not one built from the program's work. A new program has none yet.
`pay_exceeds_budget`	A single amount larger than the program's `budget.amount`.
`pay_primary_missing`	A program without the rule its type pays per result (see programs).
`pay_primary_changed`	Program pay, or a creator's pay, that changes what the program pays per result on (for example ad spend to leads). Change the amount instead.
`pay_program_unsupported`	`"approval": "manual"` on a program, or pay per approved video on an organic program.

Retainers

A retainer is recurring pay for one creator. Offer one with POST /v1/retainers and { "creator", "pay", "deliverables" }, with an Idempotency-Key. A retainer can also pay only on conversions, like an affiliate deal: { "rules": [{ "conversion": "conv_1fK7pQ2wXy9LmN4bVc8RtZa", "amount": 500 }], "schedule": { "every": "week" } }.

The creator accepts or rejects it with PATCH /v1/retainers/:id and { "status": "accepted" } (or "rejected"). A partner answers for its roster creator with Lucra-Account: crtr_….

Each period pays its base up front and earned results at the end. Cancel with { "status": "canceling" }; the current period is still paid.

Failed charges

A declined charge retries after 1, 2, 2, and 2 days, then the retainer goes past_due until the brand updates its payment method. Program pay retries the same way.

Balance

GET /v1/balance shows a creator's earnings, or a partner's commissions ready to withdraw. Brands keep no balance: each charge goes to their saved card or bank.

Payouts

Every few minutes, Lucra sends each paid-for earning to the creator's Stripe balance, against the brand's charge, once they've verified their identity. GET /v1/payouts lists them. Every Monday, each creator's and partner's available balance is paid out to their bank as a standard withdrawal.

Supported payout countries

Payouts run on one of two rails, set by the payout country when the creator first sets up payouts.

Stripe Connect: Austria, Belgium, Bulgaria, Canada, Croatia, Cyprus, Czechia, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, United Kingdom, United States. Earnings go to the creator's (or partner's) Stripe balance, which they withdraw anytime and which is paid out every Monday.
Stripe Global Payouts: Australia, India, Indonesia, Israel, Japan, Jamaica, Mexico, Monaco, Morocco, New Zealand, San Marino, Singapore, Trinidad and Tobago, for creators only. Lucra keeps the earnings and pays them to the creator's bank every Monday in one payout, less the cross-border fee. They finish setup on Stripe's own page (the url from POST /v1/connections, even with checkout: elements), there's no withdrawing in between, and GET /v1/withdrawals lists the weekly payouts.

Global Payouts countries appear only once Lucra switches them on. GET /v1/payouts/countries lists the countries open now. A country that isn't open is a 422 (payout_country_unavailable). The country enum on POST /v1/connections (provider stripe) lists every country on both rails. Creators anywhere else can't be paid out yet.

Withdrawals

POST /v1/withdrawals moves a balance to the bank anytime, with speed set to standard (free) or instant. Leave out amount to withdraw everything. A creator adds their bank account on their first withdrawal. Global Payouts creators are paid every Monday instead, so their withdrawals return weekly_payouts_only.

Earnings

GET /v1/earnings lists what a creator earned, with its status: pending (until the brand's payment goes through), available, paid, or held while a dispute is reviewed.

Endpoints

GET/v1/balance

As creatorread

Get the balance: the account's commissions, or a creator's earnings

const { data } = await lucra.balance.retrieve()

Response2003 fieldsShow

balancesobject[]
Show 9 child fieldsHide child fields
- currencystring
  Lowercase ISO 4217 code, e.g. usd.
- availableinteger
  A creator's earnings ready to send to their Stripe balance, sent within minutes once their identity is verified; 0 for an account.
- pendinginteger
  A creator's earnings waiting on the brand's payment; 0 for an account.
- heldinteger
  A creator's earnings held while a dispute is reviewed; 0 for an account.
- paidinteger
  A creator's earnings sent to their Stripe balance, all time; 0 for an account.
- spentinteger
  Deprecated: always 0.
- refundableinteger
  Deprecated: always 0.
- withdrawableinteger
  In this balance's Stripe account (a creator's, or an account's commissions), ready to withdraw with POST /v1/withdrawals.
- instantWithdrawableinteger
  How much of withdrawable can go out instantly, to a debit card.
depositMethodsenum[]
Deprecated: always empty.
bankcard
withdrawalFeesobject
What a withdrawal costs; it comes out of the amount.
Show 2 child fieldsHide child fields
- instantobject
  Show 2 child fieldsHide child fields
  percentnumber
  A percent, e.g. 1.5 for 1.5%.
  minimuminteger
  The least an instant withdrawal costs.
- crossBorderobject
  Added outside the US; 0 in the US.
  Show 1 child fieldHide child fields
  percentnumber
  A percent, e.g. 1.5 for 1.5%.

GET/v1/balance/tax

As creatorread

Get US tax reporting: whether a taxpayer ID is on file, and what Lucra paid each year

const { data } = await lucra.balance.tax.retrieve()

Response2005 fieldsShow

taxIdenum
The SSN or EIN on the Stripe account: verified by Stripe, provided, flagged (failed) or missing.
missingprovidedverifiedfailed
requiredboolean
True when withdrawals wait for a taxpayer ID (US, paid at least threshold this year): add it with POST /v1/connections (provider stripe).
thresholdinteger
What Lucra can pay a US payee in a calendar year before a taxpayer ID is needed, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
yearsobject[]
Newest first.
Show 2 child fieldsHide child fields
- yearinteger
- reportableinteger
  What Lucra paid this balance that year (UTC), in cents: transfers less fees taken back.

GET/v1/balance/transactions

read

List every ledger line on the account

const { data } = await lucra.balance.transactions.list({
  query: { type: "…" },
})

Query parameters

typestring
Comma-separated transaction types, e.g. creator_earning,platform_fee.
programprog_…

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 15 fields each, and nextCursorShow

idtxn_…
typestring
statusstring
amountinteger
Signed, in cents: positive adds to the balance.
feeinteger
In cents.
netinteger
Signed, in cents: amount less fee.
balancenumbernullable
currencystring
Lowercase ISO 4217 code, e.g. usd.
descriptionstringnullable
What it is, e.g. Creator payment.
memostringnullable
sourcestring
counterpartyobject
Show 3 child fieldsHide child fields
- typeenum
  partnerpayment_methodcreatorplatformaccount
- idcrtr_…nullable
  Set when the other side is a creator.
- namestringnullable
campaigncamp_…nullable
programprog_…nullable
occurredAtstring

POST/v1/payments

write

Pay a creator

const { data } = await lucra.payments.create({
  body: { creator: "crtr_…", net: 1000 },
})

Headers

Idempotency-Keystring· required
Unique to this write; resend it to retry safely.

Body

creatorcrtr_…· required
netinteger· required
In cents, what the creator receives and the brand is charged.
notestring

Response20115 fieldsShow

idpay_…
creatorcrtr_…
amountinteger
Charged to the brand: what the creator receives (net; Lucra takes no fee), in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with failureMessage. disputed until Lucra decides; refunded if canceled.
pending_approvalapprovedpendingsucceededfailedrefundeddisputed
retainerret_…nullable
The retainer this is a period payment of, if any.
failureMessagestringnullable
notestringnullable
holdUntilAtstringnullable
disputeobjectnullable
While status is disputed: who opened it and why; null otherwise.
Show 3 child fieldsHide child fields
- byenum
  brand: the paying brand disputed it; lucra: Lucra holds it for review.
  brandlucra
- reasonstringnullable
  Why; a Lucra hold's reason shows only to Lucra's admin.
- openedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/payments

As creatorread

List payments to creators

const { data } = await lucra.payments.list({
  query: { creator: "crtr_…" },
})

Query parameters

creatorcrtr_…
retainerret_…
statusenum
pending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with failureMessage. disputed until Lucra decides; refunded if canceled.
pending_approvalapprovedpendingsucceededfailedrefundeddisputed

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 15 fields each, and nextCursorShow

idpay_…
creatorcrtr_…
amountinteger
Charged to the brand: what the creator receives (net; Lucra takes no fee), in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with failureMessage. disputed until Lucra decides; refunded if canceled.
pending_approvalapprovedpendingsucceededfailedrefundeddisputed
retainerret_…nullable
The retainer this is a period payment of, if any.
failureMessagestringnullable
notestringnullable
holdUntilAtstringnullable
disputeobjectnullable
While status is disputed: who opened it and why; null otherwise.
Show 3 child fieldsHide child fields
- byenum
  brand: the paying brand disputed it; lucra: Lucra holds it for review.
  brandlucra
- reasonstringnullable
  Why; a Lucra hold's reason shows only to Lucra's admin.
- openedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/payments/:id

As creatorread

Get a payment to a creator

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

Path parameters

idpay_…· required

Response20015 fieldsShow

idpay_…
creatorcrtr_…
amountinteger
Charged to the brand: what the creator receives (net; Lucra takes no fee), in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with failureMessage. disputed until Lucra decides; refunded if canceled.
pending_approvalapprovedpendingsucceededfailedrefundeddisputed
retainerret_…nullable
The retainer this is a period payment of, if any.
failureMessagestringnullable
notestringnullable
holdUntilAtstringnullable
disputeobjectnullable
While status is disputed: who opened it and why; null otherwise.
Show 3 child fieldsHide child fields
- byenum
  brand: the paying brand disputed it; lucra: Lucra holds it for review.
  brandlucra
- reasonstringnullable
  Why; a Lucra hold's reason shows only to Lucra's admin.
- openedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/payments/:id

write

Approve or dispute a payment to a creator

const { data } = await lucra.payments.update({
  path: { id: "pay_…" },
  body: { },
})

Path parameters

idpay_…· required

Headers

Idempotency-Keystring· required
Unique to this write; resend it to retry safely.

Response20015 fieldsShow

idpay_…
creatorcrtr_…
amountinteger
Charged to the brand: what the creator receives (net; Lucra takes no fee), in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with failureMessage. disputed until Lucra decides; refunded if canceled.
pending_approvalapprovedpendingsucceededfailedrefundeddisputed
retainerret_…nullable
The retainer this is a period payment of, if any.
failureMessagestringnullable
notestringnullable
holdUntilAtstringnullable
disputeobjectnullable
While status is disputed: who opened it and why; null otherwise.
Show 3 child fieldsHide child fields
- byenum
  brand: the paying brand disputed it; lucra: Lucra holds it for review.
  brandlucra
- reasonstringnullable
  Why; a Lucra hold's reason shows only to Lucra's admin.
- openedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/payouts/countries

As creatorread

The payout countries that can be chosen now: a creator's (Stripe Global Payouts' too while it's on), or this brand's or partner's

const { data } = await lucra.payouts.countries.retrieve()

Response2001 fieldsShow

countriesenum[]
The payout countries that can be chosen now. Stripe Global Payouts countries appear only while Lucra has them switched on; brands and partners get Stripe Connect's only.
ATBEBGCAHRCYCZDKEEFIFRDEGRHUISIEITLVLILTLUMTNLNOPLPTROSKSIESSECHGBUSAUINIDILJPJMMXMCMANZSMSGTT

GET/v1/payouts

As creatorread

List payouts: to creators from this brand's earnings, received by this account, or (as a creator) the creator's own

const { data } = await lucra.payouts.list({
  query: { direction: "sent" },
})

Query parameters

directionenum
sentreceived
creatorcrtr_…
statusstring
One or more, comma-separated: pending, submitted, paid, failed, reversed, unknown.

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 12 fields each, and nextCursorShow

idpout_…
directionenum
sent: from this brand's earnings to a creator's balance; received: paid to this account's balance, like a partner's commission.
sentreceived
creatorcrtr_…nullable
sourcesenum[]
paid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commission
amountinteger
The earnings it pays; net is sent to the recipient's Stripe balance, in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pendingsubmittedpaidfailedreversedunknown
failureMessagestringnullable
createdAtstring
updatedAtstring

GET/v1/payouts/:id

As creatorread

Get a payout

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

Path parameters

idpout_…· required

Response20012 fieldsShow

idpout_…
directionenum
sent: from this brand's earnings to a creator's balance; received: paid to this account's balance, like a partner's commission.
sentreceived
creatorcrtr_…nullable
sourcesenum[]
paid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commission
amountinteger
The earnings it pays; net is sent to the recipient's Stripe balance, in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pendingsubmittedpaidfailedreversedunknown
failureMessagestringnullable
createdAtstring
updatedAtstring

GET/v1/earnings

As creatorread

List a creator's earnings

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

Query parameters

statusstring
One or more, comma-separated: pending, held, available, paid.
sourcestring
One or more, comma-separated: paid_ads, organic, submission, program, bonus, retainer, referral, adjustment, partner_commission.
programprog_…
retainerret_…

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 13 fields each, and nextCursorShow

idern_…
programprog_…nullable
accountacct_…
The brand that paid it.
submissionsub_…nullable
retainerret_…nullable
sourceenum
paid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commission
amountinteger
Earned before any partner take rate (fee); the creator receives net, in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pending until the brand's charge succeeds, then available, then paid: sent to the creator's Stripe balance against that charge (once their identity is verified), paid out to their bank weekly or withdrawn anytime. held while a dispute is reviewed, or a referral waits on the payment it comes from.
pendingheldavailablepaid
holdUntilAtstringnullable
occurredAtstring

GET/v1/earnings/:id

As creatorread

Get one of a creator's earnings

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

Path parameters

idern_…· required

Response20013 fieldsShow

idern_…
programprog_…nullable
accountacct_…
The brand that paid it.
submissionsub_…nullable
retainerret_…nullable
sourceenum
paid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commission
amountinteger
Earned before any partner take rate (fee); the creator receives net, in cents.
feeinteger
Taken from amount, in cents.
netinteger
amount less fee, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
pending until the brand's charge succeeds, then available, then paid: sent to the creator's Stripe balance against that charge (once their identity is verified), paid out to their bank weekly or withdrawn anytime. held while a dispute is reviewed, or a referral waits on the payment it comes from.
pendingheldavailablepaid
holdUntilAtstringnullable
occurredAtstring

POST/v1/withdrawals

As creatorwrite

Withdraw from the balance to the bank account or debit card (not for Global Payouts creators, paid every Monday)

const { data } = await lucra.withdrawals.create({
  body: { amount: 1000 },
})

Headers

Idempotency-Keystring· required
Unique to this write; resend it to retry safely.

Body

amountinteger
In cents; defaults to everything withdrawable.
speedenum
standardinstant

Response20111 fieldsShow

idwdr_…
amountinteger
Taken from the balance, in cents.
feeinteger
Lucra's fee, taken from the amount: the instant fee, plus the cross-border fee outside the US.
netinteger
amount less fee: what reaches the bank or card, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
speedenum
standardinstant
statusenum
in_transit once Stripe accepted it; paid when it reached the bank.
pendingin_transitpaidfailed
failureMessagestringnullable
arrivesAtstringnullable
createdAtstring
updatedAtstring

GET/v1/withdrawals

As creatorread

List withdrawals from the balance, or a Global Payouts creator's weekly payouts

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

Query parameters

statusstring
One or more, comma-separated: pending, in_transit, paid, failed.

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 11 fields each, and nextCursorShow

idwdr_…
amountinteger
Taken from the balance, in cents.
feeinteger
Lucra's fee, taken from the amount: the instant fee, plus the cross-border fee outside the US.
netinteger
amount less fee: what reaches the bank or card, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
speedenum
standardinstant
statusenum
in_transit once Stripe accepted it; paid when it reached the bank.
pendingin_transitpaidfailed
failureMessagestringnullable
arrivesAtstringnullable
createdAtstring
updatedAtstring

GET/v1/withdrawals/:id

As creatorread

Get a withdrawal

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

Path parameters

idwdr_…· required

Response20011 fieldsShow

idwdr_…
amountinteger
Taken from the balance, in cents.
feeinteger
Lucra's fee, taken from the amount: the instant fee, plus the cross-border fee outside the US.
netinteger
amount less fee: what reaches the bank or card, in cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
speedenum
standardinstant
statusenum
in_transit once Stripe accepted it; paid when it reached the bank.
pendingin_transitpaidfailed
failureMessagestringnullable
arrivesAtstringnullable
createdAtstring
updatedAtstring

GET/v1/retainers

As creatorread

List retainers

const { data } = await lucra.retainers.list({
  query: { creator: "crtr_…" },
})

Query parameters

creatorcrtr_…

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 21 fields each, and nextCursorShow

idret_…
creatorcrtr_…
accountacct_…
The brand that offers the retainer.
brandNamestring
brandAvatarUrlstringnullable
kindenum
smart_retainer pays whichever is more each period: the guarantee (pay.base) or the creator's program earnings from this account, up to pay.cap.
retainersmart_retainer
deliverableCountnumbernullable
Approved deliverables expected each period.
payobject
Show 5 child fieldsHide child fields
- rulesobject[]
- baseinteger
  Guaranteed each period, in cents.
- capintegernullable
  The most one creator is paid per period, in cents; null or left out for no cap.
- scheduleobject
- approvalenum
  automatic pays each period on its own; manual waits for the brand to approve the calculated amount.
  automaticmanual
summarystring
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
draftofferedacceptedactivecancelingendedrejected
billingStatusstring
currentPeriodEndAtstringnullable
deliverablesstringnullable
notesstringnullable
documentsany[]
The agreements accepting accepts; accepted once the creator accepted that version with this brand.
offeredAtstring
acceptedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/retainers/:id

As creatorread

Get a retainer

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

Path parameters

idret_…· required

Response20021 fieldsShow

idret_…
creatorcrtr_…
accountacct_…
The brand that offers the retainer.
brandNamestring
brandAvatarUrlstringnullable
kindenum
smart_retainer pays whichever is more each period: the guarantee (pay.base) or the creator's program earnings from this account, up to pay.cap.
retainersmart_retainer
deliverableCountnumbernullable
Approved deliverables expected each period.
payobject
Show 5 child fieldsHide child fields
- rulesobject[]
- baseinteger
  Guaranteed each period, in cents.
- capintegernullable
  The most one creator is paid per period, in cents; null or left out for no cap.
- scheduleobject
- approvalenum
  automatic pays each period on its own; manual waits for the brand to approve the calculated amount.
  automaticmanual
summarystring
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
draftofferedacceptedactivecancelingendedrejected
billingStatusstring
currentPeriodEndAtstringnullable
deliverablesstringnullable
notesstringnullable
documentsany[]
The agreements accepting accepts; accepted once the creator accepted that version with this brand.
offeredAtstring
acceptedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

POST/v1/retainers

write

Offer a creator a retainer

const { data } = await lucra.retainers.create({
  body: { creator: "crtr_…", pay: {} },
})

Headers

Idempotency-Keystring· required
Unique to this write; resend it to retry safely.

Body

creatorcrtr_…· required
payobject· required
Show 5 child fieldsHide child fields
- rulesobject[]
- baseinteger
  Guaranteed each period, in cents.
- capintegernullable
  The most one creator is paid per period, in cents; null or left out for no cap.
- scheduleobject· required
- approvalenum
  automatic pays each period on its own; manual waits for the brand to approve the calculated amount.
  automaticmanual
kindenum
smart_retainer pays whichever is more each period: pay.base (the guarantee) or the creator's program earnings from this account, up to pay.cap; it has no rules.
retainersmart_retainer
deliverableCountinteger
Approved deliverables expected each period.
deliverablesstring
notesstring

Response20121 fieldsShow

idret_…
creatorcrtr_…
accountacct_…
The brand that offers the retainer.
brandNamestring
brandAvatarUrlstringnullable
kindenum
smart_retainer pays whichever is more each period: the guarantee (pay.base) or the creator's program earnings from this account, up to pay.cap.
retainersmart_retainer
deliverableCountnumbernullable
Approved deliverables expected each period.
payobject
Show 5 child fieldsHide child fields
- rulesobject[]
- baseinteger
  Guaranteed each period, in cents.
- capintegernullable
  The most one creator is paid per period, in cents; null or left out for no cap.
- scheduleobject
- approvalenum
  automatic pays each period on its own; manual waits for the brand to approve the calculated amount.
  automaticmanual
summarystring
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
draftofferedacceptedactivecancelingendedrejected
billingStatusstring
currentPeriodEndAtstringnullable
deliverablesstringnullable
notesstringnullable
documentsany[]
The agreements accepting accepts; accepted once the creator accepted that version with this brand.
offeredAtstring
acceptedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/retainers/:id

As creatorwrite

Cancel a retainer, or, as the creator, accept or reject an offer or cancel

const { data } = await lucra.retainers.update({
  path: { id: "ret_…" },
  body: { status: "accepted" },
})

Path parameters

idret_…· required

Body

statusenum· required
acceptedrejectedcanceling
versioninteger

Response20021 fieldsShow

idret_…
creatorcrtr_…
accountacct_…
The brand that offers the retainer.
brandNamestring
brandAvatarUrlstringnullable
kindenum
smart_retainer pays whichever is more each period: the guarantee (pay.base) or the creator's program earnings from this account, up to pay.cap.
retainersmart_retainer
deliverableCountnumbernullable
Approved deliverables expected each period.
payobject
Show 5 child fieldsHide child fields
- rulesobject[]
- baseinteger
  Guaranteed each period, in cents.
- capintegernullable
  The most one creator is paid per period, in cents; null or left out for no cap.
- scheduleobject
- approvalenum
  automatic pays each period on its own; manual waits for the brand to approve the calculated amount.
  automaticmanual
summarystring
currencystring
Lowercase ISO 4217 code, e.g. usd.
statusenum
draftofferedacceptedactivecancelingendedrejected
billingStatusstring
currentPeriodEndAtstringnullable
deliverablesstringnullable
notesstringnullable
documentsany[]
The agreements accepting accepts; accepted once the creator accepted that version with this brand.
offeredAtstring
acceptedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring