> ## 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.

# Refund a payment

> Refund a client’s payment in full.

The money comes back from your side, Orgo returns its fee, and the AI credits that month added are taken back.

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>

<ParamField path="payment_id" type="string" required>
  The payment’s `id` from [List payments](/api-reference/clients/list-payments).
</ParamField>

## Response

<ResponseField name="refunded" type="boolean">
  `true`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/v1/accounts/$CLIENT_ID/billing/payments/$PAYMENT_ID/refund \
    -H "Authorization: Bearer $ORGO_API_KEY"
  ```

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

  client_id = os.environ["CLIENT_ID"]
  payment_id = os.environ["PAYMENT_ID"]

  res = requests.post(
      f"https://www.orgo.ai/api/v1/accounts/{client_id}/billing/payments/{payment_id}/refund",
      headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
  )
  print(res.json())
  ```

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

  const res = await fetch(`https://www.orgo.ai/api/v1/accounts/${clientId}/billing/payments/${paymentId}/refund`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
  });
  console.log(await res.json());
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "refunded": true
}
```

## 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`. |
| `404` | `{ "error": "Payment not found." }` | Not one of this client’s payments. |
| `409` | `{ "error": "That payment is already refunded." }` | Nothing left to refund. |
| `409` | `{ "error": "That payment hasn’t gone through, so there’s nothing to refund." }` | It was never paid. |
| `404` | `{ "error": "Account not found." }` | No client with this id is yours. |


## OpenAPI

````yaml POST /v1/accounts/{id}/billing/payments/{payment_id}/refund
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/payments/{payment_id}/refund:
    post:
      tags:
        - Clients
      summary: Refund a payment
      description: Refund a client’s payment in full.
      operationId: refundClientPayment
      parameters:
        - name: id
          in: path
          required: true
          description: The client’s `id`.
          schema:
            type: string
        - name: payment_id
          in: path
          required: true
          description: >-
            The payment’s `id` from [List
            payments](/api-reference/clients/list-payments).
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                refunded: true
        '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: Not one of this client’s payments. No client with this id is yours.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: Not one of this client’s payments
                  value:
                    error: Payment not found.
                e2:
                  summary: No client with this id is yours
                  value:
                    error: Account not found.
        '409':
          description: Nothing left to refund. It was never paid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: Nothing left to refund
                  value:
                    error: That payment is already refunded.
                e2:
                  summary: It was never paid
                  value:
                    error: >-
                      That payment hasn’t gone through, so there’s nothing to
                      refund.
components:
  schemas:
    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.