# X-CommunityId

> The header that says which community each call happens in and in which community your role is checked. Why no route carries the community in the path, where to find the community id and the errors you get when you forget it.

Memberfy is organized by community, and so is the API: **almost every call needs the `X-CommunityId` header** with the community's id.

```
X-CommunityId: 3562c7a0-0000-0000-0000-000000000000
```

## What it decides

1. **Where** the operation happens: which community the space is created in, the product is listed in, the payout is requested from.
2. **Which role** you have: permission is checked against your profile in **that** community. The same account can be the owner of one community and a member of another; the header picks which one applies.

## The header rules, not the path

**No route carries the community in the path.** Products, coupons, plans, fees, statement, payouts, reports, business information, payout settings and subscription management live at paths without the community id (`/api/products`, `/api/coupons`, `/api/manage/subscriptions`…), and the community comes only from `X-CommunityId`. Without the header, these routes answer `400`.

This isn't a detail: with a single source for the community, there's no way to act in another one by changing an id in the URL.

The exception is the **SuperAdmin acting on another community**, at `/api/admin/communities/{communityId}/fee-overrides/...`: there the id in the path is the target community, not the caller's context. The community's own routes, `PUT` and `DELETE /api/communities/{id}`, `GET /api/communities/{id}/members` and `PATCH /api/communities/{id}/settings`, carry the `id` because the community is the resource itself; the header is still required on them.

> [!WARNING]
> **Changed on October 6, 2026.** The old `/api/communities/{communityId}/...` paths (products, coupons, plans, fees, statement, payouts, reports, subscriptions, purchases, checkout, business information, payout settings) were removed, with no transition period, and answer `404`. Switch to the same path without the prefix, under `/api/...`; team subscription management moved to `/api/manage/subscriptions`, and e-mail stats to `/api/emails/stats`. The SDK method names didn't change. See [The paths that changed](#the-paths-that-changed).

Some older routes also ask for `communityId` in the **body** (creating a course, inviting members). Send the same id as in the header.

## The paths that changed

On October 6, 2026, each path below lost the `/api/communities/{communityId}` prefix. HTTP methods, parameters, bodies, responses and required roles stay the same.

| Before | After |
|---|---|
| `/api/communities/{communityId}/products/...` | `/api/products/...` |
| `/api/communities/{communityId}/coupons/...` | `/api/coupons/...` |
| `/api/communities/{communityId}/subscription-groups/...` (including `reorder` and `downsell-offers`) | `/api/subscription-groups/...` |
| `/api/communities/{communityId}/fees` and `.../fees/simulate` | `/api/fees` and `/api/fees/simulate` |
| `/api/communities/{communityId}/ledger/...` | `/api/ledger/...` |
| `/api/communities/{communityId}/payouts/...` | `/api/payouts/...` |
| `/api/communities/{communityId}/reports/...` | `/api/reports/...` |
| `/api/communities/{communityId}/business-information/...` | `/api/business-information/...` |
| `/api/communities/{communityId}/payout-settings/...` | `/api/payout-settings/...` |
| `/api/communities/{communityId}/subscriptions` (team management: list, export, create, detail, cancel, reactivate, discount, add-ons, extend, payment link) | `/api/manage/subscriptions/...` |
| `/api/communities/{communityId}/subscriptions/me` | `/api/subscriptions/me` |
| `/api/communities/{communityId}/purchases/me` | `/api/purchases/me` |
| `/api/communities/{communityId}/checkout/...` | `/api/checkout/...`, which already existed with the same paths |
| `/webhooks/email/stats/{communityId}` | `/api/emails/stats` (owner or admin) |

The [SDK](/api/sdk-js) method names and the [reference](/api/referencia) pages stay the same, because each route kept its `operationId`: `/api/products` is still `api.products.postCommunitiesByCommunityIdProducts`. Only the nine nested checkout operations are gone; use the ones under `/api/checkout/*`.

## Where to find the community id

| Call | What it returns |
|---|---|
| `GET /api/communities/my` | Your account's communities, with the `id` and your role in each one |
| `GET /api/profiles/my` | Your profiles, one per community |

```bash
curl -s https://api.memberfy.net/api/communities/my \
  -H "Authorization: Bearer $TOKEN"
```

## The errors you get when you forget it

| Situation | Response |
|---|---|
| No header, or a value that isn't a valid id | `400` · *Send the community in the X-CommunityId header.*, with `errors[0].param = "X-CommunityId"` |
| The header names a community you're not in | `403` · *Você não é membro desta comunidade.* (you are not a member of this community) |
| An old path, with `/communities/{communityId}/` | `404` |
| The resource belongs to another community | `404`: for the header's community, it doesn't exist |

A `400` from a missing header is the number one cause of API errors.

## Example

```bash
curl -s https://api.memberfy.net/api/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID"
```

## In the SDK

Call `api.setCommunity('<uuid>')` once, and the SDK sends the header on every call. To switch communities, call `setCommunity` again. See [JavaScript SDK](/api/sdk-js).

## Frequently asked questions

**Can one integration serve two communities?**
Yes, with an account that has a role in both: change the header on each call.

**Do the authentication routes need the header?**
No: sign-in, sign-up and `GET /api/auth/me` work without it.

## Related

- [Authentication](/api/autenticacao)
- [Community](/conceitos/comunidade)
- [Responses and errors](/api/respostas-e-erros)