# Partners and child organizations

> Create and manage your clients' organizations with a single token using org_id and the orgs:manage scope.

URL: https://docs.proteside.com/en/docs/api/partners

If you're an agency, e-commerce platform or payment gateway protecting the checkout of several clients, use the
partner model: each client becomes a **child organization** of your organization, with separate stores, scripts,
alerts and reports, and you operate all of them with the same token.

The website presents the offering for each case:
[e-commerce platforms](https://proteside.com/en/solutions/ecommerce-platforms),
[PSPs and gateways](https://proteside.com/en/solutions/payment-providers) and the
[partner program](https://proteside.com/en/partners).

## How it works
* Your (partner) organization can have multiple **children**. There's only one level: a child can't create children.
* Each child has its own owner, who receives an email invitation and uses the dashboard as usual.
* Your token still belongs to your organization. To act on a child, you specify which one with `org_id`.
* In the dashboard, members of the partner organization can **view** the children's data, but changes to the children
  are made through the API or by members of the child itself.

## Before you start
Create a token in **Settings → API** with the `orgs:manage` scope and the scopes for the operations you'll perform on
the children (for example `stores:write`, `scripts:review`, `webhooks:manage`, `usage:read`). See
[Tokens and scopes](https://docs.proteside.com/en/docs/api/authentication).

> **The partner organization needs a store of its own**
>
> The dashboard only opens for users who have at least one store. A partner organization with no stores never reaches
> **Settings → API** and can't issue the token. Register a store for your own organization (for example, your website)
> before you start.

## Create a child organization```bash
curl -s -X POST "https://app.proteside.com/api/v1/organizations" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d1f4b2a-0c3e-4a5b-9d6f-1e2a3b4c5d6e" \
  -d '{
    "name": "My Store",
    "owner_email": "you@mystore.com",
    "plan": "business_100k"
  }'
```

```json
{
  "id": "11112222-3333-4444-8555-666677778888",
  "name": "My Store",
  "plan": "business_100k",
  "billing_mode": "partner",
  "parent_org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "owner_email": "you@mystore.com",
  "partner_settings": {},
  "created_at": "2026-10-06T12:05:00.000Z",
  "owner_invite": "sent"
}
```

- `name` (`string`): Organization name, 2 to 120 characters.
- `owner_email` (`string`): Email of the person who will own the child.
- `plan` (`'essential' | 'business_50k' | 'business_100k' | 'business_150k' | 'business_200k' | 'business_250k' | 'business_300k' | 'business_400k' | 'business_500k' | 'enterprise'`), default: `'business_100k'`: The child's plan: essential is Store; business_<n>k is the Business tier by monthly checkout pageview volume.
- `billing_mode` (`'partner' | 'stripe'`), default: `'partner'`: partner: you, the partner, handle billing. stripe: the child subscribes directly, with a 14-day trial.

The `owner_invite` field tells you what happened with the owner:

| Value           | Meaning                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `sent`          | The email had no account; an invitation was sent to set a password                                    |
| `existing_user` | The email already had an account; it was added as the child's owner, **without** a notification email |
| `failed`        | The invitation couldn't be sent; the child was created anyway                                         |
| `skipped`       | The invitation wasn't sent; the child was created anyway                                              |

`billing_mode: "partner"` is available to approved partners; commercial terms are defined by contract. The child
also gets the default approval policies.

> **Scheduled reports depend on the plan**
>
> The **scheduled** PCI DSS report (weekly or monthly) depends on the child's plan. Choose the plan according to the
> reports your client needs.

## Act on a child
Send the child's ID in `org_id`:

* in the **query string**, with any method: `GET /stores?org_id=11112222-…`;
* or in the **JSON body**, with `POST` and `PATCH`: `{"org_id": "11112222-…", "domain": "mystore.com"}`.

With `GET` and `DELETE`, always use the query string. Without `org_id`, the call acts on your own organization.

```bash
CHILD=11112222-3333-4444-8555-666677778888

curl -s "https://app.proteside.com/api/v1/alerts?org_id=$CHILD&status=open" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"
```

| Situation                                                     | Response                 |
| ------------------------------------------------------------- | ------------------------ |
| Token without `orgs:manage`                                   | `403 insufficient_scope` |
| `org_id` isn't a **direct** child of the token's organization | `404 not_found`          |
| `org_id` not in UUID format                                   | `400 invalid_request`    |

`GET /organizations`, `POST /organizations` and `GET /organizations/{id}/usage` ignore `org_id`: the first two always
act on the token's organization, and the usage endpoint uses the `{id}` in the path.

Everything you change in a child is recorded in its audit log with the author `api:<token prefix>`.

## List children and track usage```bash
curl -s "https://app.proteside.com/api/v1/organizations?limit=100" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"

curl -s "https://app.proteside.com/api/v1/organizations/$CHILD/usage" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"
```

Usage always covers the last 7 months (the current one and the 6 before it), from most recent to oldest, with zeros
for months with no usage. The counters are updated in real time:

```json
{
  "org_id": "11112222-3333-4444-8555-666677778888",
  "months": [
    {
      "period_month": "2026-10-01",
      "payment_pageviews": 18420,
      "events": 91234,
      "alerts": 12,
      "synthetic_runs": 4,
      "stores": [
        {
          "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
          "payment_pageviews": 18420,
          "events": 91234,
          "alerts": 12,
          "synthetic_runs": 4
        }
      ]
    }
  ]
}
```

The `{id}` can be your own organization or a child. This endpoint requires `usage:read` (not `orgs:manage`).

## Shared rate limit
The 120-requests-per-minute limit applies to **your** organization (the token owner) and adds up the calls made on
all children. If you sync many clients, spread the calls out over time and respect `Retry-After`. See
[Conventions](https://docs.proteside.com/en/docs/api/conventions#limite-de-requisi%C3%A7%C3%B5es).

> **One Idempotency-Key per operation**
>
> Generate a new `Idempotency-Key` (for example, a UUID) for each operation, including in each child. Reuse the same
> key only to repeat exactly the same request.

## Webhooks in children
A child's events only go to **the child's own** channels. A webhook created in your organization doesn't receive alerts
from the children's stores. Create a webhook in each child:

```bash
curl -s -X POST "https://app.proteside.com/api/v1/webhooks?org_id=$CHILD" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ops.parceiro.example/hooks/proteside", "min_severity": "medium"}'
```

You can use the same URL for all children. To know which client each event came from, use the envelope's `org_id`.
Each webhook has its own secret, so keep each child's secret or send your own `secret` when creating it. Details in
[Webhooks](https://docs.proteside.com/en/docs/api/webhooks).

## Limitations
* There are no endpoints to view, update or delete a specific child: only list (`GET /organizations`) and create
  (`POST /organizations`). The plan and name chosen at creation can't be changed through the API.
* You can't create tokens for a child through the API. The child's owner can create their own tokens in the
  dashboard.
* A suspended store (`DELETE /stores/{id}`) can't be reactivated through the API.

## Next steps
- [Recipe: store in a child](https://docs.proteside.com/en/docs/api/recipes#parceiro-criar-uma-loja-numa-organiza%C3%A7%C3%A3o-filha): From creating the child to the SDK snippet.
- [Reference: organizations](https://docs.proteside.com/en/docs/api/reference/organizations/createOrganization): Fields and responses for the organization endpoints.
