> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings Manifest Reference

> The format of the app settings manifest: field types, properties, limits, versions, and the changes that need review. Includes upload and preview endpoints.

> [!WARNING]
>
> 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.

**format\_version** `integer` *required*

The manifest format. Use `1`.

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

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

**type** `string` *required*

One of `text`, `secret`, `number`, `boolean`, `select`, `events`, `products`, `currencies`.

**label** `string` *required*

The label that the merchant sees. 1 to 80 characters of plain text.

**help\_text** `string`

Help for the merchant. Up to 500 characters of plain text.

**required** `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

| Type | Value | Extra properties |
| - | - | - |
| `text` | String | `default`, `pattern`, `min_length`, `max_length`, `multiline` |
| `secret` | String, write-only | `pattern`, `min_length`, `max_length` |
| `number` | Whole number | `default`, `min`, `max` |
| `boolean` | `true` or `false` | `default` |
| `select` | String, or array of strings | `default`, `options`, `options_url`, `options_url_test`, `multiple` |
| `events` | Webhook event types | `default`, `multiple` |
| `products` | Product IDs of the business | `multiple` |
| `currencies` | ISO 4217 currency codes | `default`, `multiple` |

### Text and secret

**pattern** `string`

A regular expression that must match the full value. Up to 512 characters.

**min\_length** `integer`

The minimum length of the value.

**max\_length** `integer`

The maximum length of the value. The limit is 4096.

**default** `string`

The default value. A `secret` field cannot have a default, because the manifest is not secret.

**multiline** `boolean` (default: false)

Text only. Shows a multi-line input.

### Number

Numbers are whole numbers. For an amount, use minor units, for example cents.

**min** `integer`

The smallest allowed value. It must not be more than `max`.

**max** `integer`

The largest allowed value.

### Select

A select field has a fixed `options` list, or `options_url` for [dynamic options](https://docs.dodopayments.com/developer-resources/apps/app-settings/dynamic-options.md). Give one of the two, not both.

**options** `object[]`

Up to 200 items. Each item has `value` and `label`, each 1 to 100 characters. Values must be unique.

**options\_url** `string`

An HTTPS URL on a public host name. It cannot have a port, credentials, or a fragment. Up to 2048 characters.

**options\_url\_test** `string`

The URL for test installations. It follows the same rules as `options_url`.

**multiple** `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

| Limit | Value |
| - | - |
| Manifest size | 64 KiB |
| Fields in a manifest | 50 |
| Secret fields in a manifest | 20 |
| Options in a select field | 200 |
| Size of all saved values | 64 KiB |
| Size of one value | 4096 characters |

## Example manifest

```json theme={null}
{
  "format_version": 1,
  "fields": [
    {
      "key": "project_name",
      "type": "text",
      "label": "Project name",
      "help_text": "Shown in your reports.",
      "required": true,
      "max_length": 80
    },
    {
      "key": "api_key",
      "type": "secret",
      "label": "API key",
      "required": true,
      "min_length": 20
    },
    {
      "key": "sample_rate",
      "type": "number",
      "label": "Sample rate (percent)",
      "default": 100,
      "min": 1,
      "max": 100
    },
    {
      "key": "send_test_events",
      "type": "boolean",
      "label": "Send test events",
      "default": false
    },
    {
      "key": "region",
      "type": "select",
      "label": "Region",
      "options": [
        { "value": "us", "label": "United States" },
        { "value": "eu", "label": "Europe" }
      ],
      "default": "us"
    },
    {
      "key": "workspace",
      "type": "select",
      "label": "Workspace",
      "options_url": "https://app.example.com/dodo/options",
      "options_url_test": "https://sandbox.example.com/dodo/options"
    },
    {
      "key": "events",
      "type": "events",
      "label": "Events to forward",
      "multiple": true
    },
    {
      "key": "products",
      "type": "products",
      "label": "Products to track",
      "multiple": true
    },
    {
      "key": "currencies",
      "type": "currencies",
      "label": "Currencies",
      "multiple": true
    }
  ]
}
```

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

> [!NOTE]
>
> 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.

```bash theme={null}
curl -X POST $DEVELOPER_API_URL/apps/app_123/manifest/preview \
  -H "Authorization: Bearer $DEVELOPER_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data @manifest.json
```

**valid** `boolean`

`true` if the manifest passes all checks.

**problems** `string[]`

The errors that you must fix, for example `field api_key: the pattern is not valid: ...`.

**status** `string`

The status that an upload would get.

**review\_reasons** `string[]`

The [review reason codes](#changes-that-need-review) of the change.

**review\_items** `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.

```bash theme={null}
curl -X PUT $DEVELOPER_API_URL/apps/app_123/manifest \
  -H "Authorization: Bearer $DEVELOPER_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data @manifest.json
```

```json theme={null}
{
  "version": 2,
  "status": "in_review",
  "review_reasons": ["new_required_field"],
  "review_items": [],
  "pending_version": 5,
  "review_state": "in_review"
}
```

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

| Status | Meaning |
| - | - |
| `live` | Merchants see this version. |
| `in_review` | The version waits for review. Merchants still see the live version. |
| `rejected` | A reviewer rejected the version. Upload a new version. |
| `retired` | A newer version replaced it. |

An installation moves to the newest live version when the merchant saves. Until then, `manifest_version` in the [settings response](https://docs.dodopayments.com/developer-resources/apps/app-settings/read-settings.md) 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

| Reason code | Meaning |
| - | - |
| `new_required_field` | A new field is `required`. |
| `field_now_required` | An existing field became `required`. |
| `new_secret_field` | A new `secret` field. |
| `new_options_url` | A new `options_url` or `options_url_test`. |
| `new_options_host` | An existing options URL now uses a new host. |
| `narrower_rule` | A rule is stricter: fewer options, a new `pattern`, a smaller `max`, or a larger `min`. |

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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.