FlintflintDocs

Modifiers

Modifiers let buyers customize a line item at purchase time: size, toppings, add-ons, or free-text input like an engraving message. The model has three layers:

  • A modifier group is a single buyer-facing prompt (a choose-from-a-list group or a text input) with selection rules like min/max selected and per-choice quantities.
  • Each choice within a group is a modifier, with its own optional price adjustment and tax settings.
  • A modifier set collects groups into an ordered bundle, with per-set overrides for display, defaults, pricing, and availability.

Modifier set assignments attach a set to a catalog target: a product, a specific variant, or a bundle. When a buyer selects choices during checkout or when modifiers are set on an order line item, they become line-item modifiers that adjust the line total and flow through to receipts and fulfillment based on each modifier's visibility flags.

Endpoints

List modifier groups#

GET/v1/modifier-groupsRequires scope: commerce.catalog.read or commerce.catalog.write

List modifier groups.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by modifier group status.

activeinactivearchived
modifier_group_typeenum

Filter by modifier group type.

listtext
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/modifier-groups \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create modifier group#

POST/v1/modifier-groupsIdempotentRequires scope: commerce.catalog.write

Create modifier group.

Request body
allow_quantitiesbooleanrequired
max_quantityinteger

Whole-number quantity; fractional quantities are not supported.

max_selectedinteger
max_total_quantityinteger

Whole-number quantity; fractional quantities are not supported.

metadatamap of string
min_quantityinteger

Whole-number quantity; fractional quantities are not supported.

min_selectedinteger
modifier_group_typeenumrequired
listtext
modifiersarray of object
namestringrequired
show_on_fulfillmentboolean
show_on_receiptboolean
statusenum
activeinactive
textobject
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get modifier group#

GET/v1/modifier-groups/{modifier_group_id}Requires scope: commerce.catalog.read or commerce.catalog.write

Get modifier group.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/modifier-groups/mg_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update modifier group#

PATCH/v1/modifier-groups/{modifier_group_id}IdempotentRequires scope: commerce.catalog.write

Update modifier group.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

Request body
allow_quantitiesboolean
max_quantityinteger

Whole-number quantity; fractional quantities are not supported.

max_selectedinteger
max_total_quantityinteger

Whole-number quantity; fractional quantities are not supported.

metadatamap of string
min_quantityinteger

Whole-number quantity; fractional quantities are not supported.

min_selectedinteger
namestring
show_on_fulfillmentboolean
show_on_receiptboolean
statusenum
activeinactive
textobject
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/modifier-groups/mg_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Archive modifier group#

POST/v1/modifier-groups/{modifier_group_id}/archiveIdempotentRequires scope: commerce.catalog.write

Archive modifier group.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-groups/mg_123/archive \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create modifier#

POST/v1/modifier-groups/{modifier_group_id}/modifiersIdempotentRequires scope: commerce.catalog.write

Create modifier.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

Request body
default_quantityinteger

Whole-number quantity; fractional quantities are not supported.

metadatamap of string
namestringrequired
positioninteger
selected_by_defaultbooleanrequired
show_on_fulfillmentboolean
show_on_receiptboolean
statusenum
activeinactive
tax_categoryenum

Flint line-item tax category.

generalphysical_goodsdigital_goodssoftwaresaasservicesprofessional_servicesfoodprepared_foodclothingmedical_goodsadmission
taxableboolean
unit_price_delta_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-groups/mg_123/modifiers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace modifier group modifiers#

PUT/v1/modifier-groups/{modifier_group_id}/modifiersIdempotentRequires scope: commerce.catalog.write

Replace modifier group modifiers.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

Request body
modifiersarray of objectrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PUT https://api.withflintpay.com/v1/modifier-groups/mg_123/modifiers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update modifier#

PATCH/v1/modifier-groups/{modifier_group_id}/modifiers/{modifier_id}IdempotentRequires scope: commerce.catalog.write

Update modifier.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

modifier_idstringrequired

Flint modifier ID.

Request body
default_quantityinteger

Whole-number quantity; fractional quantities are not supported.

metadatamap of string
namestring
positioninteger
selected_by_defaultboolean
show_on_fulfillmentboolean
show_on_receiptboolean
statusenum
activeinactive
tax_categoryenum

Flint line-item tax category.

generalphysical_goodsdigital_goodssoftwaresaasservicesprofessional_servicesfoodprepared_foodclothingmedical_goodsadmission
taxableboolean
unit_price_delta_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/modifier-groups/mg_123/modifiers/mod_01JZEXAMPLEMODIFIER123456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Archive modifier#

POST/v1/modifier-groups/{modifier_group_id}/modifiers/{modifier_id}/archiveIdempotentRequires scope: commerce.catalog.write

Archive modifier.

Path parameters
modifier_group_idstringrequired

Flint modifier group ID.

modifier_idstringrequired

Flint modifier ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-groups/mg_123/modifiers/mod_01JZEXAMPLEMODIFIER123456/archive \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List modifier set assignments#

GET/v1/modifier-set-assignmentsRequires scope: commerce.catalog.read or commerce.catalog.write

List modifier set assignments.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

modifier_set_idstring

Filter by assigned modifier set.

target_product_idstring

Filter by product assignment target.

target_variant_idstring

Filter by variant assignment target.

target_bundle_idstring

Filter by bundle assignment target.

statusenum

Filter by assignment status.

activeinactiveremoved
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/modifier-set-assignments \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create modifier set assignment#

POST/v1/modifier-set-assignmentsIdempotentRequires scope: commerce.catalog.write

Create modifier set assignment.

Request body
bundle_idstring
modifier_set_idstringrequired
product_idstring
statusenum
activeinactive
variant_idstring
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-set-assignments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get modifier set assignment#

GET/v1/modifier-set-assignments/{modifier_set_assignment_id}Requires scope: commerce.catalog.read or commerce.catalog.write

Get modifier set assignment.

Path parameters
modifier_set_assignment_idstringrequired

Flint modifier set assignment ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/modifier-set-assignments/{modifier_set_assignment_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update modifier set assignment#

PATCH/v1/modifier-set-assignments/{modifier_set_assignment_id}IdempotentRequires scope: commerce.catalog.write

Update modifier set assignment.

Path parameters
modifier_set_assignment_idstringrequired

Flint modifier set assignment ID.

Request body
modifier_set_idstring
statusenum
activeinactive
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/modifier-set-assignments/{modifier_set_assignment_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete modifier set assignment#

DELETE/v1/modifier-set-assignments/{modifier_set_assignment_id}IdempotentRequires scope: commerce.catalog.write

Delete modifier set assignment.

Path parameters
modifier_set_assignment_idstringrequired

Flint modifier set assignment ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/modifier-set-assignments/{modifier_set_assignment_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List modifier sets#

GET/v1/modifier-setsRequires scope: commerce.catalog.read or commerce.catalog.write

List modifier sets.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by modifier set status.

activeinactivearchived
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/modifier-sets \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create modifier set#

POST/v1/modifier-setsIdempotentRequires scope: commerce.catalog.write

Create modifier set.

Request body
metadatamap of string
modifier_groupsarray of object
namestringrequired
statusenum
activeinactive
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-sets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get modifier set#

GET/v1/modifier-sets/{modifier_set_id}Requires scope: commerce.catalog.read or commerce.catalog.write

Get modifier set.

Path parameters
modifier_set_idstringrequired

Flint modifier set ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/modifier-sets/{modifier_set_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update modifier set#

PATCH/v1/modifier-sets/{modifier_set_id}IdempotentRequires scope: commerce.catalog.write

Update modifier set.

Path parameters
modifier_set_idstringrequired

Flint modifier set ID.

Request body
metadatamap of string
namestring
statusenum
activeinactive
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/modifier-sets/{modifier_set_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Archive modifier set#

POST/v1/modifier-sets/{modifier_set_id}/archiveIdempotentRequires scope: commerce.catalog.write

Archive modifier set.

Path parameters
modifier_set_idstringrequired

Flint modifier set ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/modifier-sets/{modifier_set_id}/archive \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace modifier set groups#

PUT/v1/modifier-sets/{modifier_set_id}/groupsIdempotentRequires scope: commerce.catalog.write

Replace modifier set groups.

Path parameters
modifier_set_idstringrequired

Flint modifier set ID.

Request body
modifier_groupsarray of objectrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PUT https://api.withflintpay.com/v1/modifier-sets/{modifier_set_id}/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc