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

# External Billing

> Configure external billing for your HoopAI Platform marketplace app

# External Billing

The billing webhook enables developers to process payments for externally-billed apps in the HoopAI Platform marketplace. It is essential for externally billed apps within the marketplace.

## Prerequisites

Before implementation, you must:

* Configure your app with a **Paid** business model
* Enable **External Billing** in marketplace settings
* Provide a **Billing URL** endpoint

## Installation Flow

When users install your app, they are redirected to your Billing URL with the following query parameters:

| Parameter     | Description                  |
| ------------- | ---------------------------- |
| `clientId`    | Your app's client ID         |
| `installType` | Type of installation         |
| `locationId`  | The location being installed |
| `companyId`   | The company ID               |

## Webhook Implementation

After processing payment, send a `POST` request to:

```
https://services.leadconnectorhq.com/oauth/billing/webhook
```

### Authentication Headers

| Header            | Description              |
| ----------------- | ------------------------ |
| `x-client-key`    | Your app's client key    |
| `x-client-secret` | Your app's client secret |

### Request Payload

| Field         | Type   | Required    | Description                            |
| ------------- | ------ | ----------- | -------------------------------------- |
| `clientId`    | string | Yes         | Your app's client ID                   |
| `authType`    | string | Yes         | `location` or `company`                |
| `amount`      | number | Yes         | Payment amount                         |
| `status`      | string | Yes         | `COMPLETED` or `FAILED`                |
| `paymentType` | string | Yes         | `one_time` or `recurring`              |
| `locationId`  | string | Conditional | Required when `authType` is `location` |
| `companyId`   | string | Conditional | Required when `authType` is `company`  |

### Example Request

```json theme={null}
{
  "clientId": "your-client-id",
  "authType": "location",
  "amount": 49.99,
  "status": "COMPLETED",
  "paymentType": "recurring",
  "locationId": "abc123locationId"
}
```

## Important Limitation

The system requires **separate webhook calls for each location** — you cannot batch multiple locations in a single request. However, the Billing URL can deliver multiple `locationId` values in comma-separated format during installation.