Modifiers

A modifier is an option a shopper picks when ordering that doesn’t create a new SKU, such as engraving text, gift wrap or a subscription interval. You define a modifier once, then attach it to any number of products. If an option needs its own SKU, price or stock, use a variant instead.

In the admin

Create a modifier:

1. Go to Catalog → Modifiers.
2. Under Add a modifier, enter a name (for example “Ships every”) and choose a type.
3. Click Add. minipim generates the code from the name and opens the modifier editor.
4. In the editor you can change the Name and Type. For choice types, use Add choice to add each choice, with a Label, a Value and an optional Price change (None, Fixed or Percent) plus an Amount. Text types have Max length, and numbers have Min and Max.
5. Click Save changes.

Attach it to a product:

1. Open the product and scroll to the Modifiers section.
2. Choose one from Attach a modifier…, tick Required if the shopper must answer it, and click Attach.
3. Use the arrows to reorder attached modifiers, toggle Required, or click the × to detach one.

The types in the admin are Select (single), Select (multi), Text (one line), Text (multiline), Number, Yes / no and File upload.

With the API

Method	Path	What it does
GET, POST	/v1/modifiers	List or create modifier definitions
GET, PATCH, DELETE	/v1/modifiers/{id}	Read, update or delete a definition
GET, POST	/v1/products/{id}/modifiers	List or attach a product’s modifiers
PATCH, DELETE	/v1/products/{id}/modifiers/{modifierId}	Change isRequired/position, or detach

curl -X POST https://api.minipim.com/v1/modifiers \
  -H 'Authorization: Bearer pim_…' -H 'Content-Type: application/json' \
  -d '{
    "code": "gift_wrap",
    "label": { "en_US": "Gift wrap" },
    "type": "select",
    "validation": { "options": [
      { "value": "none", "label": "No thanks" },
      { "value": "premium", "label": "Premium wrap" }
    ]},
    "config": { "priceAdjusters": {
      "premium": { "adjuster": "fixed", "amount_cents": 500, "currency": "USD" }
    }}
  }'

Product reads include modifierCount and hasRequiredModifiers. @minipim/sdk ships helpers for reading choices and price changes, such as getModifierChoices and applyPriceAdjuster. See the SDK. Full reference: api.minipim.com/docs.

Rules and limits

• API types: text, textarea, select, multiselect, number, boolean, file.
• code must start with a lowercase letter and use only a-z, 0-9 and _. Codes are unique within an organization, and a duplicate returns 409.
• Choices live in validation.options as [{ value, label }], and values must be unique. Only select, multiselect and boolean can have choices.
• maxLength applies only to text types. min and max apply only to number, and min can’t be greater than max.
• Price changes live in config.priceAdjusters, keyed by choice value. A fixed change is integer cents plus a 3-letter ISO currency. A percentage change is integer basis_points. A price change for a value that isn’t one of the choices is rejected.
• Changing type to one that can’t hold the stored choices or prices is rejected unless the same request replaces them.
• Attaching a modifier that’s already on the product returns 409. Use PATCH to change it. Detaching is idempotent.
• Deleting a modifier removes it from every product it’s attached to.
• Modifiers imported from BigCommerce have codes starting with bc_mod_. The next pull replaces their name, type, choices and prices, so make lasting changes in BigCommerce. See Connectors.
• Every change emits a modifier.* or product_modifier.* event for webhooks.