Marketplace listing and install consent

Authentication

These routes are for the merchant dashboard, not for an installed app. Send the merchant’s session token:

Authorization: Bearer <merchant-session-token>

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

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

{
  "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
    }
  }
}

featured and collections are set by Salesive admins. There is no developer-writable route for them.

Get one app

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

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.

{
  "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.

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.

Overview

Developer console

Billing

Blogs

Categories

Comments

Customers

Digital access

Digital products

Discounts

Domains

Emails

Foods

KYC

Notes

Notifications

Orders

Payouts

Products

Roles

Scripts

Services

Shipday

Shipping

Tasks

Marketplace listing and install consent

Authentication

List the marketplace

Query parameters

Response

Get one app

Start an install

The ticket

Errors

Next steps

Install flow

Webhook deliveries

​Authentication

​List the marketplace

​Query parameters

​Response

​Get one app

​Start an install

​The ticket

​Errors

​Next steps

Install flow

Webhook deliveries

Authentication

List the marketplace

Query parameters

Response

Get one app

Start an install

The ticket

Errors

Next steps