# Connections

> Ad accounts, stores, socials, payouts and cards.

Source: https://www.onlucra.com/docs/api-connections

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](https://www.onlucra.com/docs/api-ads) 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:

```ts
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](https://www.onlucra.com/docs/api-payments#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](https://www.onlucra.com/docs/webhooks) (or `creator.payouts_updated` for Stripe), or read `GET /v1/connections`. `connection.expired` means the person needs to connect again the same way.

## Pick an ad account

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](https://www.onlucra.com/docs/api-commerce).

## Endpoints

- `GET /v1/connections/:id` (read, SDK `lucra.connections.retrieve`): Get a connection
- `GET /v1/connections/:id/setup` (read, SDK `lucra.connections.setup.retrieve`): List an ad platform's accounts, pages and identities to pick from, and the ones picked
- `GET /v1/connections` (read, SDK `lucra.connections.list`): List connected ad platforms, Shopify and creator social accounts
- `POST /v1/connections/:id/syncs` (write, SDK `lucra.connections.syncs.create`): Sync a connected shop's catalog, or, as a creator, mirror a social account's posts now
- `POST /v1/connections` (write, SDK `lucra.connections.create`): Connect a platform, payouts or a card: returns the hosted page to send the person to
- `PATCH /v1/connections/:id` (write, SDK `lucra.connections.update`): Pick a brand's ad account, page and identity after signing in, or disconnect a connection
- `GET /v1/connections/:id/posts` (read, SDK `lucra.connections.posts.list`): List the posts Lucra mirrors from a creator's connected account, newest first
- `POST /v1/connections/:id/logos` (write, SDK `lucra.connections.logos.create`): Upload a square logo (PNG or JPEG, at least 128 × 128, up to 5 MB) to a Google Ads connection