MidwayPlus API Docs

This section covers the basic components that make up an App, including the App Id/Name, what parties the app is available to, the version, the Purchase Options, acknowledgement requirements, permissions, settings, and webhook configuration.

The Id of your app is the unique identifier for your app, used in several places in the API, and is also used as the URL slug for your app listing. The name and Id must both be unique within MidwayPlus.

Apps can be configured to be available for one or multiple different party types, e.g. Buyers and Sellers. Currently, apps can only be made available to Buyers and/or Sellers.

Every app in the app store is assigned a version, which can be used to track updates and changes to its configuration, settings, or functionality. The version is defined by the app creator and is copied to the installation record when a user installs the app, ensuring that the specific iteration of the app is documented for that instance. This version is also exposed through the API, allowing developers to query or reference the exact app version installed. Updates to an app that render the app incompatible with previous behavior or settings should correspond to a different version. All new installations will reflect the latest version available at the time of installation.

Purchase Options define the pricing settings for an application available in the app store. They provide Developers with flexibility to determine how payments are calculated for their app. An app can have one or more Purchase Options, each specifying a distinct pricing model. These options allow developers to cater to different user needs by offering varied payment structures.

Supported Pricing Models

Flat Price
A fixed recurring fee charged on a monthly basis.
- Example: $10 / month
Flat Price (Billed annually)
A fixed recurring fee calculated monthly but billed annually as a lump sum.
- Example: $10 / month billed as $120 / year.
Tiered Pricing with Buckets
A dynamic pricing model based on predefined tiers (or "buckets") of existing data, with an optional flat monthly rate. Buckets represent increments of usage, such as a set number of products, and a flat rate is applied per bucket. Tiered Pricing currently only supports buckets of Products.
- How Buckets Work: Pricing is calculated by dividing the total records (e.g., number of products) into buckets of a specified size, then charging a flat rate per bucket. An additional flat monthly rate can also be included.
- Example: $5 per 500 products + $10/month base fee.
  - For 1,200 products:
    - Buckets = ceil(1,200 / 500) = 3 buckets.
    - Cost = (3 buckets × $5) + $10/month = $25/month.

Usage in the API

Purchase Options must be given an Id. The Purchase Option is made available by it's Id in various places of the API and UI. We recommend you use meaningful Ids for the purchase options that correspond to the feature set of your app so you can control behavior. For example, free, basic, premium, etc.

In addition to a terms and conditions document you can attach to your app, you can also require that users purchasing your app acknowledge certain things before installing/purchasing your app.

Permissions define the specific actions and data access an app is allowed to perform within the platform. Every app must have its permissions pre-defined by the app creator before it is made available in the app store. When a user installs an app, these permissions are copied to the installation record, creating a binding agreement between the app and the user’s environment. Because permissions are locked in at installation, it’s critical to ensure they are accurately configured from the start.

Available Permissions

A comprehensive list of all available permissions, including their descriptions and use cases, can be found on our Permissions Reference Page. This page provides detailed guidance to help app creators select the appropriate permissions for their application and also to inform users of your app exactly the actions and data that are made to app operators.

App Settings allow app creators to define configurable options for their applications, enabling customization by both end users and app operators. Settings are categorized into two types: User Settings, which are configured by the app’s end users, and Admin Settings, which are managed by the developer. These settings are tied to specific Purchase Options (see Purchase Options (#)), linking configuration capabilities to the pricing model selected by the user.

Configuration Structure

Settings are defined in a JSON object where each top-level key (e.g., "free", "enhanced") represents a configuration profile linked to a specific Purchase Option. Within each profile, individual settings are specified as nested objects, each with properties that determine their behavior, type, and presentation in the app’s interface.

Setting Types

Text (type: "text")
A free-form text input field.
- Attributes
  - name: Display name of the setting (e.g., "Text setting").
  - description: A brief explanation (e.g., "What is your text setting?").
  - placeholder: Placeholder text in the input field (e.g., "Put your text setting here").
  - mandatory: Boolean indicating if the field is required (true/false).
  - order: Numeric value determining display order (e.g., 1).
- Example: A field for entering a textual identifier or label.
Select (type: "select")
A dropdown menu with predefined options.
- Attributes
  - name: Display name of the setting (e.g., "Select option").
  - options: Array of choices, each with name (display text) and value (string).
  - mandatory: Boolean indicating if the field is required (true/false).
  - order: Numeric value determining display order (e.g., 1).
- Example: { "name": "One", "value": "one" } and { "name": "Two", "value": 2 }
Number (type: "number")
A numeric input with optional range constraints.
- Attributes
  - name: Display name of the setting (e.g., "Number setting").
  - min: Minimum allowed value (e.g., 0).
  - max: Maximum allowed value (e.g., 10).
  - step: Increment/decrement step (e.g., 1).
  - mandatory: Boolean indicating if the field is required (true/false).
  - order: Numeric value determining display order (e.g., 1).
- Example: A setting to specify a quantity between 0 and 10.
Boolean (type: "boolean")
A checkbox for true/false selection.
- Attributes
  - name: Display name of the setting (e.g., "Text setting").
  - mandatory: Boolean indicating if the field is required (true/false).
  - order: Numeric value determining display order (e.g., 1).
- Example: Enable or disable a feature.
Password (type: "password")
A masked text input for sensitive data. These fields, once entered, are hidden from the user.
- Attributes
  - name: Display name of the setting (e.g., "Password setting").
  - description: Explanation (e.g., "a secret password").
  - mandatory: Boolean indicating if the field is required (true/false).
  - order: Numeric value determining display order (e.g., 1).
- Example: Enable or disable a feature.

How Settings Work

User Settings: Configured by the end user during app installation, these settings allow personalization based on the selected Purchase Option. For example, a user might enter required credentials to connect to the ERP system or another third party API.
Admin Settings: Managed by the app operator via the App Installation Page, these settings control operational aspects of the app (e.g., a "Password setting" for backend authentication). They are typically set after the app is installed and are ideal for things the users of the app may not be able to configure themselves or things your app's logic needs to determine and set after installation.
Purchase Option Link: Each settings profile (e.g., "free", "enhanced") corresponds to a specific Purchase Option. When a user selects a Purchase Option during installation, the associated settings are made available for configuration.

Example

{
  "free": {
    "textSetting": {
      "name": "Text setting",
      "type": "text",
      "order": 1,
      "mandatory": true,
      "description": "What is your text setting?",
      "placeholder": "Put your text setting here"
    },
    "selectOption": {
      "name": "Select Option",
      "type": "select",
      "order": 2,
      "options": [
        {
          "name": "One",
          "value": "one"
        },
        {
          "name": "Two",
          "value": 2
        }
      ],
      "mandatory": false
    },
    "numberSetting": {
      "max": 10,
      "min": 0,
      "name": "Number setting",
      "step": 1,
      "type": "number",
      "order": 5,
      "mandatory": false
    },
    "checkboxSetting": {
      "name": "Checkbox setting",
      "type": "boolean",
      "order": 3,
      "mandatory": false
    },
    "passwordSetting": {
      "name": "Password setting",
      "type": "password",
      "order": 4,
      "mandatory": true,
      "description": "a secret password"
    }
  },
  "enhanced": {
    "textSetting": {
      "name": "Text setting",
      "type": "text",
      "order": 1,
      "mandatory": true,
      "description": "What is your text setting?",
      "placeholder": "Put your text setting here"
    },
    "selectOption": {
      "name": "Select Option",
      "type": "select",
      "order": 2,
      "options": [
        {
          "name": "One",
          "value": "one"
        },
        {
          "name": "Two",
          "value": 2
        }
      ],
      "mandatory": false
    },
    "numberSetting": {
      "max": 10,
      "min": 0,
      "name": "Number setting",
      "step": 1,
      "type": "number",
      "order": 5,
      "mandatory": false
    },
    "checkboxSetting": {
      "name": "Checkbox setting",
      "type": "boolean",
      "order": 3,
      "mandatory": false
    },
    "passwordSetting": {
      "name": "Password setting",
      "type": "password",
      "order": 4,
      "mandatory": true,
      "description": "a secret password"
    }
  }
}

Coming soon.

Documentation

Creating an App (beta)

App Id/Name

Party Types

Version

Purchase Options

Acknowledgement Requirements

Permissions

App Settings

Webhook Configuration