Connections · Docs

A connection links an outside account to Lucra: a brand's ad accounts and Shopify store, or a creator's Instagram and TikTok. Stripe payout setup and a brand's card are connections too.

`provider`	Who	Used for
`meta`, `tiktok`, `google`, `snapchat`	Brand	Ad accounts campaigns run on
`shopify`	Brand	Products and sample orders
`card`	Brand	The payment method for programs and payments
`instagram`, `tiktok`	Creator	Posts for organic programs
`stripe`	Creator or partner	Identity and bank details for payouts

Connect an account

People sign in to the platform or Stripe themselves, never to Lucra. POST /v1/connections returns the hosted page to send them to:

TypeScript

const { data } = await lucra.as("crtr_026UYfiw1Y6OvUpuKWiOpeL").connections.create({
  body: { provider: "tiktok", returnUrl: "https://app.example.com/settings" },
})
// Redirect the creator to data.url

Call it as the brand, or as a partner with Lucra-Account set to a client brand or roster creator.
Shopify also needs shop, the store's .myshopify.com domain. A creator's first stripe setup needs their payout country, one of the supported payout countries.
When they finish, they come back to your returnUrl with status=connected or status=error added. An https returnUrl must be on your key's embed origins.

Then wait for the connection.connected webhook (or creator.payouts_updated for Stripe), or read GET /v1/connections. connection.expired means the person needs to connect again the same way.

After an ad platform sign-in, the connection is setup_needed until you pick the ad account to use. GET /v1/connections/:id/setup lists the ad accounts, pages and identities the person can choose from. Pass a pick, like businessCenterId, to list what's under it. Save the picks with PATCH /v1/connections/:id and selection.

Disconnect with PATCH /v1/connections/:id and status: "disconnected". An ad platform with live campaigns can't be disconnected.

Posts and syncs

As a creator, GET /v1/connections/:id/posts lists the posts Lucra mirrors from their account, and POST /v1/connections/:id/syncs refreshes them now. For a brand's Shopify connection, the same sync imports the catalog into products.

Endpoints

GET/v1/connections/:id

As creatorread

Get a connection

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

Path parameters

idconn_…· required

Response20012 fieldsShow

idconn_…
providerenum
The platform connected.
metatiktokgooglesnapchatshopifyinstagram
statusstring
The platform connection's state, e.g. connected, active, expired; a shop is connected or reconnect_required.
namestringnullable
The ad account, the shop domain, or the creator's handle.
handlestringnullable
A creator's handle on the platform; null for a brand's connections.
avatarUrlstringnullable
A short-lived link to a creator account's profile photo.
lastSyncedAtstringnullable
errorstringnullable
Why a creator account's last sync failed, e.g. token_expired.
activeCampaignsinteger
Live campaigns (or ones needing attention) on an ad platform connection. Campaigns only; canDisconnect covers every reason a disconnect is refused.
canDisconnectboolean
Whether a disconnect would be accepted now: you manage the account's connections (or it's your own creator account), and no campaign, ad operation or ad plan is active on it.
createdAtstring
updatedAtstring

GET/v1/connections/:id/setup

read

List an ad platform's accounts, pages and identities to pick from, and the ones picked

const { data } = await lucra.connections.setup.retrieve({
  path: { id: "conn_…" },
  query: { adAccountId: "…" },
})

Path parameters

idconn_…· required

Query parameters

adAccountIdstring
The ad account campaigns run in (Meta, Google, Snapchat).
advertiserIdstring
TikTok's advertiser account.
businessCenterIdstring
TikTok's business center; send it to list the advertisers under it.
businessIdstring
Meta's business; send it to list the ad accounts and pages under it.
identityIdstring
The TikTok identity ads post as.
organizationIdstring
Snapchat's organization; send it to list its ad accounts.
pageIdstring
The Facebook page Meta ads post as.
profileIdstring
Snapchat's public profile ads post as.

GET/v1/connections

As creatorread

List connected ad platforms, Shopify and creator social accounts

const { data } = await lucra.connections.list()

Query parameters

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 12 fields each, and nextCursorShow

idconn_…
providerenum
The platform connected.
metatiktokgooglesnapchatshopifyinstagram
statusstring
The platform connection's state, e.g. connected, active, expired; a shop is connected or reconnect_required.
namestringnullable
The ad account, the shop domain, or the creator's handle.
handlestringnullable
A creator's handle on the platform; null for a brand's connections.
avatarUrlstringnullable
A short-lived link to a creator account's profile photo.
lastSyncedAtstringnullable
errorstringnullable
Why a creator account's last sync failed, e.g. token_expired.
activeCampaignsinteger
Live campaigns (or ones needing attention) on an ad platform connection. Campaigns only; canDisconnect covers every reason a disconnect is refused.
canDisconnectboolean
Whether a disconnect would be accepted now: you manage the account's connections (or it's your own creator account), and no campaign, ad operation or ad plan is active on it.
createdAtstring
updatedAtstring

POST/v1/connections/:id/syncs

As creatorwrite

Sync a connected shop's catalog, or, as a creator, mirror a social account's posts now

const { data } = await lucra.connections.syncs.create({
  path: { id: "conn_…" },
})

Path parameters

idconn_…· required

POST/v1/connections

As creatorwrite

Connect a platform, payouts or a card: returns the hosted page to send the person to

const { data } = await lucra.connections.create({
  body: { provider: "meta" },
})

Body

providerenum· required
A brand connects meta, google, snapchat, tiktok or shopify; a creator (Lucra-Account: crtr_…) instagram or tiktok. stripe sets up payouts on Stripe (identity and bank until verified, then managing them), for a creator or the account itself; card adds or manages the card Lucra charges a brand.
metagooglesnapchattiktokinstagramshopifystripecard
shopstring
With shopify: the store's domain, like acme.myshopify.com.
countryenum
With stripe, for a creator: their payout country, required the first time. These are the countries Lucra pays out to; creators elsewhere can't be paid out yet. Stripe Global Payouts countries (paid to the bank every Monday) are accepted only while Lucra has them switched on, and never for an account's own payouts: anything else is a 422. GET /v1/payouts/countries lists the ones open now.
ATBEBGCAHRCYCZDKEEFIFRDEGRHUISIEITLVLILTLUMTNLNOPLPTROSKSIESSECHGBUSAUINIDILJPJMMXMCMANZSMSGTT
returnUrlstring
Where the person comes back to, with status=connected or status=error added: your own https page (its origin must be on the key's embed origins), a page of the Lucra app (a path), or lucra-creators: for the Lucra iOS app. Defaults to a hosted done page (for stripe and card, the matching settings page).
checkoutenum
With card or stripe. hosted (the default) returns Stripe's page at url. With card, elements returns clientSecret to save a new card in your own form with Stripe's Payment Element (Checkout elements, setup mode), which then replaces the card charged. With stripe, elements returns clientSecret and component for Stripe's embedded Connect component (Connect.js): account_onboarding until identity is verified, then account_management. A Global Payouts creator has no embedded form: url is Stripe's hosted page instead, with clientSecret null.
hostedelements

Response2014 fieldsShow

urlstringnullable
Send the person here: they finish on the platform or Stripe, never on Lucra. The connection.connected (or creator.payouts_updated) webhook, or GET /v1/connections, shows the result. Null with checkout: elements.
clientSecretstringnullable
With checkout: elements: for card, the Checkout Session's client secret for Stripe's Payment Element (initCheckoutElementsSdk; Stripe's setup webhook saves the card); for stripe, the account session's client secret for Connect.js (fetchClientSecret). Null otherwise.
componentenumnullable
With stripe and checkout: elements: the Connect embedded component to render with the client secret; null otherwise.
account_onboardingaccount_management
expiresAtstringnullable
When the page stops working; null when it doesn't expire.

PATCH/v1/connections/:id

As creatorwrite

Pick a brand's ad account, page and identity after signing in, or disconnect a connection

const { data } = await lucra.connections.update({
  path: { id: "conn_…" },
  body: { status: "disconnected" },
})

Path parameters

idconn_…· required

Body

statusstring
Disconnects it: Lucra forgets the platform's tokens. An ad platform with live campaigns (see canDisconnect) is refused.
disconnected
selectionobject
A brand's ad platform picks, from GET /v1/connections/:id/setup: send the IDs it lists (e.g. adAccountId and pageId) to save them.
Show 8 child fieldsHide child fields
- adAccountIdstring
  The ad account campaigns run in (Meta, Google, Snapchat).
- advertiserIdstring
  TikTok's advertiser account.
- businessCenterIdstring
  TikTok's business center; send it to list the advertisers under it.
- businessIdstring
  Meta's business; send it to list the ad accounts and pages under it.
- identityIdstring
  The TikTok identity ads post as.
- organizationIdstring
  Snapchat's organization; send it to list its ad accounts.
- pageIdstring
  The Facebook page Meta ads post as.
- profileIdstring
  Snapchat's public profile ads post as.

Response20012 fieldsShow

idconn_…
providerenum
The platform connected.
metatiktokgooglesnapchatshopifyinstagram
statusstring
The platform connection's state, e.g. connected, active, expired; a shop is connected or reconnect_required.
namestringnullable
The ad account, the shop domain, or the creator's handle.
handlestringnullable
A creator's handle on the platform; null for a brand's connections.
avatarUrlstringnullable
A short-lived link to a creator account's profile photo.
lastSyncedAtstringnullable
errorstringnullable
Why a creator account's last sync failed, e.g. token_expired.
activeCampaignsinteger
Live campaigns (or ones needing attention) on an ad platform connection. Campaigns only; canDisconnect covers every reason a disconnect is refused.
canDisconnectboolean
Whether a disconnect would be accepted now: you manage the account's connections (or it's your own creator account), and no campaign, ad operation or ad plan is active on it.
createdAtstring
updatedAtstring

GET/v1/connections/:id/posts

As creatorread

List the posts Lucra mirrors from a creator's connected account, newest first

const { data } = await lucra.connections.posts.list({
  path: { id: "conn_…" },
})

Path parameters

idconn_…· required

Response200A page of items, 12 fields each, and nextCursorShow

idstring
The post's ID on its platform.
platformenum
instagramtiktok
urlstringnullable
titlestringnullable
captionstringnullable
publishedAtstringnullable
durationLabelstringnullable
durationSecondsnumbernullable
thumbnailUrlstringnullable
videoUrlstringnullable
thumbnailImageobjectnullable
Show 5 child fieldsHide child fields
- fileIdstringnullable
- urlstring
- widthnumbernullable
- heightnumbernullable
- blurHashstringnullable
metricsobjectnullable
Show 6 child fieldsHide child fields
- viewsnumber
- likesnumbernullable
- commentsnumbernullable
- sharesnumbernullable
- savesnumbernullable
- engagementsnumbernullable

Connect an account

Pick an ad account

Posts and syncs

Endpoints

Path parameters

Path parameters

Query parameters

Query parameters

Path parameters

Body

Path parameters

Body

Path parameters