Documentation

API reference

Modifiers

Modifiers are option groups a customer chooses from when adding a product — sizes, toppings, add-ons.

Base URL: https://apiv2.venuerun.com/merchants/:merchantId/modifiers

text

GET    /merchants/:merchantId/modifiers
POST   /merchants/:merchantId/modifiers
GET    /merchants/:merchantId/modifiers/:modifierId
POST   /merchants/:merchantId/modifiers/:modifierId
PATCH  /merchants/:merchantId/modifiers/:modifierId
DELETE /merchants/:merchantId/modifiers/:modifierId

The modifier object

Field	Type	Description
`id`	`string` (read-only)	Unique identifier, assigned by VenueRun.
`createdAt`	`string` (read-only)	When it was created (ISO 8601).
`updatedAt`	`string` (read-only)	When it last changed (ISO 8601).
`type`	`"CHECKBOX"`	Defaults to `"CHECKBOX"`.
`title`	`string`
`instructions`	`string`	Defaults to `""`.
`description`	`string`	Defaults to `""`.
`rules`	`object`
↳ `minSelections`	`integer`	`0` = optional; `1+` = required, at least this many. Defaults to `0`.
↳ `maxSelections`	`integer \| null`	`null` = no limit. `1` = a single choice. Defaults to `null`.
↳ `maxPerOption`	`integer`	How many of ONE option may be taken. `1` = no "2× bacon". Defaults to `1`.
`options`	`object[]`	Defaults to `[]`.
`testMode`	`boolean`	Defaults to `false`.

json

{
  "id": "oNCjlvaFsre9pzHH3A9s",
  "type": "CHECKBOX",
  "title": "Test modifier A1B2C3",
  "instructions": "Please select an option",
  "description": "",
  "rules": {
    "minSelections": 1,
    "maxSelections": 1,
    "maxPerOption": 1
  },
  "options": [
    {
      "id": "opt-a-A1B2C3",
      "label": "Small",
      "additionalCostMinor": 0,
      "additionalCalories": 0,
      "defaultQuantity": 0,
      "available": true
    }
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

List modifiers

GET /merchants/:merchantId/modifiers

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/modifiers`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "testMode": true,
  "length": 1,
  "data": [
    {
      "id": "oNCjlvaFsre9pzHH3A9s",
      "type": "CHECKBOX",
      "title": "Test modifier A1B2C3",
      "instructions": "Please select an option",
      "description": "",
      "rules": {
        "minSelections": 1,
        "maxSelections": 1,
        "maxPerOption": 1
      },
      "options": [
        {
          "id": "opt-a-A1B2C3",
          "label": "Small",
          "additionalCostMinor": 0,
          "additionalCalories": 0,
          "defaultQuantity": 0,
          "available": true
        }
      ],
      "testMode": true,
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Create a modifier

POST /merchants/:merchantId/modifiers

Required attributes

Field	Type	Description
`title`	`string`
`rules`	`object`
↳ `minSelections`	`integer`	`0` = optional; `1+` = required, at least this many. Defaults to `0`.
↳ `maxSelections`	`integer \| null`	`null` = no limit. `1` = a single choice. Defaults to `null`.
↳ `maxPerOption`	`integer`	How many of ONE option may be taken. `1` = no "2× bacon". Defaults to `1`.

Optional attributes

Field	Type	Description
`type`	`"CHECKBOX"`	Defaults to `"CHECKBOX"`.
`instructions`	`string`	Defaults to `""`.
`description`	`string`	Defaults to `""`.
`options`	`object[]`	Defaults to `[]`.
`testMode`	`boolean`	Defaults to `false`.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/modifiers`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "CHECKBOX",
    "title": "Test modifier A1B2C3",
    "instructions": "Please select an option",
    "rules": {
      "minSelections": 1,
      "maxSelections": 1,
      "maxPerOption": 1
    },
    "options": [
      {
        "id": "opt-a-A1B2C3",
        "label": "Small",
        "additionalCostMinor": 0,
        "additionalCalories": 0
      }
    ],
    "testMode": true
  }),
});

Response:

json

{
  "id": "OMxdBQHz6nDFmm7J7zaA",
  "type": "CHECKBOX",
  "title": "Test modifier A1B2C3",
  "instructions": "Please select an option",
  "description": "",
  "rules": {
    "minSelections": 1,
    "maxSelections": 1,
    "maxPerOption": 1
  },
  "options": [
    {
      "id": "opt-a-A1B2C3",
      "label": "Small",
      "additionalCostMinor": 0,
      "additionalCalories": 0,
      "defaultQuantity": 0,
      "available": true
    }
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Retrieve a modifier

GET /merchants/:merchantId/modifiers/:modifierId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/modifiers/HoXGTIeTFoPfwHsiQu5r`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "HoXGTIeTFoPfwHsiQu5r",
  "type": "CHECKBOX",
  "title": "Test modifier A1B2C3",
  "instructions": "Please select an option",
  "description": "",
  "rules": {
    "minSelections": 1,
    "maxSelections": 1,
    "maxPerOption": 1
  },
  "options": [
    {
      "id": "opt-a-A1B2C3",
      "label": "Small",
      "additionalCostMinor": 0,
      "additionalCalories": 0,
      "defaultQuantity": 0,
      "available": true
    }
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Update a modifier (POST alias)

POST /merchants/:merchantId/modifiers/:modifierId

Send only the fields you are changing — every attribute is optional.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/modifiers/3SToW76GAAEUMjXztXib`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "options": [
      {
        "id": "opt-a-A1B2C3",
        "label": "Small",
        "defaultQuantity": 1
      }
    ]
  }),
});

Response:

json

{
  "id": "3SToW76GAAEUMjXztXib",
  "type": "CHECKBOX",
  "title": "Test modifier A1B2C3",
  "instructions": "Please select an option",
  "description": "",
  "rules": {
    "minSelections": 1,
    "maxSelections": 1,
    "maxPerOption": 1
  },
  "options": [
    {
      "id": "opt-a-A1B2C3",
      "label": "Small",
      "additionalCostMinor": 0,
      "additionalCalories": 0,
      "defaultQuantity": 1,
      "available": true
    }
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Update a modifier

PATCH /merchants/:merchantId/modifiers/:modifierId

Send only the fields you are changing — every attribute is optional.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/modifiers/gwg4TueJiH3w7EXtsBl1`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "options": [
      {
        "id": "opt-a-A1B2C3",
        "label": "Small",
        "additionalCostMinor": 0,
        "additionalCalories": 0,
        "defaultQuantity": 0,
        "available": false
      }
    ]
  }),
});

Response:

json

{
  "id": "gwg4TueJiH3w7EXtsBl1",
  "type": "CHECKBOX",
  "title": "Test modifier A1B2C3",
  "instructions": "Please select an option",
  "description": "",
  "rules": {
    "minSelections": 1,
    "maxSelections": 1,
    "maxPerOption": 1
  },
  "options": [
    {
      "id": "opt-a-A1B2C3",
      "label": "Small",
      "additionalCostMinor": 0,
      "additionalCalories": 0,
      "defaultQuantity": 0,
      "available": false
    }
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Delete a modifier

DELETE /merchants/:merchantId/modifiers/:modifierId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/modifiers/LuCYFT8A4VwU9tGMTgab`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "LuCYFT8A4VwU9tGMTgab",
  "object": {
    "id": "LuCYFT8A4VwU9tGMTgab",
    "type": "CHECKBOX",
    "title": "Size A1B2C3",
    "instructions": "",
    "description": "",
    "rules": {
      "minSelections": 1,
      "maxSelections": 1,
      "maxPerOption": 1
    },
    "options": [
      {
        "id": "d95c2634-be3f-6584-0153-043bf5db0485",
        "label": "Small",
        "additionalCostMinor": 0,
        "additionalCalories": 0,
        "defaultQuantity": 0,
        "available": true
      },
      {
        "id": "ea84a0e6-0317-6595-b1da-fd3c12c44469",
        "label": "Large",
        "additionalCostMinor": 150,
        "additionalCalories": 0,
        "defaultQuantity": 0,
        "available": true
      },
      {
        "id": "db34021b-0c0d-66b9-087f-d44164298ca0",
        "label": "Huge",
        "additionalCostMinor": 300,
        "additionalCalories": 0,
        "defaultQuantity": 0,
        "available": false
      }
    ],
    "testMode": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  },
  "message": "Modifier deleted",
  "deleted": true
}

Errors

Every error answers with a message. A request that fails validation is a 400:

json

{
  "message": "An API key in test mode cannot create a live mode modifier."
}