Sign in

Reference

Build on the Lucra API.

Get API keyQuickstart

Drag a sticker to move it, or use the arrow keys while focused.

Connections

Ad accounts, stores, and creator socials.

A connection is an outside account linked to Lucra: a brand's ad accounts and Shopify store, or a creator's Instagram and TikTok.

providerWhoUsed for
meta, tiktok, google, snapchatBrandAd accounts campaigns run on
shopifyBrandProducts and sample orders
instagram, tiktokCreatorPosts for organic programs

GET /v1/connections lists them. People sign in to the platform themselves, but never to Lucra: send them to the url from POST /v1/connections with a provider (Shopify also needs shop, the store's .myshopify.com domain). Call it with the brand's key, a partner key with Lucra-Account: acct_… for a brand, or a partner key with Lucra-Account: crtr_… for a creator on its roster. The platform sends them back to your returnUrl (an https page on the key's embed origins) with status=connected or status=error; then wait for the connection.connected webhook or read GET /v1/connections. connection.expired means it needs reconnecting the same way.

Ad account setup

After an ad platform sign-in the connection is setup_needed. GET /v1/connections/:id/setup lists the ad accounts, pages, and identities the person can pick from; pass a pick (like businessCenterId) to list what's under it. Save the picks with PATCH /v1/connections/:id and selection. Disconnect with status: "disconnected".

Posts and syncs

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

Hosted links

Stripe steps are connections too: provider: "stripe" sets up payouts (identity and bank until verified, then managing them; send country the first time for a creator) and provider: "card" adds or manages a brand's payment method. Everything around them, before and after, is in the API.

Endpoints

GET/v1/connections/:id
As creatorread

Get a connection

SDKlucra.connections.retrieve({ path: { id } })

Path parameters

  • idstringrequired
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

SDKlucra.connections.setup.retrieve({ path: { id }, query })

Path parameters

  • idstringrequired

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

SDKlucra.connections.list({ query })

Query parameters

  • limitinteger
  • cursorstring
  • createdAfterstring

    Only items created at or after this time.

  • createdBeforestring

    Only items created before this time.

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

SDKlucra.connections.syncs.create({ path: { id } })

Path parameters

  • idstringrequired
POST/v1/connections
As creatorwrite

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

SDKlucra.connections.create({ body })

Body

  • providerenumrequired

    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.

    ATBEBGCAHRCYCZDKEEFIFRDEGRHUISIEITLVLILTLUMTNLNOPLPTROSKSIESSECHGBUS
  • 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: hosted (the default) returns Stripe's page at `url` (its billing portal once a card is saved); 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.

    hostedelements
Response2013 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 card and `checkout: elements`: the Checkout Session's client secret for Stripe's Payment Element (`initCheckoutElementsSdk`); null otherwise. Stripe's setup webhook saves the card.

  • 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

SDKlucra.connections.update({ path: { id }, body })

Path parameters

  • idstringrequired

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 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

SDKlucra.connections.posts.list({ path: { id } })

Path parameters

  • idstringrequired
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 fields
    • fileIdstringnullable
    • urlstring
    • widthnumbernullable
    • heightnumbernullable
    • blurHashstringnullable
  • metricsobjectnullable
    Show 6 child fields
    • viewsnumber
    • likesnumbernullable
    • commentsnumbernullable
    • sharesnumbernullable
    • savesnumbernullable
    • engagementsnumbernullable