Skip to main content
App settings are in development. They are not yet available in production, and details can change before release.

Format

A manifest is a JSON object with a format version and a list of fields.
integer
required
The manifest format. Use 1.
object[]
required
The settings fields. The order of the list is the order in the Configure tab.

Common field properties

All field types have these properties.
string
required
The name of the field. Use 1 to 64 characters: a to z first, then a to z, 0 to 9, or _. Each key must be unique in the manifest.
string
required
One of text, secret, number, boolean, select, events, products, currencies.
string
required
The label that the merchant sees. 1 to 80 characters of plain text.
string
Help for the merchant. Up to 500 characters of plain text.
boolean
default:"false"
If true, the merchant must give a value. A missing value sets action_needed.
Labels and help text are plain text. HTML and control characters are not allowed. A property that the field type does not support is an error.

Field types

Text and secret

string
A regular expression that must match the full value. Up to 512 characters.
integer
The minimum length of the value.
integer
The maximum length of the value. The limit is 4096.
string
The default value. A secret field cannot have a default, because the manifest is not secret.
boolean
default:"false"
Text only. Shows a multi-line input.

Number

Numbers are whole numbers. For an amount, use minor units, for example cents.
integer
The smallest allowed value. It must not be more than max.
integer
The largest allowed value.

Select

A select field has a fixed options list, or options_url for dynamic options. Give one of the two, not both.
object[]
Up to 200 items. Each item has value and label, each 1 to 100 characters. Values must be unique.
string
An HTTPS URL on a public host name. It cannot have a port, credentials, or a fragment. Up to 2048 characters.
string
The URL for test installations. It follows the same rules as options_url.
boolean
default:"false"
Lets the merchant pick more than one item. The value is then an array of strings. This also applies to events, products, and currencies.

Dodo pickers

events, products, and currencies show a picker that Dodo Payments fills for the merchant. A products field has no default.

Limits

Example manifest

Upload a manifest

These endpoints are in the developer API that the developer dashboard uses. You can also use the manifest editor on the app page.
The examples use $DEVELOPER_API_URL and $DEVELOPER_API_TOKEN as placeholders for the developer API base URL and your developer credentials.

Preview

Checks a manifest and shows the review result. It does not store anything.
boolean
true if the manifest passes all checks.
string[]
The errors that you must fix, for example field api_key: the pattern is not valid: ....
string
The status that an upload would get.
string[]
The review reason codes of the change.
object[]
The fields that caused each reason.

Upload

Stores a new version. The body is the raw manifest, at most 64 KiB. Only an owner or an admin of the app can upload.

List versions

GET /apps/{id}/manifests returns { "items": [...] }. Each item has id, app_id, version, status, manifest, review_reasons, created_by_user_id, live_at, created_at, and updated_at.

Versions

Each upload creates a new version number for the app. A live version never changes. An installation moves to the newest live version when the merchant saves. Until then, manifest_version in the settings response is older than live_manifest_version. If your app is private, or has not been listed yet, every version goes live at once. For a listed app, a version with no review reason goes live at once, and a version with a reason goes to review.

Changes that need review

A stored value that fails a stricter rule is listed in invalid_keys. The installation shows Action needed until the merchant fixes it. These changes need no review: new labels, help text, order, defaults, a new optional field that is not secret, and a removed field. Values of a removed field stay stored, but your app no longer receives them.
You cannot change the type of a key that any earlier version used, and you cannot change whether it is secret. Use a new key instead.
Last modified on November 16, 2026