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

# Building marketplace apps

> How to build, test, and publish apps for the HoopAI App Marketplace.

The HoopAI App Marketplace lets developers build and distribute integrations to all HoopAI users. Marketplace apps use OAuth 2.0 for authentication and can monetize through subscription billing.

## App types

| Type                | Description                                  | Use case                                   |
| ------------------- | -------------------------------------------- | ------------------------------------------ |
| **Integration app** | Connects HoopAI with an external service     | CRM sync, payment processor, analytics     |
| **Workflow action** | Adds custom actions to the Workflow Builder  | Custom API calls, data enrichment          |
| **Custom page**     | Embeds a UI inside HoopAI via iframe         | Dashboards, custom tools                   |
| **Widget**          | Adds UI elements to specific areas of HoopAI | Contact sidebar widgets, dashboard widgets |

## Building your app

<Steps>
  <Step title="Register on the Developer Marketplace">
    Go to the [HoopAI Developer Marketplace](https://marketplace.hoopai.com/) and create a developer account.
  </Step>

  <Step title="Create a new app">
    Click **Create App** and configure:

    * App name and description
    * OAuth redirect URI
    * Required scopes
    * Webhook subscriptions
  </Step>

  <Step title="Implement OAuth flow">
    Follow the [Authentication guide](/developer/guide/authentication#option-2-oauth-20-authorization-code-flow) to implement the OAuth 2.0 Authorization Code flow.
  </Step>

  <Step title="Build your integration">
    Use the [API Reference](/api-reference/introduction) to implement your app's features. Handle token refresh, webhooks, and error cases.
  </Step>

  <Step title="Test with a sandbox account">
    Install your app on a test account and verify all features work correctly.
  </Step>

  <Step title="Submit for review">
    Once tested, submit your app for review. The HoopAI team will verify it meets marketplace standards.
  </Step>
</Steps>

## App lifecycle events

When your app is installed or uninstalled, HoopAI sends webhook events:

| Event          | When it fires                          |
| -------------- | -------------------------------------- |
| `AppInstall`   | A user installs your app on a account  |
| `AppUninstall` | A user removes your app from a account |

Handle these events to provision or clean up resources for each installation.

## Monetization

Marketplace apps can charge users through the **External Billing** system:

* Set a monthly or annual subscription price
* HoopAI handles billing and payments
* You receive payouts minus the marketplace commission

See the [External Billing guide](/api-reference/oauth/external-billing) for implementation details.

## Custom menus and UI

Apps can inject custom navigation items and pages into HoopAI:

```json theme={null}
{
  "locationId": "LOC_ID",
  "name": "My App Dashboard",
  "url": "https://myapp.com/dashboard?locationId={{locationId}}",
  "icon": "chart-bar",
  "showInSidebar": true
}
```

## Best practices

<AccordionGroup>
  <Accordion title="Handle installation gracefully">
    When a user installs your app, set up all necessary resources (database records, webhook subscriptions) and provide a clear onboarding experience.
  </Accordion>

  <Accordion title="Respect rate limits">
    Design your app to work within [rate limits](/developer/guide/making-requests#rate-limits). Use caching and batch operations where possible.
  </Accordion>

  <Accordion title="Clean up on uninstall">
    When your app is uninstalled, clean up webhooks, revoke tokens, and remove any data you no longer need.
  </Accordion>

  <Accordion title="Provide clear documentation">
    Include setup instructions, feature descriptions, and support contact information in your marketplace listing.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="OAuth scopes" icon="shield" href="/api-reference/oauth/scopes">
    Choose the right permissions for your app
  </Card>

  <Card title="Webhook events" icon="bell" href="/api-reference/webhooks/overview">
    Subscribe to platform events
  </Card>
</CardGroup>