---
title: Partner API overview
description: An API for external apps that connect to Toreca Cloud over OAuth to read buy boosts and stock.
sidebar:
  label: Overview
---

The partner API is for external apps a shop has approved: apps that put buy boosts on a landing page or an X post, and oripa services or business systems that sync stock.

An app calls the API with a token issued when a shop member approves it in the browser. No API keys are shared. The token decides which shop's data the app reads; a request can't name another shop.

## Basics

| Item          | Value                                                        |
| ------------- | ------------------------------------------------------------ |
| Base URL      | `https://api.toreca-cloud.com/partner/v1`                    |
| Authorization | OAuth 2.1 authorization code flow (PKCE S256 required)       |
| Client        | A pre-registered confidential client (`client_secret_basic`) |
| Format        | JSON; every response has `Cache-Control: no-store`           |

## What it offers

| Scope                  | Lets the app                                        |
| ---------------------- | --------------------------------------------------- |
| `purchase-boosts:read` | Read the buy boost list. No stock is visible        |
| `inventory:read`       | Sync sites, storage locations and stock units       |
| `inventory:write`      | Hold and ship units it sold                         |
| `inventory:move`       | Move between shelves and sites, take out and return |

Give landing page and posting apps `purchase-boosts:read` only. They get the buy boosts and never see a single unit of stock.

## Getting started

1. **The shop registers the app**

    A shop admin registers the app under Settings › Integrations: display name,
    redirect URI and what to allow. A client ID and client secret are issued. If
    the screen isn't there, ask Toreca Cloud support to enable it.

2. **A shop member approves**

    The app opens the authorization screen, and a shop member signs in and
    presses Allow. The app exchanges the authorization code for tokens
    ([authorization](/en/api/authorization)).

3. **Create the connection**

    Call `POST /connection` first. If the shop revokes it, later calls fail with
    `connection_revoked`.

4. **Call the API**

    Send the access token as a Bearer token. Store and refresh tokens as
    described in [tokens and expiry](/en/api/tokens).

Every endpoint is described in the [API reference](/en/api/reference).