# Team subscriptions API

> Reference for team subscriptions in the IXO Subscriptions API: who manages a team, setup, member budgets enforced on chain, card top-ups, freezes, every route with its fields, limits and errors.

A team subscription gives an organisation, project or DAO its own pool of IXO credits, shared by the
people it adds as members. Each member gets a spend limit per period, and the IXO Protocol enforces
that limit. Use this page to set up a team, manage its members and budgets, and top it up from your
own application. For what a team subscription means to the people in it, see
[Team subscriptions](/guides/users/team-subscriptions).

## Current limits

Read this before you build on team subscriptions.

- **No service spends a team budget.** The billing engine does not charge team subscriptions. AI
  usage in the QiForge Personal Agent is charged to each person's own credits, not to the team's,
  whatever budget the person has on a team. See
  [Pay for your Personal Agent with credits](/guides/users/personal-agent-credits).
- **API only.** There is no IXO Portal screen for teams. Every step on this page is an API call.
- **No unfreeze route.** A frozen team is unfrozen by IXO support after review.
- **No list of a team's top-ups.** Top-ups are recorded, but no route returns them.

The routes are available on devnet, testnet and mainnet.

## What a team subscription is

- **The team** is an IXO entity, `did:ixo:entity:…`: an organisation, a project or a DAO.
- **The subscription deed.** Setup creates a subscription deed (an entity of type
  `deed/subscription`) for the team. The IXO subscriptions service owns the deed and is its only
  controller. The deed links to the team entity with the relationship `subscriber`. A manager of the
  team does not own the deed.
- **The shared balance.** The deed's admin account holds the team's PAY. 1 credit is 1 PAY, and
  1 PAY is US$1 (1,000,000 `upay`). PAY is internal credit. It cannot be withdrawn: there is no
  route for it, and no manager or member is given permission to send it.
- **Two claim collections.** The deed has a subscription collection, for the service's own top-up
  claims, and an oracle collection, where members' budgets live and where oracles would charge
  usage. The oracle collection requires intents (see [How budgets are enforced on chain](#how-budgets-are-enforced-on-chain)).
- **Managers** set the team up, add and remove members, set budgets and top up. See
  [Who manages a team](#who-manages-a-team).
- **Members** are IXO accounts (`ixo1…`) with a budget on the team's oracle collection. The chain is
  the only record of who is a member. A member needs no role in the team entity.

## Who manages a team

The service decides who manages a team from the team entity's record in IXO Blocksync, on every
request. The caller is a manager when the caller's DID is one of these:

1. a `controller` of the team entity;
2. the entity's `owner`, as `did:ixo:<owner address>`;
3. a `linkedEntity` of the entity with `service` `matrix` and `relationship` `admin`;
4. for a DAO named in 1, 2 or 3 as `did:ixo:wasm:<address>`: an account with positive voting power
   in that DAO. That is a member of its cw4 group with a weight above 0, a staker with a cw20 or
   native token stake above 0, or a staker of an NFT (cw721) in it. The address is also checked as
   a cw4 group in its own right.

Rule 4 is the same DAO membership rule that IXO Matrix rooms and the virtual file store use. Any
stake counts: one staked token unit, or one staked NFT, is enough.

- Fragments (`#…`) are ignored. Entities (`did:ixo:entity:…`) named in these fields are skipped, and
  their own managers are not looked up.
- Every manager has the full manager rights on this page, including setting their own budget. No DAO
  vote is needed.
- At most 25 DAOs are checked. If the entity names more and the caller is not found in the first
  25, the answer is `503`, not `403`.
- A change on chain takes effect within about 3 seconds plus IXO Blocksync's indexing delay. This
  applies to a manager added and to a manager removed.
- If the lookup fails or takes longer than 8 seconds, the answer is `503`. It is never `403` and
  never "allowed". Retry later.

## Call the API

### Base URL

| Network | Base URL |
| --- | --- |
| Mainnet | `https://subscriptions-api-mainnet.ixo-api.workers.dev` |
| Testnet | `https://subscriptions-api-testnet.ixo-api.workers.dev` |
| Devnet | `https://subscriptions-api.ixo-api.workers.dev` |

Every team route is under `/api/v1/teams/{teamEntityDid}/`. `teamEntityDid` must match
`did:ixo:entity:[A-Za-z0-9]+`. Any other value is `422`.

### Authentication

Send a User Controlled Authorization Network (UCAN) invocation as a bearer token:

```http
Authorization: Bearer <UCAN invocation>
X-Auth-Type: ucan
```

- The invocation must be rooted in an IXO account DID, `did:ixo:ixo1…`. Any other root is `403`.
- Its capability is `{ "with": "ixo:subscriptions", "can": "*" }`, and it must declare only that one
  capability.
- Its audience is the service's `did:web` for the host you call, published at
  `/.well-known/did.json` on that host.
- No token, or a token that does not validate, is `401`.

The service acts only as the account the invocation is rooted in. A route never takes the caller's
address from the request body or path.

### Amounts and errors

- Budget amounts are integers in micro-USD (`upay`). In responses they are strings. 1 PAY is
  1,000,000.
- An error body is `{ "message": "…" }`. A schema error is `422` with
  `{ "error", "message", "status": 422 }`. An authentication error is `{ "error": "…" }`.
- `502` and `503` are returned as they are. Any other `5xx` becomes a generic `500`.

### Rate limits

| Limit | Applies to | Over the limit |
| --- | --- | --- |
| 20 requests per 60 seconds per caller account | `POST`, `PUT` and `DELETE` under `/api/v1/teams/` | `429 { "message": "Too many team changes; try again in a minute" }` |
| 600 requests per 60 seconds per IP address | Every route | `429 { "message": "Rate limit exceeded", "status": 429 }` |

The team limit is checked after authentication and before the body is validated. Reads do not count
towards it.

## Set up a team

<Steps>
  <Step title="Start setup">
    A manager calls `POST /api/v1/teams/{teamEntityDid}/subscription`. The answer is `202` with
    `{ "setupStatus": "in_progress" }`. Setup runs in the background. It creates the deed, its two
    claim collections and the grants they need, in three transactions signed by the service.
  </Step>

  <Step title="Wait for it to finish">
    Call `GET /api/v1/teams/{teamEntityDid}/subscription` every few seconds until `status` is
    `active` or `failed`.
  </Step>

  <Step title="Retry a failed setup">
    If `status` is `failed`, call `POST …/subscription` again. A new run reuses the deed and the
    collections already created, and sends only what is missing.
  </Step>
</Steps>

The team is set up when `status` is `active` and `claimCollections` holds both collection ids.

## Manage members and budgets

A budget is a spend limit per period, in micro-USD.

- **Period:** 86,400 seconds (24 hours, the chain's minimum) to 31,622,400 seconds (366 days).
- **Limit:** 1 to 1,000,000,000,000 micro-USD (1,000,000 PAY) per period.
- **A new member** starts with nothing spent. Their first period ends one period after the block
  that added them.
- **Changing an existing member** replaces the limit and the period. What they spent in the current
  period, and the end of that period, stay. A lower limit can leave nothing to spend until the
  period ends.
- **`resetSpent: true`** starts a fresh period now, with nothing spent.
- **Period reset.** The chain resets a period only when the next charge arrives. The API applies the
  reset when it answers: once the period has ended, spent shows as 0 and `periodResetAt` moves to
  the end of the current period. The API uses its own clock, so right at the end of a period it can
  differ by a few seconds from the chain.
- **Removing a member** deletes their budget on chain and removes their permission to authorise
  oracles against the team. Oracle authorisations the member already created stay on chain, but
  cannot spend: a charge for a member without a budget fails.
- **Removing and adding the same member again.** Their old oracle authorisations match again and can
  spend from the new budget. If they had charges in progress when removed, the amounts returned for
  those charges are applied to the new budget. Avoid removing a member who has charges in progress.

A team has at most 100 members. One request adds, updates or removes at most 25. Each request is one
transaction on chain. Only one member change runs at a time for each team.

## How budgets are enforced on chain

Member budgets are a feature of the Claims module of the IXO Protocol (`x/claims`), on the team's
oracle collection. This is how the chain uses them:

1. A new member gets a grant that lets them authorise an oracle against the team's oracle
   collection, tagged with their own address. They do this with `MsgCreateClaimAuthorization`,
   with `memberAddress` set to their own address.
2. An oracle charges usage by opening an intent (`MsgClaimIntent`) with `memberAddress` set to the
   member. The chain checks the member's budget, resets the period if it has ended, and adds the
   amount to what the member spent.
3. The oracle submits the claim against that intent. When the claim is approved, the payment comes
   from the team's admin account.
4. If the claim is rejected or the intent expires, the amount goes back to the member's budget.

The oracle collection requires intents. A claim submitted without one is refused, so no charge can
skip the budget check.

## Top up a team

A manager pays by card for the team. The credits go to the team's admin account, not to the
manager's own subscription.

1. Call `POST /api/v1/teams/{teamEntityDid}/payments/intent` with the amount.
2. Confirm the payment with Stripe in your client, using `clientSecret`. If you sent a saved
   `paymentMethodId`, the payment is confirmed when it is created.
3. When Stripe confirms the payment, the service credits the amount to the team in PAY.

- The amount is a whole number of US dollars, 1 to 10,000.
- The card is charged the amount plus a card service fee. Only the amount is credited.
- The manager pays with their own Stripe customer. Saved cards work as for a personal purchase.
  Promo codes are not accepted.
- Each Stripe payment is credited once. A repeated delivery of the same Stripe event does not
  credit it again.

## Freeze after a card dispute

A card dispute (`charge.dispute.created`) or a refund (`charge.refunded`) on a team payment freezes
the team. The payer's personal subscription is not affected.

| While a team is frozen | |
| --- | --- |
| Refused with `409` | `PUT …/members` and `POST …/payments/intent` |
| Still allowed | `DELETE …/members`, every read, `POST …/subscription` |
| Not stopped | Spending of existing budgets on chain. A payment intent created before the freeze and paid after it is still credited |

There is no route to unfreeze a team. Contact [support@ixo.world](mailto:support@ixo.world).

## Routes

| Method | Path | Who |
| --- | --- | --- |
| `GET` | `/api/v1/teams/{teamEntityDid}/subscription` | A manager or a member |
| `POST` | `/api/v1/teams/{teamEntityDid}/subscription` | A manager |
| `GET` | `/api/v1/teams/{teamEntityDid}/members` | A manager |
| `GET` | `/api/v1/teams/{teamEntityDid}/members/{address}` | A manager, or the member reading their own budget |
| `PUT` | `/api/v1/teams/{teamEntityDid}/members` | A manager |
| `DELETE` | `/api/v1/teams/{teamEntityDid}/members` | A manager |
| `POST` | `/api/v1/teams/{teamEntityDid}/payments/intent` | A manager |

### The budget object

Every member route returns budgets in this shape.

```json
{
  "address": "ixo1kx8manv7l0znk3qwqy6sg306l76l8ehc42vfet",
  "periodSeconds": 2592000,
  "limitMicroUsd": "50000000",
  "spentMicroUsd": "1200000",
  "remainingMicroUsd": "48800000",
  "periodResetAt": "2026-12-16T09:30:00.000Z"
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `address` | string | The member's account address |
| `periodSeconds` | integer | Length of a period, in seconds |
| `limitMicroUsd` | string | Spend limit per period, in micro-USD |
| `spentMicroUsd` | string | Spent in the current period, in micro-USD |
| `remainingMicroUsd` | string | Limit minus spent, never below 0 |
| `periodResetAt` | string or null | When the current period ends (ISO 8601). Can be null right after a `PUT`, see below |

### GET /subscription

Returns the team's subscription as the caller may see it. The caller must be a manager or a member.

| Field | Type | Meaning |
| --- | --- | --- |
| `teamEntityDid` | string | The team entity |
| `deedDid` | string or null | The team's subscription deed. Null until it is created |
| `setupStatus` | string | `in_progress`, `completed` or `failed` |
| `role` | string | `manager` or `member`. A manager who is also a member is `manager` |
| `claimCollections` | object | `oracleClaimsCollectionId` and `subscriptionClaimsCollectionId`. Empty until setup is complete |
| `totalCredits` | number | The team's balance, in credits |
| `status` | string | After setup: `active` or `inactive` (the deed's status). Before: `processing`, or `failed` |
| `adminAddress` | string | The deed's admin account, which holds the team's PAY. Empty until setup is complete |
| `memberBudget` | object | The caller's own budget. Present only when the caller is a member |

| Code | Meaning |
| --- | --- |
| `200` | The subscription |
| `401` | Not authenticated |
| `403` | Neither a manager nor a member. A caller who is not a manager also gets `403` when the team has no subscription or the entity does not exist |
| `404` | A manager asked about a team with no subscription. Rarely, the deed is not indexed yet: retry |
| `422` | `teamEntityDid` is not valid |
| `503` | The caller's role could not be checked. Retry |

### POST /subscription

Starts setup, or reports on it. No body. The answer is always `202 { "setupStatus": "…" }`.

| Situation | What happens | `setupStatus` |
| --- | --- | --- |
| Never set up, or the last run failed | A new run starts | `in_progress` |
| A run is in progress | Nothing new starts | `in_progress` |
| A run stopped without reporting for 15 minutes | A new run takes over | `in_progress` |
| Setup is complete | Nothing new starts | `completed` |

The call is idempotent: repeating it never creates a second team subscription.

| Code | Meaning |
| --- | --- |
| `202` | `{ "setupStatus" }` after this call |
| `401` | Not authenticated |
| `403` | Not a manager. Nothing is written |
| `404` | The entity does not exist. Nothing is written |
| `422` | `teamEntityDid` is not valid |
| `429` | Team write limit |
| `500` | Setup could not be started. Call again |
| `503` | The manager check failed. Nothing is written. Retry |

### GET /members

Lists one page of the team's member budgets, read from the chain. Manager only.

| Query parameter | Meaning |
| --- | --- |
| `limit` | Page size, 1 to 100. Default 100 |
| `paginationKey` | `nextPaginationKey` from the previous page |

The pagination key is standard base64 and can contain `+`, `/` and `=`. URL-encode it, for example
with `encodeURIComponent`. An unencoded `+` arrives as a space and is refused with `422`.

Response: `{ "members": [<budget>, …], "nextPaginationKey": "…" }`. `nextPaginationKey` is null on
the last page.

| Code | Meaning |
| --- | --- |
| `200` | One page |
| `400` | `paginationKey` is not a key from a previous page |
| `401` | Not authenticated |
| `403` | Not a manager |
| `404` | Entity not found, or the deed is not indexed yet |
| `409` | No team subscription, or setup is not complete |
| `422` | `limit` out of range, or `paginationKey` is not base64 |
| `503` | The manager check or a chain read failed. Retry |

### GET /members/\{address\}

Returns one member's budget. A manager can read any member. A member can read their own budget.

When `address` is the caller's own address, the service does not check whether the caller is a
manager. That read answers `404` for anyone who is not a member, whatever state the team is in, so it
reveals nothing about the team.

| Code | Meaning |
| --- | --- |
| `200` | The budget |
| `401` | Not authenticated |
| `403` | Reading another account's budget without being a manager |
| `404` | Not a member, or the entity was not found |
| `409` | Manager reads only: no team subscription, or setup is not complete |
| `422` | `teamEntityDid` or `address` is not valid |
| `503` | The manager check or a chain read failed. Retry |

### PUT /members

Adds new members and updates existing ones, in one transaction. Manager only. Refused while the team
is frozen.

```json
{
  "members": [
    {
      "address": "ixo1kx8manv7l0znk3qwqy6sg306l76l8ehc42vfet",
      "periodSeconds": 2592000,
      "limitMicroUsd": 50000000,
      "resetSpent": false
    }
  ]
}
```

| Field | Type | Rules |
| --- | --- | --- |
| `members` | array | 1 to 25 entries. No address twice |
| `address` | string | A lower-case `ixo1…` account address with a valid checksum |
| `periodSeconds` | integer | 86,400 to 31,622,400 |
| `limitMicroUsd` | integer | 1 to 1,000,000,000,000 |
| `resetSpent` | boolean | Optional. Default `false`. `true` starts a fresh period now |

Response: `{ "members": [<budget>, …], "transactionHash": "…" }`, one budget for each entry, in the
order you sent them. If the service cannot read a budget from the transaction's events, it computes
it from what it wrote. A fresh period then shows spent 0 and `periodResetAt` null.

Sending the same body again sets the same budgets. Take care with `resetSpent: true`: it starts
another fresh period each time.

| Code | Meaning |
| --- | --- |
| `200` | The budgets and the transaction hash |
| `400` | A bad address checksum, an address twice, or a value out of range |
| `401` | Not authenticated |
| `403` | Not a manager |
| `404` | Entity not found, or the deed is not indexed yet |
| `409` | No team subscription, setup not complete, the team is frozen, another member change is in progress, the change would take the team over 100 members, or the team already has more than 100 |
| `422` | Schema error, including more than 25 entries |
| `429` | Team write limit |
| `502` | See [Failed member changes](#failed-member-changes) |
| `503` | The manager check or a chain read failed, or the change took too long to prepare and was not sent. Retry |

### DELETE /members

Removes members, in one transaction. Manager only. Allowed while the team is frozen.

```json
{ "addresses": ["ixo1kx8manv7l0znk3qwqy6sg306l76l8ehc42vfet"] }
```

`addresses` holds 1 to 25 addresses, with no address twice. Every address must be a member.
Otherwise the answer is `404` naming the addresses that are not, and nothing is removed.

Response: `{ "removed": ["ixo1…"], "transactionHash": "…" }`.

Repeating a removal that succeeded answers `404`, because the address is no longer a member.

| Code | Meaning |
| --- | --- |
| `200` | The removed addresses and the transaction hash |
| `400` | A bad address checksum, or an address twice |
| `401` | Not authenticated |
| `403` | Not a manager |
| `404` | Entity not found, or an address is not a member |
| `409` | No team subscription, setup not complete, another member change is in progress, or the team has more than 100 members |
| `422` | Schema error |
| `429` | Team write limit |
| `502` | See [Failed member changes](#failed-member-changes) |
| `503` | The manager check or a chain read failed, or the change was not sent in time. Retry |

### POST /payments/intent

Creates a Stripe payment intent that tops up the team. Manager only. The team must be set up and not
frozen.

| Field | Type | Meaning |
| --- | --- | --- |
| `amount` | integer | US dollars to credit, 1 to 10,000 |
| `paymentMethodId` | string | Optional. A saved card. When set, the payment is confirmed when it is created |
| `setAsDefault` | boolean | Optional. Default `false`. Makes `paymentMethodId` your default card |

| Response field | Type | Meaning |
| --- | --- | --- |
| `setupIntentId` | string | The Stripe payment intent id |
| `clientSecret` | string | Pass it to Stripe in your client to confirm the payment |
| `requiresAction` | boolean | `true` when Stripe reports the payment intent as `requires_action`: the card holder must complete a further step, such as 3-D Secure |
| `serviceFee` | number | The card service fee, in US dollars |
| `amountCharged` | number | What the card is charged: `amount` plus `serviceFee` |

Each call creates a new payment intent. Do not repeat a call to retry a payment: confirm the intent
you already have.

| Code | Meaning |
| --- | --- |
| `200` | The payment intent |
| `400` | The saved payment method can no longer be used. Remove the card and add it again |
| `401` | Not authenticated |
| `402` | The card was declined. The message comes from Stripe and can be shown to the user |
| `403` | Not a manager |
| `404` | Entity not found |
| `409` | Setup is not complete, or the team is frozen |
| `422` | Schema error, including an amount that is not a whole number from 1 to 10,000 |
| `429` | Team write limit |
| `500` | Any other Stripe error |
| `503` | The manager check failed. Retry |

## Failed member changes

A `PUT` or `DELETE` on members can fail in three ways.

| Answer | Meaning | What to do |
| --- | --- | --- |
| `502` "The member change could not be completed on chain; try again shortly" | Nothing changed | Retry |
| `502` "The member change was sent to the chain but could not be confirmed, so it may still apply. …" | The transaction was sent and may still land | Wait about 2 minutes. Read `GET …/members`. Repeat the change only if it did not apply |
| `503` "The member change took too long to prepare and was not sent; try again shortly" | Nothing was sent | Retry |

After a change whose outcome is unknown, the team's member changes stay locked for 2 minutes from
when the change started, so the pending transaction can land first. A change in that time gets
`409`. The transaction carries no timeout, so landing within 2 minutes is likely but not certain.

## Next steps

<CardGroup cols={2}>
  <Card title="Team subscriptions for people" icon="users" href="/guides/users/team-subscriptions">
    What a team subscription means for a member and for a manager.
  </Card>
  <Card title="Personal Agent credits" icon="coins" href="/guides/users/personal-agent-credits">
    How the Personal Agent charges each person's own credits.
  </Card>
  <Card title="How claim disputes work on chain" icon="scale-balanced" href="/guides/dev/claim-disputes">
    Claims, intents and evaluation in the Claims module.
  </Card>
  <Card title="What works today" icon="table" href="/status">
    What is available on which network.
  </Card>
</CardGroup>
