Organizations API

Organizations represent multi-tenant accounts in the Fanfare platform. These endpoints allow you to manage organization settings and configuration.

Get Current Organization

Get the current organization details. GET /api/v1/organizations/current

Authentication

Secret key required

Response

interface Organization {
  id: string;
  name: string;
  slug: string;
  logoUrl: string | null;
  faviconUrl: string | null;
  timeZone: string;
  countryCode: string;
  languageCode: string;
  currencyCode: string;
  status: "ACTIVE" | "INACTIVE" | "PENDING";
  plan: "FREE" | "STARTER" | "GROWTH" | "ENTERPRISE";
  clerkOrganizationId: string;
  createdAt: string;
  updatedAt: string;
}

Example

curl -X GET https://admin.fanfare.io/api/v1/organizations/current \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Response:

{
  "id": "org_01HXYZ123456789",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "logoUrl": "https://cdn.fanfare.io/orgs/acme/logo.png",
  "faviconUrl": null,
  "timeZone": "America/New_York",
  "countryCode": "US",
  "languageCode": "en",
  "currencyCode": "USD",
  "status": "ACTIVE",
  "plan": "GROWTH",
  "clerkOrganizationId": "org_clerk_123456",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-12-01T15:30:00Z"
}

Error Responses

Status	Error	Description
404	`Organization not found`	Organization does not exist

Update Organization

Update organization details. PUT /api/v1/organizations

Authentication

Secret key required

Request Body

interface UpdateOrganizationRequest {
  name?: string;
  slug?: string;
  logoUrl?: string | null;
  faviconUrl?: string | null;
  timeZone?: string;
  countryCode?: string;
  languageCode?: string;
  currencyCode?: string;
}

Example

curl -X PUT https://admin.fanfare.io/api/v1/organizations \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "timeZone": "America/Los_Angeles",
    "currencyCode": "USD"
  }'

Response:

{
  "id": "org_01HXYZ123456789",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "logoUrl": "https://cdn.fanfare.io/orgs/acme/logo.png",
  "faviconUrl": null,
  "timeZone": "America/Los_Angeles",
  "countryCode": "US",
  "languageCode": "en",
  "currencyCode": "USD",
  "status": "ACTIVE",
  "plan": "GROWTH",
  "clerkOrganizationId": "org_clerk_123456",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-12-01T16:00:00Z"
}

Error Responses

Status	Error	Description
400	`Slug already taken`	Slug is used by another org
400	`Invalid slug format`	Slug contains invalid chars
400	`Validation failed`	Invalid request data

Check Slug Availability

Check if an organization slug is available. GET /api/v1/organizations/slug/availability

Authentication

Optional (if authenticated, excludes current org from check)

Query Parameters

Parameter	Type	Description
`slug`	string	The slug to check

Response

interface SlugAvailabilityResponse {
  slug: string;
  available: boolean;
  reason?: "TAKEN" | "RESERVED" | "INVALID_FORMAT";
}

Example

curl -X GET "https://admin.fanfare.io/api/v1/organizations/slug/availability?slug=my-brand" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Response (available):

{
  "slug": "my-brand",
  "available": true
}

Response (taken):

{
  "slug": "acme-corp",
  "available": false,
  "reason": "TAKEN"
}

Slug Requirements

Organization slugs must follow these rules:

Rule	Description
Length	3-50 characters
Characters	Lowercase letters, numbers, hyphens
Start/End	Must start and end with letter or number
No consecutive hyphens	Cannot contain `--`
Reserved words	Cannot use reserved system slugs

Reserved Slugs

The following slugs are reserved and cannot be used:

admin, api, app, auth
dashboard, settings, account
fanfare, waitify, support
www, mail, ftp, cdn

Organization Settings

Organization settings are managed through a separate Settings API. Common settings include:

Notification Settings

Configure email and SMS notifications:

interface NotificationSettings {
  email: {
    enabled: boolean;
    fromName: string;
    fromEmail: string;
    replyToEmail?: string;
  };
  sms: {
    enabled: boolean;
    fromNumber?: string;
  };
}

Integration Settings

Configure third-party integrations:

interface IntegrationSettings {
  klaviyo?: {
    apiKey: string;
    publicKey: string;
  };
  shopify?: {
    shopDomain: string;
    accessToken: string;
  };
}

See the Settings API for managing these configurations.

Time Zone Support

Fanfare supports all IANA time zones. Common examples:

Time Zone	Description
`America/New_York`	Eastern Time (US)
`America/Los_Angeles`	Pacific Time (US)
`America/Chicago`	Central Time (US)
`Europe/London`	British Time
`Europe/Paris`	Central European
`Asia/Tokyo`	Japan Standard Time
`Australia/Sydney`	Australian Eastern
`UTC`	Coordinated UTC

Time zones affect:

Scheduled experience open/close times
Analytics reporting periods
Notification scheduling
Dashboard displays

Currency Support

Fanfare supports all ISO 4217 currency codes:

Code	Currency
`USD`	US Dollar
`EUR`	Euro
`GBP`	British Pound
`CAD`	Canadian Dollar
`AUD`	Australian Dollar
`JPY`	Japanese Yen
`CHF`	Swiss Franc

Currency settings affect:

Product pricing display
Order totals and revenue reporting
Analytics currency conversions

SDK Usage

import { FanfareAdmin } from "@fanfare/admin-sdk";

const admin = new FanfareAdmin({
  secretKey: process.env.FANFARE_SECRET_KEY,
});

// Get current organization
const org = await admin.organizations.getCurrent();
console.log(`Organization: ${org.name} (${org.slug})`);

// Update organization
const updated = await admin.organizations.update({
  name: "Acme Corporation",
  timeZone: "America/Los_Angeles",
});

// Check slug availability
const availability = await admin.organizations.checkSlugAvailability("my-brand");
if (availability.available) {
  await admin.organizations.update({ slug: "my-brand" });
}

Multi-Tenancy

Fanfare is a multi-tenant platform where each organization has completely isolated data:

Resource	Isolation Level
Consumers	Per organization
Experiences	Per organization
Products	Per organization
Orders	Per organization
Audiences	Per organization
API Keys	Per organization
Settings	Per organization
Analytics	Per organization

Organization IDs

All API responses include organizationId to identify the owning organization. This ID is automatically scoped based on your API key.

Cross-Organization Access

Cross-organization access is not supported through the API. Each API key is scoped to exactly one organization.

Overview

Consumer API

Admin API

Webhooks

Organizations API

Organizations API

Get Current Organization

Authentication

Response

Example

Error Responses

Update Organization

Authentication

Request Body

Example

Error Responses

Check Slug Availability

Authentication

Query Parameters

Response

Example

Slug Requirements

Reserved Slugs

Organization Settings

Notification Settings

Integration Settings

Time Zone Support

Currency Support

SDK Usage

Multi-Tenancy

Organization IDs

Cross-Organization Access

Overview

Consumer API

Admin API

Webhooks

Documentation Index

​Organizations API

​Get Current Organization

​Authentication

​Response

​Example

​Error Responses

​Update Organization

​Authentication

​Request Body

​Example

​Error Responses

​Check Slug Availability

​Authentication

​Query Parameters

​Response

​Example

​Slug Requirements

​Reserved Slugs

​Organization Settings

​Notification Settings

​Integration Settings

​Time Zone Support

​Currency Support

​SDK Usage

​Multi-Tenancy

​Organization IDs

​Cross-Organization Access

Organizations API

Get Current Organization

Authentication

Response

Example

Error Responses

Update Organization

Authentication

Request Body

Example

Error Responses

Check Slug Availability

Authentication

Query Parameters

Response

Example

Slug Requirements

Reserved Slugs

Organization Settings

Notification Settings

Integration Settings

Time Zone Support

Currency Support

SDK Usage

Multi-Tenancy

Organization IDs

Cross-Organization Access