> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bill a client

> Email your client a payment link. They pay you monthly, and need no Orgo account.

The email comes from your business, and checkout carries your business name, logo, and color. Set up payouts once in **Settings → Invoicing** first.

Orgo keeps the client’s computer cost and any AI amount, and Stripe takes its card fee (2.9% + 30¢). The rest is paid out to you. While they pay, their computers don’t count against your plan, and each paid month adds `ai_usd` to your credits and caps their AI at it.

Use your account-wide API key. A client’s own key gets `403` here. See [Invoicing](/guides/invoicing).

## Path parameters

<ParamField path="id" type="string" required>
  The client’s `id`.
</ParamField>

## Body

<ParamField body="email" type="string" required>
  Where to send the link.
</ParamField>

<ParamField body="price_usd" type="number" required>
  What they pay each month. At least their computers’ cost.
</ParamField>

<ParamField body="ai_usd" type="number">
  A monthly amount of AI they pay for at cost, as its own line.
</ParamField>

<ParamField body="setup_fee_usd" type="number">
  Charged once, with the first month.
</ParamField>

## Response

<ResponseField name="billing" type="object">
  As [Get billing](/api-reference/clients/get-billing), with `status` `sent` and the `payment_link_url`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/v1/accounts/$CLIENT_ID/billing \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "billing@acme.com", "price_usd": 250, "ai_usd": 40, "setup_fee_usd": 2500}'
  ```

  ```python Python theme={null}
  import os
  import requests

  client_id = os.environ["CLIENT_ID"]

  res = requests.post(
      f"https://www.orgo.ai/api/v1/accounts/{client_id}/billing",
      headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
      json={"email": "billing@acme.com", "price_usd": 250, "ai_usd": 40, "setup_fee_usd": 2500},
  )
  print(res.json())
  ```

  ```javascript JavaScript theme={null}
  const clientId = process.env.CLIENT_ID;

  const res = await fetch(`https://www.orgo.ai/api/v1/accounts/${clientId}/billing`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({"email": "billing@acme.com", "price_usd": 250, "ai_usd": 40, "setup_fee_usd": 2500}),
  });
  console.log(await res.json());
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "billing": {
    "status": "sent",
    "email": "billing@acme.com",
    "price_usd": 250,
    "setup_fee_usd": 2500,
    "ai_usd": 40,
    "payment_link_url": "https://buy.stripe.com/…",
    "current_period_end": null,
    "ends_at_period_end": false
  }
}
```

## Errors

| Status | Body | Meaning |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | No key, or not one of yours. |
| `403` | `{ "error": "Use your account-wide API key to manage accounts. Workspace keys can’t." }` | A client’s own key, or any key scoped to one workspace. |
| `403` | `{ "error": "Invoicing is on every paid plan. Upgrade to use it." }` | You’re on the Free plan. `code` is `UPGRADE_REQUIRED`. |
| `400` | `{ "error": "price_usd is required: what they pay each month." }` | Missing price. |
| `400` | `{ "error": "Set a price of at least $50, your cost." }` | The price doesn’t cover their computers. |
| `409` | `{ "error": "Set up payouts first." }` | Payouts aren’t set up. |
| `409` | `{ "error": "Your client is already paying for this workspace." }` | Change the price instead. |
| `404` | `{ "error": "Account not found." }` | No client with this id is yours. |
| `409` | `{ "error": "This account is closed." }` | The client is closed. `code` is `ACCOUNT_CLOSED`. |
| `409` | `{ "error": "This account was transferred to your client." }` | The client accepted a transfer and owns it now. `code` is `ACCOUNT_TRANSFERRED`. |


## OpenAPI

````yaml POST /v1/accounts/{id}/billing
openapi: 3.1.0
info:
  title: Orgo API
  description: >-
    Launch cloud computers that AI agents can control and interact with. Create
    workspaces, provision computers, and control them programmatically.
  version: 2.0.0
  contact:
    name: Orgo Support
    email: spencer@orgo.ai
    url: https://orgo.ai
servers:
  - url: https://www.orgo.ai/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account capacity: how many computers an account may run, and adding or
      giving back more.
  - name: Clients
    description: >-
      Run Orgo for your clients from your own app: a workspace and scoped key
      each, billed to you or to them.
  - name: Workspaces
    description: Organize computers into named workspaces
  - name: Computers
    description: Provision and manage virtual computers
  - name: Computer Lifecycle
    description: Start, stop, and restart computers
  - name: Computer Actions
    description: Control mouse, keyboard, and execute commands
  - name: Screens
    description: >-
      More than one desktop on a single computer. Each screen is its own X
      server with its own cursor and window manager, so an agent working on one
      cannot disturb another.
  - name: Files
    description: Upload and download files
  - name: Templates
    description: Author, build, and launch reproducible computers from templates
paths:
  /v1/accounts/{id}/billing:
    post:
      tags:
        - Clients
      summary: Bill a client
      description: >-
        Email your client a payment link. They pay you monthly, and need no Orgo
        account.
      operationId: sendClientPaymentLink
      parameters:
        - name: id
          in: path
          required: true
          description: The client’s `id`.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Where to send the link.
                price_usd:
                  type: number
                  description: What they pay each month. At least their computers’ cost.
                ai_usd:
                  type: number
                  description: >-
                    A monthly amount of AI they pay for at cost, as its own
                    line.
                setup_fee_usd:
                  type: number
                  description: Charged once, with the first month.
              required:
                - email
                - price_usd
            example:
              email: billing@acme.com
              price_usd: 250
              ai_usd: 40
              setup_fee_usd: 2500
      responses:
        '201':
          description: Created
          content:
            application/json:
              example:
                billing:
                  status: sent
                  email: billing@acme.com
                  price_usd: 250
                  setup_fee_usd: 2500
                  ai_usd: 40
                  payment_link_url: https://buy.stripe.com/…
                  current_period_end: null
                  ends_at_period_end: false
              schema:
                $ref: '#/components/schemas/BillingEnvelope'
        '400':
          description: Missing price. The price doesn’t cover their computers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: Missing price
                  value:
                    error: 'price_usd is required: what they pay each month.'
                e2:
                  summary: The price doesn’t cover their computers
                  value:
                    error: Set a price of at least $50, your cost.
        '401':
          description: No key, or not one of yours.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: No key, or not one of yours
                  value:
                    error: Invalid API key
        '403':
          description: >-
            A client’s own key, or any key scoped to one workspace. You’re on
            the Free plan. `code` is `UPGRADE_REQUIRED`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: A client’s own key, or any key scoped to one workspace
                  value:
                    error: >-
                      Use your account-wide API key to manage accounts.
                      Workspace keys can’t.
                e2:
                  summary: You’re on the Free plan
                  value:
                    error: Invoicing is on every paid plan. Upgrade to use it.
        '404':
          description: No client with this id is yours.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: No client with this id is yours
                  value:
                    error: Account not found.
        '409':
          description: >-
            Payouts aren’t set up. Change the price instead. The client is
            closed. `code` is `ACCOUNT_CLOSED`. The client accepted a transfer
            and owns it now. `code` is `ACCOUNT_TRANSFERRED`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: Payouts aren’t set up
                  value:
                    error: Set up payouts first.
                e2:
                  summary: Change the price instead
                  value:
                    error: Your client is already paying for this workspace.
                e3:
                  summary: The client is closed
                  value:
                    error: This account is closed.
                e4:
                  summary: The client accepted a transfer and owns it now
                  value:
                    error: This account was transferred to your client.
components:
  schemas:
    BillingEnvelope:
      type: object
      properties:
        billing:
          type: object
          nullable: true
          properties:
            status:
              type: string
              enum:
                - sent
                - active
                - past_due
            email:
              type: string
            price_usd:
              type: number
            setup_fee_usd:
              type: number
            ai_usd:
              type: number
            payment_link_url:
              type: string
              nullable: true
            current_period_end:
              type: string
              format: date-time
              nullable: true
            ends_at_period_end:
              type: boolean
    Error:
      type: object
      description: >-
        The base error body. Every failure carries `error`; individual endpoints
        add the fields named in the schemas below.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable message.
          example: Access denied
        code:
          type: string
          description: >-
            Machine-readable reason. Present on the failures that define one,
            absent otherwise.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.