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

# Partner apps

> Create an app that brands can install to connect with your platform.

Subtotal works with technology partners that help brands make more use of their retail purchase data. Loyalty platforms, review providers, customer engagement tools, analytics products, and other partners can create an app that a brand installs to securely connect its Subtotal data with their service.

Under the hood, the app requests access to a brand's data through the OAuth Authorization Code flow with PKCE, following OAuth 2.1 security practices. It can also receive the brand's selected webhook events at an endpoint operated by the partner.

## Become a Subtotal partner

To create an app, first sign up for the [Subtotal Dashboard](https://dashboard.subtotal.com). Once Subtotal authorizes your dashboard team to create apps, team admins can create and manage them under **Apps → Created Apps**.

Before approval, only the team that owns the app can install and test it. Once approved by Subtotal, other brands can discover and install it.

## Integration lifecycle

<Steps>
  <Step title="Create the app">
    Enter the listing, OAuth, and optional webhook configuration in **Created Apps**. Subtotal assigns a Client ID, a one-time client secret, a webhook signing secret, and the app's fixed scopes.
  </Step>

  <Step title="Install and test the app">
    Use **Install app** to run the real authorization-code flow with the dashboard team that owns the app. This development installation is available only to that team.
  </Step>

  <Step title="Submit for review">
    Subtotal reviews the listing and integration configuration. Submitted apps are read-only, so finish testing before you submit.
  </Step>

  <Step title="Install the approved app">
    Approval publishes the reviewed listing. A brand starts at your Install URL, authorizes all three fixed permissions in Subtotal, and returns to an allow-listed redirect URI.
  </Step>
</Steps>

## Fixed permissions

Every partner app is assigned the same permission set. There are no broader scopes available to partners at this time.

| Scope                      | Access                                                                                       |
| :------------------------- | :------------------------------------------------------------------------------------------- |
| `connections:read`         | View the brand's connections and receive configured connection events                        |
| `retailers:read`           | Read the authorizing brand's [retailer catalog](/docs/api-reference/retailers/get-retailers) |
| `purchases:brand_products` | Receive configured `purchase.created` events containing brand products                       |

Omit `scope` to request the full set, or send all three scopes exactly once. Partner apps receive them as one fixed grant; subsets, additional scopes, and duplicates are rejected. The `purchases:brand_products` scope is required for a partner installation to subscribe to `purchase.created`.

<Warning>
  Direct OAuth Bearer access to purchase list and detail endpoints is not available yet. Today, `purchases:brand_products` authorizes configured `purchase.created` webhook deliveries and limits their purchase data to brand products. Connection API access, OAuth identity, installation management, and partner webhooks are available today.
</Warning>

## Current limitations

* Apps under development can be installed only by the dashboard team that created them. Other brands can install an app only after Subtotal approves it.
* Submitted and approved app configuration is read-only in this onboarding release.
* Partner scopes are fixed; partners cannot add, remove, or negotiate individual permissions.
* Approval and rejection are performed by Subtotal. A rejected app can be edited and resubmitted; saving an edited rejection returns it to draft.