Catalog setup
Build the catalog a coffee shop needs: a croissant, a latte in two sizes, a milk choice with its own price, and a breakfast combo. Then put them on an order. Flint prices every line, choice, and combo from the catalog, so your code never adds 75 cents for oat milk.
The same catalog serves online stores and restaurants alike. Swap the latte for a t-shirt in three sizes and the milk choice for gift wrap, and every call below stays the same.
The API reference covers every field on products and variants, categories, modifiers, and bundles.
The model in one paragraph#
A product is what you sell, by name: a latte. It has no price or SKU. Its variants are the units you sell, each with its own price and SKU: the 12 oz latte and the 16 oz latte. Options label the variants: Size, with the values 12 oz and 16 oz. Categories group products and bundles for filtering and for promotion and return targeting. A modifier set holds the choices a buyer makes at purchase time, such as oat milk or a name on the cup. A bundle sells several variants as one line at its own price. An order line names a variant_id or a bundle_id, never a product_id, and Flint copies the name, price, and SKU from the catalog onto the line. A variant line takes the variant's tax settings; a bundle line takes the taxability and category shared by its components.
| Resource | Routes | What you use it for |
|---|---|---|
| Products, variants, options | /v1/products, /v1/products/{product_id}/variants, /v1/products/{product_id}/options | What you sell and its prices |
| Categories | /v1/categories | Grouping, filtering, and targeting |
| Modifier groups and sets | /v1/modifier-groups, /v1/modifier-sets | Choices made at purchase time |
| Bundles | /v1/bundles | Several variants sold as one line |
Products, variants, and options need the commerce.products scopes. Categories and modifiers need commerce.catalog. Bundles need commerce.bundles. Promotions and promotion codes need commerce.promotions. Each scope has a .read and a .write form. expand=modifier_set on a product, variant, or bundle, or on their lists, needs the read scope for that item plus commerce.catalog.read, and expand=promotion on promotion codes needs commerce.promotions.read.
Sale reference prices#
Set a variant's optional compare_at_price_money to store its original or "was" price. For example, a variant priced at {"amount":3600,"currency":"USD"} can have compare_at_price_money: {"amount":4500,"currency":"USD"}. Both prices use the currency's smallest unit. The compare-at price must use the same currency and be strictly greater than unit_price_money.
Create it through default_variant, an inline variants entry, or the variant create route. Variant reads and expand=variants return the value, or null when none is set. On PATCH, omit it to preserve it or send null to clear it. If you raise the base price to the compare-at price or above, or change its currency, replace or clear the compare-at price in the same PATCH.
The compare-at price is a display reference. It does not change the amount charged or quantity price breaks. When importing from Shopify, map each variant's compare-at price to compare_at_price_money and its selling price to unit_price_money.
1. Create categories#
Categories group products and bundles for filtering and for promotion and return targeting. Create each category before you assign it. Products and bundles reference categories by handle, and a write that names a handle that doesn't exist fails instead of creating one.
curl -X POST https://api.withflintpay.com/v1/categories \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: category-espresso-drinks" \
-H "Content-Type: application/json" \
-d '{ "name": "Espresso drinks", "handle": "espresso-drinks" }'
{
"data": {
"category_id": "ctg_1kmn0bExample",
"handle": "espresso-drinks",
"name": "Espresso drinks",
"status": "active",
"version": 1
}
}
The response is abridged. Omit handle and Flint derives a lowercase, hyphenated one from the name: Espresso drinks becomes espresso-drinks. Create pastries and combos the same way for the steps below.
A handle never changes, even when you rename the category, so use it anywhere a category is stored:
- Assign categories to a product or bundle with
category_handles. - Filter the catalog with
GET /v1/products?category_handle=espresso-drinks. Bundles accept the same filter. - Target a promotion with a
line_item.categoriesrule, or a return policy withcategory_handles.
2. Create a product with one price#
A croissant comes in one form, so it is a simple product with a default_variant. The price, SKU, and tax settings go on the variant.
curl -X POST https://api.withflintpay.com/v1/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: product-croissant" \
-H "Content-Type: application/json" \
-d '{
"variant_mode": "simple",
"name": "Butter croissant",
"product_type": "physical",
"category_handles": ["pastries"],
"default_variant": {
"sku": "PAS-CROISSANT",
"unit_price_money": { "amount": 450, "currency": "USD" },
"line_item_tax_category": "prepared_food"
}
}'
{
"data": {
"product_id": "prod_1kmn0aExample",
"name": "Butter croissant",
"product_type": "physical",
"status": "active",
"version": 1,
"default_variant_id": "var_1kmn0aExample",
"variant_count": 1,
"is_available_for_sale": true,
"categories": [
{ "category_id": "ctg_1kmn0aExample", "handle": "pastries" }
]
}
}
The response is abridged. default_variant_id is the ID you sell. Sending unit_price_money, sku, taxable, or line_item_tax_category on the product itself returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD and the field in param.
product_type is physical, service, fee, digital, or gift_card. A physical variant created without delivery_profile_id gets your default delivery profile. A digital or service variant gets no default; send a manual profile as delivery_profile_id only if you want to create its fulfillments in Flint. Variants do not track stock unless you link an inventory item. The Inventory guide covers that.
For product_type: digital, omitting line_item_tax_category stores digital_goods on each new variant. This applies to default_variant, to variants created with the product, and to POST /v1/products/{product_id}/variants. Reads return the stored category, and you can edit it later. An explicit category is preserved.
Changing an existing product's product_type to digital fills only its variants' unset categories with digital_goods and advances those variants' versions. Other existing variants keep their categories. If the change would give a bundle mixed tax treatment, Flint refuses the whole change with 409 ACTION_NOT_ALLOWED, reason mixed_tax_treatment, and the bundles in blocking_resources.
Gift card variants require USD and are non-taxable. Omit line_item_tax_category, inventory_item_id, inventory_item, modifier_set_id, and delivery_profile_id. They do not require delivery, cannot be included in bundles or subscriptions, and are excluded from ordinary cart discounts. Existing gift card value can pay for other goods in the same order, but cannot pay for a new gift card purchase. Create a separate product to change to or from product_type: gift_card.
For a deliberate discounted offer, put the issued value in gift_card_configuration.face_value_money and the price paid in unit_price_money. For example, a $100 gift card sold for $90 uses:
{
"unit_price_money": { "amount": 9000, "currency": "USD" },
"gift_card_configuration": {
"face_value_money": { "amount": 10000, "currency": "USD" },
"price_mode": "discounted"
}
}
Omitting the configuration creates a fixed denomination at the variant price. Optional custom_amount_bounds define minimum and maximum USD face values; the reference face value must fall within them. Face values and bounds cannot exceed 200000 cents per card. Custom prices use the configured price-to-face-value ratio with cent rounding. An update preserves the configuration when omitted and replaces it when provided. To change the price of a face_value variant, send the configuration with the new face_value_money too. Include expected_version to reject a concurrent change.
Sell, redeem, and refund gift cards takes a gift card from this product through sale, delivery, redemption, and refund.
3. Create a product with sizes#
A latte comes in two sizes. Send options and variants together instead of default_variant. Flint never generates variants from options, so list every variant you sell. Each variant selects exactly one value for each option.
curl -X POST https://api.withflintpay.com/v1/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: product-latte" \
-H "Content-Type: application/json" \
-d '{
"variant_mode": "optioned",
"name": "Latte",
"product_type": "physical",
"category_handles": ["espresso-drinks"],
"options": [{
"name": "Size",
"values": [{ "value": "12 oz" }, { "value": "16 oz" }]
}],
"variants": [
{
"name": "12 oz",
"sku": "ESP-LATTE-12",
"unit_price_money": { "amount": 475, "currency": "USD" },
"line_item_tax_category": "prepared_food",
"selected_options": [{ "option_name": "Size", "value": "12 oz" }]
},
{
"name": "16 oz",
"sku": "ESP-LATTE-16",
"unit_price_money": { "amount": 525, "currency": "USD" },
"line_item_tax_category": "prepared_food",
"selected_options": [{ "option_name": "Size", "value": "16 oz" }]
}
]
}'
Each variant selects values by option_name and value, so you don't need IDs, even for options created in the same request. Names match case-insensitively: "size" selects the Size option. A variant names one value for each active option, and no two variants of a product can select the same combination. Flint assigns opt_ and optv_ IDs to the options and values and returns them in the product's options array.
The 201 response returns the variants it created in variants, ordered by position and then variant_id, so you get every variant_id without another request (abridged):
{
"data": {
"product_id": "prod_1kmn0bExample",
"name": "Latte",
"variant_count": 2,
"variants": [
{
"variant_id": "var_1kmn0bExample",
"name": "12 oz",
"sku": "ESP-LATTE-12",
"selected_options": [{ "option_id": "opt_1kmn0aExample", "option_name": "Size", "option_value_id": "optv_1kmn0aExample", "value": "12 oz" }]
},
{
"variant_id": "var_1kmn0cExample",
"name": "16 oz",
"sku": "ESP-LATTE-16",
"selected_options": [{ "option_id": "opt_1kmn0aExample", "option_name": "Size", "option_value_id": "optv_1kmn0bExample", "value": "16 oz" }]
}
]
}
}
Only the create response includes variants. Later reads of the product leave it out; list a product's variants with GET /v1/products/{product_id}/variants. An order line for the 16 oz variant is named Latte - 16 oz.
The rules Flint enforces when you create a product like this:
- Send
default_variantoroptionswithvariants, never both. Mixing them returns400 INVALID_REQUEST. - Two variants cannot select the same combination of values.
- All active variants of one product use the same currency.
- A SKU is unique across every variant and bundle in the environment.
- One create request takes at most 100
variants. Add more withPOST /v1/products/{product_id}/variants.
To add a size later, see Change the catalog later.
4. Change a product's categories#
To change a product's categories, send the complete category_handles set in PATCH /v1/products/{product_id}. It replaces every category the product had, and an empty array clears them. Order doesn't matter, and a handle can appear only once. Category changes don't need expected_version, so you can send them without reading the product first. A product or bundle can have up to 100 categories. For example, after you create a seasonal category, add the latte to it:
curl -X PATCH https://api.withflintpay.com/v1/products/prod_1kmn0bExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "category_handles": ["espresso-drinks", "seasonal"] }'
A handle that doesn't match a category returns 404 RESOURCE_NOT_FOUND with param naming the entry, such as category_handles[1], and details[0].resource_type set to category. Nothing is saved. Handles must match exactly: Flint doesn't match category names or change letter case.
Before deleting a category, check its assigned_product_count, assigned_bundle_count, and targeting_reference_count. If any is above zero, deletion returns 409 RESOURCE_IN_USE; all three must be zero before you can delete the category. details[0].blocking_resources lists what still uses it, up to 25, with the total in blocking_resource_count.
targeting_reference_count counts each referencing promotion, return reason, or return policy once. Ended promotions and promotions that have used up their limit still count; deleted promotions don't. Historical return policy revisions still count, even after a newer revision stops referencing the category. Several rules or revisions of the same resource count as one reference.
5. Add modifiers#
A buyer ordering a latte picks a milk, may add an extra shot, and gives a name for the cup. Modifiers have three layers:
- A modifier group is one prompt with its own selection rules. A
listgroup offers choices, and atextgroup takes free text. - A modifier is one choice in a list group, with an optional
unit_price_delta_moneyand its owntaxableandline_item_tax_category. - A modifier set puts groups in order and attaches to a product, variant, or bundle.
Create a reusable group#
Every espresso drink on the menu offers the same milk choice, so create it once as an independent group. min_selected and max_selected of 1 make it exactly one choice.
curl -X POST https://api.withflintpay.com/v1/modifier-groups \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: modifier-group-milk" \
-H "Content-Type: application/json" \
-d '{
"name": "Milk",
"modifier_group_type": "list",
"min_selected": 1,
"max_selected": 1,
"modifiers": [
{ "name": "Whole milk", "position": 0 },
{ "name": "Oat milk", "position": 1, "unit_price_delta_money": { "amount": 75, "currency": "USD" } }
]
}'
The response returns the group's mg_ ID and each choice's mod_ ID. Group rules must be satisfiable: a list group needs enough active choices to meet min_selected, and quantity limits require "allow_quantities": true.
Create the set#
The set combines the Milk group with two groups that belong only to this set. Use "source": "existing" for a group you created separately and "source": "inline" to create a group inside the set.
curl -X POST https://api.withflintpay.com/v1/modifier-sets \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: modifier-set-espresso" \
-H "Content-Type: application/json" \
-d '{
"name": "Espresso drink choices",
"modifier_groups": [
{ "source": "existing", "modifier_group_id": "mg_1kmn0aExample", "position": 0 },
{
"source": "inline",
"position": 1,
"modifier_group": {
"name": "Extra shot",
"min_selected": 0,
"max_selected": 1,
"allow_quantities": true,
"max_quantity": 3,
"modifiers": [
{ "name": "Extra shot", "unit_price_delta_money": { "amount": 100, "currency": "USD" } }
]
}
},
{
"source": "inline",
"position": 2,
"modifier_group": {
"name": "Name on cup",
"modifier_group_type": "text",
"text": { "required": false, "max_length": 20 }
}
}
]
}'
Text min_length and max_length count UTF-8 bytes after trimming whitespace. Non-ASCII characters can use several bytes, so the Name on cup limit of 20 bytes may allow fewer than 20 characters.
An inline group is not available through /v1/modifier-groups. Edit it by sending the set's complete modifier_groups array to PATCH /v1/modifier-sets/{modifier_set_id} with expected_version. Include the IDs of the groups and choices you keep. A set can also override a group's display_name for this set only. A list group accepts only min_selected and max_selected as rule overrides; a text group accepts only required. Sending the other type's field returns 400 INVALID_REQUEST with detail code NOT_ALLOWED. Without an override, the set uses the group's own value. modifier_overrides can set available: false to take a choice out of the set, or change its price. Set overrides lists every override.
Attach the set#
Attach the set to the latte product. Every latte variant then offers these choices.
curl -X PATCH https://api.withflintpay.com/v1/products/prod_1kmn0bExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "modifier_set_id": "ms_1kmn0aExample" }'
A catalog item holds one modifier set, and you can set modifier_set_id on a product, a variant, or a bundle. Send null to remove it. When Flint prices a line, it uses:
- On a bundle line, the bundle's set only. A bundle does not inherit its components' sets.
- On a variant line, the variant's set if it has one, and otherwise the product's set.
Read a product with expand=modifier_set to get the set, its groups, and their choices in one response. GET /v1/products, GET /v1/products/{product_id}/variants, and GET /v1/bundles accept the same path, so a menu screen can render a page of items with their sets from one request. Every set entry includes modifier_group_id and the full modifier_group, for both reusable and inline groups. Embedded groups exclude archived choices, even when the group is archived. Flint reads the sets, groups, and choices in batches for the page, each row's modifier_set matches the detail read, and a row without modifier_set_id returns modifier_set: null. See Expanding responses. A priced choice uses the currency of the line it is sold on. A mismatch returns 400 INVALID_REQUEST with detail code NOT_ALLOWED.
For example, the expanded latte includes the reusable Milk group and the inline Name on cup group in the same shape. The response is abridged:
{
"data": {
"product_id": "prod_1kmn0bExample",
"modifier_set_id": "ms_1kmn0aExample",
"modifier_set": {
"modifier_set_id": "ms_1kmn0aExample",
"modifier_groups": [
{
"source": "existing",
"modifier_set_group_id": "msg_1kmn0aExample",
"modifier_group_id": "mg_1kmn0aExample",
"position": 0,
"modifier_group": {
"modifier_group_id": "mg_1kmn0aExample",
"name": "Milk",
"modifier_group_type": "list",
"min_selected": 1,
"max_selected": 1,
"modifiers": [
{ "modifier_id": "mod_1kmn0aExample", "name": "Whole milk", "position": 0 },
{ "modifier_id": "mod_1kmn0bExample", "name": "Oat milk", "position": 1, "unit_price_delta_money": { "amount": 75, "currency": "USD" } }
]
}
},
{
"source": "inline",
"modifier_set_group_id": "msg_1kmn0cExample",
"modifier_group_id": "mg_1kmn0cExample",
"position": 2,
"modifier_group": {
"modifier_group_id": "mg_1kmn0cExample",
"name": "Name on cup",
"modifier_group_type": "text",
"text": { "required": false, "max_length": 20 },
"modifiers": []
}
}
]
}
}
}
6. Create a bundle#
The breakfast combo sells a croissant and a 12 oz latte for $7.50 instead of $9.25. The bundle has its own price and SKU, and each component names a variant and a quantity. Its components must share taxable and line_item_tax_category. The croissant and latte variants above all use prepared_food, so the bundle line uses that category too.
curl -X POST https://api.withflintpay.com/v1/bundles \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: bundle-breakfast-combo" \
-H "Content-Type: application/json" \
-d '{
"name": "Breakfast combo",
"sku": "CMB-BREAKFAST",
"status": "active",
"unit_price_money": { "amount": 750, "currency": "USD" },
"category_handles": ["combos"],
"components": [
{ "variant_id": "var_1kmn0aExample", "quantity": 1, "position": 0 },
{ "variant_id": "var_1kmn0bExample", "quantity": 1, "position": 1 }
]
}'
An unset component category means the merchant default and equals only another unset category, even if an explicit category currently matches that default. Bundle create or component replacement compares each component with the first component in the request. Each differing component gets a 400 INVALID_REQUEST detail with code NOT_ALLOWED at its components[index].variant_id, naming the differing attribute. A variant or product change that would make an existing bundle mixed returns 409 ACTION_NOT_ALLOWED with reason mixed_tax_treatment and the bundles in blocking_resources. Remove the component from its bundle before changing its tax treatment, or choose components that already share the same treatment.
A bundle created without status is active, as products and variants are, so the request needs the components above. To create a draft first, send "status": "inactive" and activate it later with PATCH /v1/bundles/{bundle_id}.
An active bundle needs at least one component, and every component's product and variant must be active. A physical component also needs an active delivery profile, which it copies from its variant unless you send delivery_profile_id on the component.
is_available_for_sale on a bundle is true when the bundle is active, has at least one component, every component's variant and product are active, and the bundle's delivery_configuration_status isn't action_required. A bundle with no components reports delivery_configuration_status: not_applicable and isn't available for sale. Availability does not guarantee stock. Flint checks and holds each tracked component's stock when the order claims it.
The latte in this combo gets no milk choice, because a bundle line uses only the bundle's own modifier set. To offer milk in the combo, set modifier_set_id on the bundle.
7. Sell it#
Create an order that names catalog items. The first line is two 16 oz oat milk lattes with an extra shot and a name. The second is the combo.
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-counter-0412" \
-H "Content-Type: application/json" \
-d '{
"line_items": [
{
"type": "variant",
"variant_id": "var_1kmn0cExample",
"quantity": 2,
"modifiers": [
{ "type": "catalog", "modifier_id": "mod_1kmn0bExample" },
{ "type": "catalog", "modifier_id": "mod_1kmn0cExample", "quantity": 1 },
{ "type": "text", "text": { "modifier_group_id": "mg_1kmn0cExample", "value": "Sam" } }
]
},
{ "type": "bundle", "bundle_id": "bun_1kmn0aExample", "quantity": 1 }
]
}'
Each line item names its source in type: variant, bundle, or custom. For a list choice, send a modifier with type catalog and its modifier_id, plus quantity when the group allows quantities. For a text group, send type text and text with the group's modifier_group_id and the value. Flint resolves the rest:
{
"data": {
"order_id": "ord_1kmn0aExample",
"line_items": [
{
"type": "variant",
"variant_id": "var_1kmn0cExample",
"name": "Latte - 16 oz",
"sku": "ESP-LATTE-16",
"quantity": 2,
"unit_price_money": { "amount": 525, "currency": "USD" },
"base_subtotal_money": { "amount": 1050, "currency": "USD" },
"modifiers": [
{
"modifier_group_name": "Milk",
"name": "Oat milk",
"quantity": 1,
"unit_price_delta_money": { "amount": 75, "currency": "USD" },
"total_money": { "amount": 150, "currency": "USD" }
},
{
"modifier_group_name": "Extra shot",
"name": "Extra shot",
"quantity": 1,
"unit_price_delta_money": { "amount": 100, "currency": "USD" },
"total_money": { "amount": 200, "currency": "USD" }
},
{
"modifier_group_name": "Name on cup",
"name": "Name on cup",
"text_value": "Sam",
"quantity": 1,
"unit_price_delta_money": { "amount": 0, "currency": "USD" },
"total_money": { "amount": 0, "currency": "USD" }
}
],
"modifier_total_money": { "amount": 350, "currency": "USD" },
"subtotal_money": { "amount": 1400, "currency": "USD" }
},
{
"type": "bundle",
"bundle_id": "bun_1kmn0aExample",
"name": "Breakfast combo",
"quantity": 1,
"unit_price_money": { "amount": 750, "currency": "USD" },
"subtotal_money": { "amount": 750, "currency": "USD" }
}
]
}
}
The response is abridged. A choice's total_money is its price change times its quantity times the line quantity, so two lattes with oat milk add $1.50. subtotal_money is the base subtotal plus modifier_total_money. The bundle line also returns bundle_components so a kitchen ticket or packing slip can list what goes in the combo.
Flint enforces each group's rules on the order. Leaving out the milk returns 400 INVALID_REQUEST with detail code REQUIRED, and picking two milks returns 400 INVALID_REQUEST with detail code INVALID_VALUE. Modifiers work only on lines whose variant, product, or bundle has a modifier set.
Flint copies the catalog onto the line when the order is created. Catalog lines reject a caller-supplied name, unit_price_money, or tax setting with 400 INVALID_REQUEST and detail code NOT_ALLOWED. For an item that is not in the catalog, send an ad hoc line with name, unit_price_money, and a fulfillment requirement instead of a catalog ID. Ad hoc lines cannot carry modifiers.
Payment links accept the same variant_id and bundle_id line sources. A payment link can also list several variants of one product in variant_ids, so the buyer chooses a size or color at checkout. A checkout session collects payment for an order like this one. To change a line's choices after the order exists, see Replace a line item's selections.
Set prices for larger quantities#
Add quantity_price_breaks to a variant to charge a lower unit price when one line reaches a quantity threshold. For a $10.00 base price, this variant update stores $8.00 per unit at 10 units and $7.00 per unit at 25 units:
{
"unit_price_money": { "amount": 1000, "currency": "USD" },
"quantity_price_breaks": [
{ "minimum_quantity": 10, "unit_price_money": { "amount": 800, "currency": "USD" } },
{ "minimum_quantity": 25, "unit_price_money": { "amount": 700, "currency": "USD" } }
]
}
Send it to PATCH /v1/products/{product_id}/variants/{variant_id}, or include the fields when creating a variant. Use up to 10 breaks, with increasing minimum quantities of at least 2 and decreasing positive prices in the base price's currency. Gift card variants cannot have breaks. Quantities on separate lines are not combined.
Send the complete array on an update. [] removes every break, omission preserves them, and null is invalid. If you lower the base below a stored break, replace or clear the breaks in that same request. Include the variant's version as expected_version to reject a concurrent edit. See Quantity price breaks for the complete rules.
Change the catalog later#
Most updates are sparse: send only the fields you are changing. null clears an optional field, such as description, sku, modifier_set_id, or metadata; null on a required field or a list returns 400 INVALID_REQUEST (detail INVALID_VALUE). An empty string is never a clear: "" in a field or metadata value returns 400 INVALID_REQUEST with param naming the field. A text modifier group's text object changes only the settings you send. metadata holds at most 50 keys after your changes are merged; see Metadata and your own IDs. Some fields are complete lists, and Flint replaces the whole list in one write:
| List | Where |
|---|---|
options and their values | PATCH /v1/products/{product_id} |
category_handles | Product and bundle PATCH, with no expected_version needed |
images | Product, variant, and bundle PATCH |
components | PATCH /v1/bundles/{bundle_id} |
modifiers | PATCH /v1/modifier-groups/{modifier_group_id} |
modifier_groups | PATCH /v1/modifier-sets/{modifier_set_id} |
A replacement requires the version you last read as expected_version. Include the ID of every member you keep, add new members without an ID, and leave out a member to retire it. If someone else changed the resource since you read it, the write returns 409 VERSION_CONFLICT with details[0].current_version. Read it again and retry with the new version.
For example, to add a 20 oz size, send the complete options array with the IDs you already have and the new value without one:
{
"expected_version": 2,
"options": [{
"option_id": "opt_1kmn0aExample",
"name": "Size",
"values": [
{ "option_value_id": "optv_1kmn0aExample", "value": "12 oz" },
{ "option_value_id": "optv_1kmn0bExample", "value": "16 oz" },
{ "value": "20 oz" }
]
}]
}
Then create the variant with POST /v1/products/{product_id}/variants. The body takes the same fields as one entry in variants on product create:
curl -X POST https://api.withflintpay.com/v1/products/prod_1kmn0bExample/variants \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: variant-latte-20" \
-H "Content-Type: application/json" \
-d '{
"name": "20 oz",
"sku": "ESP-LATTE-20",
"unit_price_money": { "amount": 575, "currency": "USD" },
"line_item_tax_category": "prepared_food",
"selected_options": [{ "option_name": "Size", "value": "20 oz" }]
}'
A name that matches no option or value on the product returns 404 RESOURCE_NOT_FOUND. param names the entry, such as selected_options[0].value, and details[0].resource_type is product_option or product_option_value.
To move an existing variant to other values, send its complete selected_options in PATCH /v1/products/{product_id}/variants/{variant_id}. The variant keeps its variant_id, so inventory items, payment links, and bundles still point at it, and orders placed before the change keep the values they were placed with. The same rules apply as on create: name one value for each active option, and a combination another variant already uses returns 409 ALREADY_EXISTS, with that variant in details[0].current_resource.
A variant keeps its selection for an option you've since removed or set to inactive, and returns it in selected_options. A value of an option that is still active can't be removed or set to inactive while an active variant selects it. On update, you can resend that entry unchanged or leave it out, and the variant keeps it either way. If you replaced an option with a new one of the same name, such as a new Size, selecting a value of the new option replaces the old selection. Changing it, or naming an inactive or removed option or value the variant doesn't already select, returns the same error as on create. On a product with no active options, "selected_options": [] changes nothing.
Record a variant's weight and dimensions#
A physical variant can carry the weight and dimensions of one unit you sell. Add unit_weight and unit_dimensions to the request that creates the variant: the body of POST /v1/products/{product_id}/variants, or an entry in variants on product create. Here is the 20 oz latte from the request above, with the packed weight and size of a filled cup:
{
"name": "20 oz",
"sku": "ESP-LATTE-20",
"unit_price_money": { "amount": 575, "currency": "USD" },
"line_item_tax_category": "prepared_food",
"selected_options": [{ "option_name": "Size", "value": "20 oz" }],
"unit_weight": { "value": 1.5, "unit": "pound" },
"unit_dimensions": { "length": 3.75, "width": 3.75, "height": 6.5, "unit": "inch" }
}
Weight units are gram, kilogram, ounce, and pound. Dimension units are millimeter, centimeter, and inch. Values are greater than 0 with at most 3 decimal places, a weight is at most 1,000,000, and each dimension is at most 100,000. Both fields are optional, and a variant that doesn't have them leaves them out of reads.
To change one, send the complete object in PATCH /v1/products/{product_id}/variants/{variant_id}. Flint replaces the object, so {"unit_weight": {"value": 13, "unit": "ounce"}} needs both value and unit, and leaves unit_dimensions alone. Send null to remove one:
curl -X PATCH https://api.withflintpay.com/v1/products/prod_1kmn0bExample/variants/var_1kmn0cExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "unit_dimensions": null }'
Package weight and dimensions on a shipment use the same shapes, so a weight you read from a variant can go on a package unchanged.
The variant is where weight lives. Delivery profiles carry none, and Flint prices delivery from the variant's unit_weight. Each order line records the variant's unit_weight and unit_dimensions when you create it, so editing a variant changes later orders and subscription renewals but not existing lines. A custom line takes unit_weight and unit_dimensions on the line itself. A variant with no unit_weight has an unknown weight, so a delivery option that prices by weight isn't offered for an order that includes it.
Add an option to a product that has variants#
Every active variant needs a value for each active option, so adding an option to a product that already sells variants also says which value those variants get. Add existing_variant_value to the new option's entry. To add a Milk option to the latte, whose 12 oz and 16 oz variants are both active:
curl -X PATCH https://api.withflintpay.com/v1/products/prod_1kmn0bExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: product-latte-add-milk" \
-H "Content-Type: application/json" \
-d '{
"expected_version": 3,
"options": [
{
"option_id": "opt_1kmn0aExample",
"name": "Size",
"values": [
{ "option_value_id": "optv_1kmn0aExample", "value": "12 oz" },
{ "option_value_id": "optv_1kmn0bExample", "value": "16 oz" }
]
},
{
"name": "Milk",
"existing_variant_value": "Whole",
"values": [{ "value": "Whole" }, { "value": "Oat" }]
}
]
}'
Both active variants now select Milk: Whole. Flint changes the option and the variants in one transaction. Each changed variant gets a new version and sends product_variant.updated, and the product sends product.updated. Inactive variants are not touched. To give a variant another value, send its complete selected_options in PATCH /v1/products/{product_id}/variants/{variant_id}.
existing_variant_value must match one of the option's active values, ignoring case and surrounding whitespace. If active variants need a value and you leave it out, the request returns 400 INVALID_REQUEST with detail code REQUIRED and param such as options[1].existing_variant_value, and nothing changes. Reactivating an inactive option works the same way, and a variant that already has an active value for the option keeps it. Flint doesn't store the field, so a later read shows only the variants' selected_options.
Edit an active bundle's components#
Send the complete components array and the bundle's version to PATCH /v1/bundles/{bundle_id}. The bundle can stay active. Every new component's variant and product must be active, and the bundle keeps at least one component. Existing orders, checkout sessions, invoices, subscriptions, and plans keep the components they were created with. New orders use the new components, and payment links resolve them the next time they are read.
A few changes are blocked while something depends on them:
- A variant in an active bundle cannot be retired, and its values for active options cannot change (
409 RESOURCE_IN_USE, listing thebundlereferences). Resending its currentselected_optionsis allowed. Backfilling a value for a new option is also allowed. - Removing or inactivating an option value that an active variant selects returns
409 RESOURCE_IN_USEwithparamsuch asoptions[0].values.details[0].blocking_resourceslists up to 10product_variantreferences. Move those variants to another value or set them toinactive, then retry. Retiring a whole option is allowed. - Setting a variant or bundle to
inactivestops for an open checkout session, an open invoice payment attempt, an active payment link, a subscription plan that isn't archived, or an active subscription that uses it. An open order doesn't stop it, because the order keeps its snapshot. A payment link line that lets buyers choose among variants (variant_ids) stops a variant only when no other listed variant would stay active, and it stops its product while the link is active. Deleting, or changing the currency of, an item on an open order still returns409 RESOURCE_IN_USE.
Edit with the version you read#
When two people or systems edit the same catalog item, send the version your edit started from. A complete-list replacement requires it, and other updates and DELETE accept it. Keep the version from the read your draft was built on, not from a later refresh, so a save can't silently undo a change you never saw.
Categories work the same way, with one difference: a category's version increases when you change it, and also when a product or bundle joins or leaves it or a promotion or return configuration starts or stops targeting it, because those change its counts. Redeeming a promotion or releasing its reserved use does not change the category's version. To rename espresso-drinks only if nobody changed it since you read it at version 4:
curl -X PATCH https://api.withflintpay.com/v1/categories/ctg_1kmn0bExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: category-espresso-rename-v4" \
-H "Content-Type: application/json" \
-d '{ "expected_version": 4, "name": "Espresso and tea" }'
If the category is now at version 5, the request returns 409 VERSION_CONFLICT with details[0].current_version set to 5, and the name doesn't change. Keep your draft, read the category again, and check what changed. A count change leaves the name you edited as it was, so send the rename again with "expected_version": 5. If someone renamed it, choose which name to keep before you send. Either way, the conflict's next_steps says whether you can reuse its Idempotency-Key. To delete a category only at the version you checked, send DELETE /v1/categories/{category_id}?expected_version=5.
Retire what you no longer sell#
DELETE archives products, variants, bundles, modifier groups, modifier sets, promotions, and promotion codes. The response is the archived item, exactly as a following GET returns it. Archived items stay readable by ID, so past orders keep their references. List endpoints return them when you filter for status=archived.
Repeating a DELETE is safe. It returns 200 with the archived item and changes nothing: updated_at stays the same, Flint checks no references, and no webhook is sent. If you send expected_version, Flint checks it first, so a stale value still returns 409 VERSION_CONFLICT.
An archived item can't be changed. Any write to it returns 409 ACTION_NOT_ALLOWED with reason: archived and current_status: archived in details[0], which names the archived item in resource_type and resource_id. Creating a variant under an archived product names the product, and creating a promotion code under an archived promotion names the promotion. Retrying doesn't help, so remediation.retry is none. For something you only want to pause, set status to inactive instead. That is reversible, and archiving is not.
Flint blocks archiving while the item is still in use:
- A product, variant, or bundle on an open order, an open checkout session, an active payment link, an active subscription, a subscription plan that isn't archived, or an active bundle. A variant listed in a payment link's
variant_idsblocks archiving only when it is the last active one listed. - A modifier group that a modifier set still uses.
- A modifier set attached to an active catalog item.
- The default variant of a simple product. Archive the product instead.
A refusal for something in use returns 409 RESOURCE_IN_USE. details[0].blocking_resources lists every record in the way, up to 25, such as the order, checkout_session, payment_link, subscription, subscription_plan, bundle, or modifier_set references, and blocking_resource_count gives the total. A SKU, barcode, option name, or option combination another record already has returns 409 ALREADY_EXISTS, and details[0].current_resource names that record.
Keep another system in sync#
To mirror the catalog into a point-of-sale system, an ERP, or a search index, subscribe to the catalog events for changes as they happen, and read the lists to fill in what you missed.
Create an endpoint with the catalog events you mirror in enabled_events, or send ["*"] to receive every event. Catalog events lists them all.
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: webhook-endpoint-catalog-001" \
-d '{
"url": "https://example.com/webhooks/flint",
"enabled_events": [
"product.created",
"product.updated",
"product.archived",
"product_variant.created",
"product_variant.updated",
"product_variant.archived"
],
"description": "Catalog mirror"
}'
Then apply every event, and every row you read from a list, with the same rules:
- Store each object under its ID and keep the higher
version.data.objectis the resource as itsGETreturns it, at the change that sent the event. Store it byproduct_id,variant_id,bundle_id,price_list_id,category_id,modifier_group_id,modifier_set_id,promotion_id, orpromotion_code_id, and replace your copy only when the incomingversionis higher. Events can arrive out of order, so store aproduct_variant.createdthat arrives before itsproduct.created. Don't order copies byupdated_at, because separate changes can share a timestamp. - Every change sends one event for each resource it changes. That includes a change that reaches a resource from another one, such as a product's options reaching its variants, and a child change that moves its parent's counts or summaries, such as a variant's price moving its product's
price_range. Catalog events names every field. - Archives cascade, one event per child. Archiving a product sends
product_variant.archivedfor each variant it archives, and archiving a promotion sendspromotion_code.archivedfor each code it archives. Archived resources stay readable by ID, so keep them: past orders refer to them. - Deletes arrive as
category.deleted. Categories are deleted instead of archived, andGETreturns404afterward. Product and bundlecategoriescarry onlycategory_idandhandle, so read a category's name from your stored category. - A few fields change without an event. A promotion's and code's
available,unavailable_reason, anduses_count, and a promotion'scodes_summary.active_countandnewest_active_code, follow redemptions, schedules, and the clock. A return policy or return reason that starts or stops referencing a category changes itstargeting_reference_count. Catalog events lists each field and when it changes. - Event objects leave out stock and expansions. They leave out a variant's
inventory_availabilityand anything added withexpand. Read the variant again afterinventory_level.updated; see Show stock on a storefront.
Copying catalog data into another environment and resetting a sandbox send no events. Fill the mirror for that environment again from the lists.
Find a product from your own identifiers#
A mirror often knows a variant by its SKU, by the reference it stored in the variant's external_reference_id, or by the inventory item that stocks it. The product list finds the product from any of them:
| You have | Product list filter | Matches |
|---|---|---|
| A scanned barcode | barcode | The variant's barcode, byte for byte |
| A variant SKU | sku | The variant's sku, ignoring case and accents |
| Your variant reference | variant_external_reference_id | The variant's external_reference_id, byte for byte |
| An inventory item | inventory_item_id | The variant's inventory_item_id |
| Your product reference | external_reference_id | The product's external_reference_id, byte for byte |
curl "https://api.withflintpay.com/v1/products?variant_external_reference_id=erp-item-40213" \
-H "Authorization: Bearer YOUR_API_KEY"
Use GET /v1/products?barcode=0781234567890 to resolve a scan across your catalog. The nested variant list accepts the same barcode filter. Product query searches variant barcodes as well as SKUs and product text.
Every filter compares the whole value, never part of it, and none trims whitespace. A byte-for-byte reference keeps its case, spaces, and Unicode, so store the reference exactly as you sent it. Combine the variant filters to narrow the match: they must all hold for the same variant, so sku=ESP-LATTE-16&inventory_item_id=invi_... finds the latte only if its 16 oz variant draws from that item. Inactive variants match and archived ones don't. A filter that matches nothing returns an empty page, not an error.
When an exact variant filter is supplied, each returned product carries matched_variant. It names one matching variant: the first by position, then by variant_id. Store that variant_id when you expect one match. When several variants can match, such as variants that share one inventory item, page the product's variants with the same filters to read every one:
curl "https://api.withflintpay.com/v1/products/prod_1kmn0bExample/variants?inventory_item_id=invi_01K0P7W6A4N9F3J2T8Q5R1C6XM&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
On the variant list, external_reference_id is the variant's reference, so send your variant_external_reference_id value under that name. Find products through their variants covers the matching and validation rules.
Backfill and recover#
Read the lists to fill a new mirror, and to recover after an outage longer than Flint's retry window of about three days. Read each list once, oldest change first, with every status:
status=active,inactive,archived&sort_by=updated_at&sort_direction=asc&page_size=100
Use it on GET /v1/products with expand=variants, and on GET /v1/bundles, GET /v1/price-lists, GET /v1/modifier-groups, GET /v1/modifier-sets, GET /v1/promotions, and GET /v1/promotion-codes. GET /v1/categories has no status filter, so read it without one. Follow next_page_token until it is empty, keeping the other parameters unchanged. To fill a new mirror with every product and its variants:
curl "https://api.withflintpay.com/v1/products?status=active,inactive,archived&expand=variants&sort_by=updated_at&sort_direction=asc&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
Apply each product with the rules above, then replace its stored variant set with its variants, keeping the higher version of any variant you already have. The array holds every active and inactive variant, ordered by position then variant_id, so a stored variant missing from it is archived. An archived product returns variants: []. A page holds at most 500 expanded variants, so it can return fewer products than page_size, and a product's variants are never split across pages. A price list carries price_count, not its prices: read GET /v1/price-lists/{price_list_id}/prices for each list whose version advanced.
To recover, save the newest updated_at you read from each list, and set updated_after a few minutes before it, such as updated_after=2026-10-20T14:55:00Z. It is inclusive, so rows you already have come back, and applying them again is harmless. Read products and categories in full, without updated_after: a variant change that leaves its product's summaries alone, such as a new SKU on a variant other than the default, doesn't advance the product's updated_at, and a deleted category has no row. A category you stored that is missing from the full list was deleted.
Common errors#
The full list is in the error reference.
Related docs#
- Products API reference: products, variants, and options, including every list filter.
- Modifiers API reference: set overrides and replacing the selections on an existing order line.
- Bundles API reference and Categories API reference.
- Inventory: track stock for a variant and hold it when an order is paid.
- Images: galleries for products, variants, and bundles.
- Promotions: discounts that target categories.
- Catalog events: every event a mirror subscribes to.
Stripe has no variant or option fields. Stripe product variants compares a product per size and color with options and variants.
Customer price lists#
Use price lists to manage variant prices for individual customers or segment labels. Each list has its own base prices and optional quantity breaks. Manage the list with commerce.catalog.write; price lists are hidden from customer sessions.
At order creation and when adding a line, Flint checks the customer's active direct list for that variant, then the active list for the customer's segment, then the variant's own schedule. An inactive list stops providing prices but keeps its assignments. Each line uses its own quantity. Orders freeze the chosen schedule, so later list edits do not change existing lines. See wholesale pricing for setup and customer reassignment.