CRM provisioning (merchants)

A merchant (acc_xxx) is the CRM organization: it owns stores, products, orders, customers, subscriptions, and CRM Keys. This page covers provisioning merchants and minting CRM Keys on the CRM domain (/api/public/v1/partner/*). The full onboarding lifecycle, in one pass:

Create the merchant with your Partner Key (merchants.create), passing your own externalRef for idempotency and — if you want the client to log in — their email.
The contact receives an invitation email fully branded as you (your name, logo, colors — TagadaPay never appears), sets their own password, and lands on your CRM host as admin of their organization.
Mint a CRM Key (merchants.keys.create) whenever your backend needs to read or manage that merchant’s data on their behalf.

CRM-only is valid. A merchant does not need a TPA. If your product only uses the merchant control plane (catalog, orders, customers, subscriptions) and processes payments elsewhere, you never have to touch the Processing domain.When you do want TagadaPay to process cards: CRM-only partners submit an entity application (partners.processing.applications.create({ accountId })) or embed; payfac partners use tpas.create(). See Processing provisioning.

Create a merchant

const partner = new Tagada(process.env.TAGADA_PARTNER_KEY!);

const merchant = await partner.partners.crm.merchants.create({
  legalName: 'Acme SAS',
  country: 'FR',                // ISO 3166-1 alpha-2 (optional)
  currency: 'EUR',              // ISO 4217 (optional)
  externalRef: 'merchant_42',   // YOUR id — used for idempotency
  email: 'owner@acme.com',      // optional — invite the merchant to the dashboard
  metadata: { plan: 'pro' },
});

// →
// {
//   object: 'merchant',
//   id: 'acc_xxx',
//   legalName: 'Acme SAS',
//   externalRef: 'merchant_42',
//   country: null,        // not stored on the merchant — see note below
//   currency: null,
//   managementMode: 'partner_managed',
//   createdAt: '2026-04-29T…',
//   portalInvite: {       // present when `email` was supplied
//     object: 'merchant_portal_invite',
//     status: 'invited',        // 'added' when they already have an account with you
//     email: 'owner@acme.com',
//     clerkOrgId: 'org_…',
//     clerkUserId: null,
//     invitationId: 'orginv_…',
//     emailMode: 'branded',     // email carries YOUR partner branding
//   },
// }

Creating a merchant also auto-provisions a default store (store_xxx) so the CRM is immediately usable.

country / currency you pass on create() are provisioning inputs — currency sets the auto-created store’s base currency. They are not stored on the merchant object itself, so the response always returns country: null and currency: null. Read per-store currency back via the CRM stores API.

Idempotency

A second create() with the same externalRef returns the same merchant — retries are safe:

const a = await partner.partners.crm.merchants.create({ legalName: 'Acme', externalRef: 'merchant_42' });
const b = await partner.partners.crm.merchants.create({ legalName: 'Acme', externalRef: 'merchant_42' });
console.log(a.id === b.id); // true

The idempotency key is the (partnerId, externalRef) pair and is permanent. You can also pass it via the Idempotency-Key header — the body value wins.

Invite the merchant to the dashboard

By default, a merchant you create by API is API-only: nobody can log in to it, and it does not appear in the CRM dashboard. To hand the account over to your client, pass email on create() (as above) or invite them later:

const invite = await partner.partners.crm.merchants.invite('acc_xxx', {
  email: 'owner@acme.com',
});
// {
//   merchantId: 'acc_xxx',
//   object: 'merchant_portal_invite',
//   status: 'invited',            // see the four statuses below
//   email: 'owner@acme.com',
//   clerkOrgId: 'org_…',
//   clerkUserId: null,            // set once they are in the organization
//   invitationId: 'orginv_…',     // null unless status is 'invited'
//   emailMode: 'branded',         // sent with YOUR partner branding
// }

If the email already has a TagadaPay account with one of your merchants, nobody is emailed. We add that person to the merchant’s organization on the spot and answer status: 'added'. There is no link, so there is nothing to expire, nothing to click, and no way for them to end up creating a second account by mistake. This is the case that used to hurt: a merchant who had signed up on their own — often into a duplicate organization — could only be reached through a link that had usually already died. Everyone else gets the invitation flow: a brand-new email, and also an existing TagadaPay account that has no organization of yours. Adding someone to an organization is silent, so we only do it for people already inside your account; anyone else has to accept, which keeps you from attaching a stranger who never agreed to it.

The contact receives an invitation email branded with your partner identity (your name, logo and colors from your partner profile — TagadaPay does not appear anywhere in the email), with an accept link.
On acceptance they choose their own password and land in the CRM dashboard. Partners with a dedicated CRM host (e.g. crm.yourbrand.com) get the acceptance page skinned with their brand and the user is dropped onto their host, not TagadaPay’s.
From that point the account behaves like a regular self-serve merchant — dashboard access, notifications, team management.

The four statuses:

`status`	Meaning
`added`	Already had a TagadaPay account with one of your merchants — now in this organization too. No email sent.
`already_member`	Was in the organization already. Nothing changed.
`invited`	Brand-new email, or an account with no organization of yours — invitation sent.
`already_invited`	An invitation for that email is still pending. No second email sent.

The call is idempotent in every direction: repeat it as often as you like, it never fails for work that is already done. Note that sending a new invitation (e.g. after a previous one expired) invalidates earlier links — only the most recent email works.

Developers and team members

role defaults to admin, the merchant’s own contact. Pass member for the developers and team members you add alongside them:

await partner.partners.crm.merchants.invite('acc_xxx', {
  email: 'dev@acme.com',
  role: 'member',
});

One email, one person. If several TagadaPay users share the address you pass, we refuse with 409 ambiguous_email rather than guess which one to add to your merchant’s organization. Contact your account manager to get them merged.

Branding comes from your partner profile. The email name, logo, colors, dashboard host and reply-to address are configured once on your partner profile by your TagadaPay account manager. Until they’re set, the email falls back to your partner name with a neutral look. Optionally, configure your own DKIM-verified sending domain so even the technical From address is yours.

Silent merchants stay silent. If your partner agreement uses the silent-merchant model (Tagada never contacts your merchants directly — merchantPortalAccess: 'never'), invites are rejected with 403 portal_access_never. Contact your account manager to change the policy.

Retrieve / list

const merchant = await partner.partners.crm.merchants.retrieve('acc_xxx');
const byRef = await partner.partners.crm.merchants.retrieveByExternalRef('merchant_42'); // null if none

const { data, hasMore } = await partner.partners.crm.merchants.list({
  limit: 50,
  cursor: '…',
  externalRef: 'merchant_42', // optional filter
});

Mint a CRM Key

A CRM Key (sk_crm_…) grants access to /api/public/v1/* for this one merchant.

const key = await partner.partners.crm.merchants.keys.create('acc_xxx');
// {
//   object: 'crm_key',
//   id: '…',
//   accountId: 'acc_xxx',
//   prefix: 'sk_crm_live_a1b2…',
//   token: 'sk_crm_live_a1b2c3…',   // RETURNED ONCE — store immediately
//   name: 'Your Partner — merchant_42',
//   createdAt: '2026-04-29T…',
// }

const keys = await partner.partners.crm.merchants.keys.list('acc_xxx');
await partner.partners.crm.merchants.keys.revoke(key.id);

The token is returned only on creation. Store it in your secret manager immediately. Existing UUID tokens keep working — only newly minted keys use the sk_crm_… format.

Use the token as a normal merchant client:

const merchantClient = new Tagada(key.token);    // sk_crm_live_…
const orders = await merchantClient.orders.list();
const customers = await merchantClient.customers.list();

See API keys & authentication for rotation patterns and the full three-key model.

Query the merchant’s data

Once you hold a CRM Key, the client behaves exactly like a merchant’s own key — the whole CRM read surface is available on behalf of that one merchant (acc_xxx). This is what you use to build a merchant dashboard, reconcile orders, or pull reporting into your own backend.

const m = new Tagada(crmKey.token); // sk_crm_live_…

// Stores (a CRM-only merchant has one auto-created store)
const stores = await m.stores.list({ pageSize: 20 });
const storeId = stores.data[0].id;

// Orders — POST /orders/list under the hood, so filter + sort are rich
const orders = await m.orders.list({
  pagination: { page: 1, pageSize: 25 },
  sortBy: { field: 'orders.createdAt', direction: 'desc' },
  filters: { 'orders.status': ['paid'] },      // optional
});
console.log(orders.total, 'orders');            // e.g. 6280

// Payments (with their transactions), and the currencies / processors in use
const payments = await m.payments.list({ pagination: { page: 1, pageSize: 25 } });
const { currencies } = await m.payments.currencies();   // ['USD']
const { processors } = await m.payments.processors();

// Customers
const customers = await m.customers.list({ pageSize: 25 });

// Catalog
const products = await m.products.list({ storeId, page: 1, per_page: 25 });

// Subscriptions (recurring)
const subs = await m.subscriptions.list({ page: 1, per_page: 25 });

// Funnels, payment flows, processors config
const { funnels } = await m.funnels.list(storeId);
const flows = await m.paymentFlows.list();
const procs = await m.processors.list();

events.list on high-volume merchants. The behavioural event stream (app_events) can be very large. Always scope events.list with a storeId and a tight date window, or use events.statistics / events.recent — an unfiltered events.list on a big merchant can time out. For heavy analytics, prefer aggregated reporting over paging raw events.

Every listing returns the same envelope: { data, total, page, pageSize, totalPages, hasMore }. Retrieve single records with orders.retrieve(id), payments.retrieve(id), customers.retrieve(id), products.retrieve(id), etc.

Common errors

HTTP	Code	When
401	`missing_api_key` / `invalid_api_key`	No / unknown / revoked key
403	`partner_scope_required`	Not a Partner Key (e.g. a CRM/Processing key used to provision)
403	`merchant_access_denied`	Merchant exists but belongs to another partner
403	`portal_access_never`	Your partner policy forbids CRM invites (silent-merchant model)
404	`merchant_not_found`	`acc_xxx` does not exist

Next step

Add card processing (TPA)

When this merchant needs to take payments through TagadaPay, provision a TPA bound to its acc_xxx and mint a Processing Key.

Get Started