> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesive.com/llms.txt > Use this file to discover all available pages before exploring further. # Marketplace listing and install consent > Read the marketplace listing with its sort and curation filters, and start a marketplace install with a single use consent ticket. ## Authentication These routes are for the **merchant dashboard**, not for an installed app. Send the merchant's session token: ```http theme={null} Authorization: Bearer ``` An `app_` access token cannot call them, and the install consent route needs the merchant who is allowed to install on the store. ## List the marketplace ```http theme={null} GET /api/v1/apps/marketplace ``` Returns live, public, approved apps. The listing is paginated and every app carries `featured`. ### Query parameters | Parameter | Type | Notes | | - | - | - | | `q` | string | Search the name, tagline, description, category, tags and developer name. Results are ranked and carry `score`. See [Marketplace search](https://docs.salesive.com/apps-api/marketplace-search.md). | | `category` | string | Filter by the app's category. | | `shopType` | string | `ecommerce`, `restaurant`, `business` or `digital`. Apps with no store types are compatible with all. | | `sort` | string | `relevance` (default), `installs`, `rating` or `newest`. An unknown value falls back to `relevance`. | | `featured` | string | `1`, `true` or `yes` to return only featured apps. | | `collection` | string | A collection slug such as `staff-picks`. Lowercase letters, digits and hyphens, up to 64 characters. Junk values are ignored. | | `page` | number | Default 1. | | `limit` | number | Default 20. | Featured apps lead the explicit sorts (`installs`, `rating` and `newest`), which is the point of curation. `installs` sorts by the live install base, `rating` by average then count, and `newest` by creation time. A relevance search ranks by score instead, so a featured app gets no bonus there. ### Response ```json theme={null} { "status": 200, "success": true, "message": "Marketplace apps retrieved", "data": { "apps": [ { "_id": "66b1f0a3c2d4e5f6a7b8c9d0", "name": "Sizer", "slug": "sizer", "tagline": "Right-size every order", "iconUrl": "https://cdn.example.com/sizer.png", "category": "operations", "featured": true, "official": false, "activeInstalls": 128, "ratingAvg": 4.6, "ratingCount": 31, "requestedScopes": ["READ_ORDERS", "WRITE_ORDERS"], "shopTypes": ["ecommerce"], "createdAt": "2026-09-14T09:00:00.000Z" } ], "pagination": { "total": 1, "page": 1, "limit": 20, "pages": 1, "hasNext": false, "hasPrev": false, "nextPage": null, "prevPage": null } } } ``` > [!NOTE] > > `featured` and `collections` are set by Salesive admins. There is no developer-writable route for > them. ## Get one app ```http theme={null} GET /api/v1/apps/marketplace/:slug ``` Returns the public listing fields for one approved, public app. A review tester can also open an app that is still in review; the response then carries `inReview: true`. ## Start an install ```http theme={null} POST /api/v1/apps/marketplace/:slug/install-consent Content-Type: application/json { "shop": "66b1f0a3c2d4e5f6a7b8c9d0" } ``` Verifies that the signed-in merchant may install this app on that store, then issues a **consent ticket** plus the OAuth values the consent screen needs. It creates **no installation**. ```json theme={null} { "status": 200, "success": true, "message": "Consent ticket issued", "data": { "ticket": "act_9f2c...", "clientId": "app_xxxxxxxxxxxxxxxx", "redirectUri": "https://yourapp.com/oauth/callback", "scopes": ["READ_ORDERS", "WRITE_ORDERS"], "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "codeChallengeMethod": "S256", "state": "6f1c2e3a9b0d", "expiresAt": "2026-11-07T12:10:00.000Z", "scopeDetails": [ { "permission": "READ_ORDERS", "label": "View orders", "category": "Orders", "name": "Read Orders", "description": "Allows reading orders." } ], "deniedScopes": [], "shopId": "66b1f0a3c2d4e5f6a7b8c9d0", "app": { "_id": "66b1f0a3c2d4e5f6a7b8c9d0", "name": "Sizer", "slug": "sizer", "tagline": "Right-size every order", "iconUrl": "https://cdn.example.com/sizer.png", "developerName": "Acme Labs", "website": "https://acme.example.com", "type": "app", "official": false } } } ``` ### The ticket * Single use, expires after **10 minutes**, and is bound to the app, the store and the merchant who requested it. * Only its SHA-256 is stored, never the raw value. * `GET /oauth/authorize?ticket=...` validates it without consuming it. * `POST /oauth/authorize` with `approved: true` consumes it once, creates the installation and returns a redirect URL with an authorization code. The dashboard does not follow that redirect for a marketplace install; it returns the merchant to the listing, and the app completes its own token exchange when it is opened. A missing, expired or already used ticket is refused with `400 invalid_ticket` and nothing is installed. `scopes` is the list that will actually be granted, after the grantable catalog and customer data gates. `deniedScopes` explains every requested scope that was dropped. See [Scopes & permissions](https://docs.salesive.com/apps/scopes-permissions.md#what-salesive-will-grant). ### Errors | Status | Message | Meaning | | - | - | - | | `400` | `No store selected` | The body has no `shop` and the request carries no store context. | | `400` | `This app has no redirect URI registered yet. The developer must add one before it can be installed.` | The app must register a redirect URI before it can be installed. | | `403` | `This app isn't available to install` | The app is not live, or this merchant cannot install it yet. | | `403` | `You don't have permission to install apps on this store` | The merchant is not the owner or staff of that store. | | `403` | `This store is suspended` | The store is blocked. | | `404` | `App not found` | No app has that slug. | ## Next steps > [card] [Install flow](https://docs.salesive.com/apps/oauth-install.md) > > The full consent and token exchange. > [card] [Webhook deliveries](https://docs.salesive.com/apps-api/webhook-deliveries.md) > > List, replay and test an app's deliveries. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.