Price lists
A price list stores a base net unit price and optional quantity breaks for each product variant. Lists belong to one merchant environment and are visible only to merchant credentials. Read them with commerce.catalog.read and manage them with commerce.catalog.write.
Create a price list#
curl https://api.withflintpay.com/v1/price-lists \
-H "Authorization: Bearer $FLINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Wholesale",
"currency": "USD",
"customer_segments": ["wholesale"],
"external_reference_id": "wholesale-us"
}'
currency is immutable and must match the catalog currency. Currently only USD is supported. status defaults to active; send inactive to create a list that remains assignable but does not provide prices.
customer_segments is a set of up to 20 Customer.segment labels. Each label can belong to only one unarchived price list in the same merchant environment, including inactive lists. A conflicting assignment returns 409 ALREADY_EXISTS.
Add variant prices#
Use the nested prices endpoint to add between 1 and 500 prices in one request. Each list can hold up to 10,000 prices. Each variant has at most one price in a list. Bundles and gift cards are refused.
curl https://api.withflintpay.com/v1/price-lists/prl_01J00000000000000000000000/prices \
-H "Authorization: Bearer $FLINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"on_variant_conflict": "return_existing",
"prices": [{
"variant_id": "var_01J00000000000000000000000",
"unit_price_money": {"amount": 800, "currency": "USD"},
"quantity_price_breaks": [{
"minimum_quantity": 10,
"unit_price_money": {"amount": 700, "currency": "USD"}
}]
}]
}'
The response's data contains the updated price_list and an additions array in request order. Each addition contains price_list_price and an outcome:
| Outcome | Meaning |
|---|---|
created | A new price was added for the variant |
existing | The stored price was returned without a change |
updated | The existing price or its quantity schedule changed |
The response is 201 when any price was created, otherwise 200. The default on_variant_conflict: return_existing preserves existing variant prices. Use update to replace them with each input's base price and complete quantity schedule. In that mode, omitting quantity_price_breaks removes existing breaks.
A batch is atomic. A rejected input leaves the list unchanged. Do not repeat a variant within one batch. To reject a batch if the list changed since you read it, send its version as expected_price_list_version.
Exceeding the list's capacity returns 409 LIMIT_REACHED with reason price_list_prices, limit: 10000, and a reference to the price list. Remove prices from that list or add the remaining prices to another list.
Quantity schedules#
The base price must be positive. A schedule has at most 10 breaks. Each minimum_quantity is at least 2 and strictly increases; each unit price is positive, strictly decreases from the preceding price starting with the base, and uses the list's currency. An empty schedule uses the base price at every quantity.
The largest minimum not above one line's quantity selects the tier. Quantities from separate lines are not combined. See Quantity price breaks for the shared schedule rules.
Read and edit prices#
| Operation | Endpoint |
|---|---|
| List prices | GET /v1/price-lists/{price_list_id}/prices |
| Get one price | GET /v1/price-lists/{price_list_id}/prices/{price_list_price_id} |
| Update one price | PATCH /v1/price-lists/{price_list_id}/prices/{price_list_price_id} |
| Remove one price | DELETE /v1/price-lists/{price_list_id}/prices/{price_list_price_id} |
The price list supports variant_id and product_id filters on its nested prices list. Both lists use cursor pagination with page_size and page_token.
On a price PATCH, send unit_price_money, quantity_price_breaks, or both. Omit the schedule to keep it unchanged; send [] to clear it. The complete resulting schedule must remain valid. Supplying quantity_price_breaks, including [], requires expected_version equal to the child price's version.
Removing a price permanently deletes it and returns the parent price list with its updated price_count and version. On this DELETE, the optional expected_version query parameter fences the parent list returned in data.
Assign a list to a customer#
Set the merchant-only price_list_id on a customer, or assign the customer's segment label to the list through customer_segments. You can assign an inactive list; archived lists return 409 ACTION_NOT_ALLOWED. Customer-session responses hide both the list assignment and segment.
To remove a direct customer assignment, update that customer with price_list_id: null.
Update or archive a list#
PATCH /v1/price-lists/{price_list_id} accepts name, status, customer_segments, external_reference_id, and metadata. Omitted fields remain unchanged. customer_segments replaces the complete set; send [] to clear it, and include the list's expected_version whenever the field is supplied. Send external_reference_id: null to clear the reference or metadata: null to clear all metadata.
Use status: active or status: inactive for reversible availability changes. status: archived is refused on PATCH; use DELETE /v1/price-lists/{price_list_id} instead.
DELETE soft-deletes the list, releases its segment assignments, and returns the full list with status: archived and archived_at. The list remains readable by ID and cannot be edited or assigned. Repeating DELETE returns the same archived snapshot. A stale expected_version still returns 409 VERSION_CONFLICT, including on an already archived list.
A list directly referenced by any customer returns 409 RESOURCE_IN_USE instead of being archived. Clear or replace those customers' price_list_id assignments first.
List and synchronize#
GET /v1/price-lists supports status, customer_segment, external_reference_id, and query filters. Archived lists are excluded by default; name archived in the status filter to include them. Multi-value statuses accept repeated keys or a comma-separated value. GET by ID always includes archived lists.
Lists default to created_at descending, with their ID descending as the tiebreak. The price list supports sorting by created_at, updated_at, or name; the nested prices list supports created_at or updated_at. Both accept sort_direction, creation and update time bounds, and cursor pagination.
Each list starts at version: 1. A request that changes its own fields or any prices advances the aggregate version once. A changed child price also advances its own version. No-op writes preserve both versions.
Subscribe to price_list.created, price_list.updated, and price_list.archived. A request that changes child prices emits one price_list.updated event, including a bulk request. No-op writes and repeat archives emit no event. Event objects use the same PriceList schema as GET; fetch the nested prices list to synchronize the prices themselves.
Negotiated prices#
Fresh catalog lines resolve the customer’s active direct list first, then an active list for their segment, then the variant schedule. A list that does not price that variant falls through to the next source. Inactive lists provide no prices. Existing lines keep their frozen terms. See wholesale pricing.
The Price list object#
A merchant-only set of variant prices for individual customers or customer segments.
Returned by GET /v1/price-lists/{price_list_id} and carried by the endpoints below.
Attributes
archived_atstring or nullRequiredWhen this price list was soft-deleted, as an RFC3339 timestamp. Null when it has not been archived.
created_atstringRequiredWhen this price list was created, as an RFC3339 timestamp.
currencystringRequiredImmutable currency of every price in this list. Currently USD. Uses ISO 4217 currency codes.
customer_segmentsarray of stringRequiredCustomer.segment labels assigned to this list. Empty when no segments are assigned.
external_reference_idstring or nullRequiredCaller-owned identifier for this resource in an external system. `null` when unset.
merchant_idstringRequiredIdentifier of the merchant that owns this price list.
metadatamap of stringRequiredCaller-owned metadata stored on this price list.
namestringRequiredName used to identify this price list.
price_countintegerRequiredNumber of variant prices in the list.
price_list_idstringRequiredStable identifier of this price list.
statusenumRequiredAvailability or retirement state. Derived as archived when archived_at is set; otherwise active or inactive.
activeinactivearchived
updated_atstringRequiredWhen this price list or its prices last changed, as an RFC3339 timestamp.
versionintegerRequiredAggregate version, increased once for a request that changes the list or its prices. No-op writes preserve it.
{
"archived_at": null,
"created_at": "2026-11-07T12:00:00Z",
"currency": "USD",
"customer_segments": [
"wholesale"
],
"external_reference_id": null,
"merchant_id": "mer_01J00000000000000000000000",
"metadata": {},
"name": "Wholesale",
"price_count": 1,
"price_list_id": "prl_01J00000000000000000000000",
"status": "active",
"updated_at": "2026-11-07T12:00:00Z",
"version": 1
}List price lists#
/v1/price-listsRequires scope commerce.catalog.read or commerce.catalog.write
Rate limit: read
Lists price lists. Archived lists are excluded unless the status filter explicitly names archived. Results default to created_at descending, with price_list_id descending as the tiebreak. Default order: created_at descending, then price_list_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
statusarray of enumFilter by status. Omitted, the list leaves out archived rows; name archived to include them. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
activeinactivearchived
customer_segmentstringExact match on a Customer.segment label assigned to this price list.
external_reference_idstringExact match on the caller-owned external reference ID.
querystringSearch across price list ID, name, and external reference ID. Text fields match any part of the value, and %, _ and \ are ordinary characters, not wildcards. IDs match from the start and need the type prefix, such as prl_01.
sort_byenumField to sort by. Defaults to created_at; ties are broken by price_list_id.
created_atupdated_atname
sort_directionenumSort direction. Defaults to desc.
ascdesc
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
updated_afterstringInclusive lower bound on updated_at.
updated_beforestringExclusive upper bound on updated_at.
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
archived_atstring or nullRequiredWhen this price list was soft-deleted, as an RFC3339 timestamp. Null when it has not been archived.
created_atstringRequiredWhen this price list was created, as an RFC3339 timestamp.
currencystringRequiredImmutable currency of every price in this list. Currently USD. Uses ISO 4217 currency codes.
customer_segmentsarray of stringRequiredCustomer.segment labels assigned to this list. Empty when no segments are assigned.
external_reference_idstring or nullRequiredCaller-owned identifier for this resource in an external system. `null` when unset.
merchant_idstringRequiredIdentifier of the merchant that owns this price list.
metadatamap of stringRequiredCaller-owned metadata stored on this price list.
namestringRequiredName used to identify this price list.
price_countintegerRequiredNumber of variant prices in the list.
price_list_idstringRequiredStable identifier of this price list.
statusenumRequiredAvailability or retirement state. Derived as archived when archived_at is set; otherwise active or inactive.
activeinactivearchived
updated_atstringRequiredWhen this price list or its prices last changed, as an RFC3339 timestamp.
versionintegerRequiredAggregate version, increased once for a request that changes the list or its prices. No-op writes preserve it.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/price-lists \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"archived_at": null,
"created_at": "2026-11-07T12:00:00Z",
"currency": "USD",
"customer_segments": [
"wholesale"
],
"external_reference_id": null,
"merchant_id": "mer_01J00000000000000000000000",
"metadata": {},
"name": "Wholesale",
"price_count": 1,
"price_list_id": "prl_01J00000000000000000000000",
"status": "active",
"updated_at": "2026-11-07T12:00:00Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "example",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Create price list#
/v1/price-listsIdempotentRequires scope commerce.catalog.write
Rate limit: write
Creates a merchant-only price list. Currency is immutable. A customer segment can belong to only one unarchived list, including inactive lists.
Request body
currencystringRequiredCurrency of all list prices, as an uppercase ISO 4217 code. Must match the catalog currency; currently only USD is supported. Cannot be changed after creation.
customer_segmentsarray of stringCustomer.segment labels to assign, at most 20. Each label can belong to only one unarchived list, including inactive lists. Omit or send [] for no segment assignments.
external_reference_idstringCaller-owned identifier for this resource in an external system.
metadatamap of stringCaller-owned metadata to store on this price list.
namestringRequiredName used to identify the price list. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
statusenumInitial availability. Inactive lists remain assignable but do not provide prices.
activeinactive
Response · 201
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
archived_atstring or nullRequiredWhen this price list was soft-deleted, as an RFC3339 timestamp. Null when it has not been archived.
created_atstringRequiredWhen this price list was created, as an RFC3339 timestamp.
currencystringRequiredImmutable currency of every price in this list. Currently USD. Uses ISO 4217 currency codes.
customer_segmentsarray of stringRequiredCustomer.segment labels assigned to this list. Empty when no segments are assigned.
external_reference_idstring or nullRequiredCaller-owned identifier for this resource in an external system. `null` when unset.
merchant_idstringRequiredIdentifier of the merchant that owns this price list.
metadatamap of stringRequiredCaller-owned metadata stored on this price list.
namestringRequiredName used to identify this price list.
price_countintegerRequiredNumber of variant prices in the list.
price_list_idstringRequiredStable identifier of this price list.
statusenumRequiredAvailability or retirement state. Derived as archived when archived_at is set; otherwise active or inactive.
activeinactivearchived
updated_atstringRequiredWhen this price list or its prices last changed, as an RFC3339 timestamp.
versionintegerRequiredAggregate version, increased once for a request that changes the list or its prices. No-op writes preserve it.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/price-lists \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"currency": "USD",
"customer_segments": [
"wholesale"
],
"name": "Wholesale"
}'Get price list#
/v1/price-lists/{price_list_id}Requires scope commerce.catalog.read or commerce.catalog.write
Rate limit: read
Returns a price list by ID, including archived lists. Price lists and their segment assignments are merchant-only.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
curl https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": {
"archived_at": null,
"created_at": "2026-11-07T12:00:00Z",
"currency": "USD",
"customer_segments": [
"wholesale"
],
"external_reference_id": null,
"merchant_id": "mer_01J00000000000000000000000",
"metadata": {},
"name": "Wholesale",
"price_count": 1,
"price_list_id": "prl_01J00000000000000000000000",
"status": "active",
"updated_at": "2026-11-07T12:00:00Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update price list#
/v1/price-lists/{price_list_id}IdempotentRequires scope commerce.catalog.write
Rate limit: write
Updates only the fields supplied. Send customer_segments: [] to clear segment assignments. Inactive lists remain assignable but do not provide prices. Send expected_version to reject a stale write. Archived lists cannot be changed.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
customer_segmentsarray of stringComplete set of Customer.segment labels to assign, at most 20. Each label can belong to only one unarchived list, including inactive lists. On PATCH, omission preserves the set and [] clears it. Include expected_version whenever customer_segments is supplied.
expected_versionintegerAggregate version last read. Required when customer_segments is present. A mismatch returns VERSION_CONFLICT without changing the list.
external_reference_idstring or nullCaller-owned identifier for this resource in an external system. Omit to keep it unchanged; send null to clear it.
metadatamap of string or nullMetadata patch. Omit to keep metadata unchanged; send null to clear all metadata.
namestringName used to identify the price list. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
statusenumSet active or inactive. To archive a price list, use DELETE /v1/price-lists/{price_list_id}.
activeinactive
curl -X PATCH https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1,
"name": "Wholesale partners"
}'Archive price list#
/v1/price-lists/{price_list_id}IdempotentRequires scope commerce.catalog.write
Rate limit: write
Soft-deletes a price list, releasing its segment assignments, and returns its full snapshot with status archived. A list referenced by customers returns RESOURCE_IN_USE. Repeating DELETE returns the same archived snapshot; a stale expected_version still returns VERSION_CONFLICT.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
expected_versionintegerVersion last read by the caller.
curl -X DELETE https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"List price list prices#
/v1/price-lists/{price_list_id}/pricesRequires scope commerce.catalog.read or commerce.catalog.write
Rate limit: read
Lists the variant prices in a price list. Filter by variant_id or product_id. Results default to created_at descending, with price_list_price_id descending as the tiebreak. Default order: created_at descending, then price_list_price_id descending.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
variant_idstringExact match on the priced variant ID.
product_idstringExact match on the product owning the priced variant.
sort_byenumField to sort by. Defaults to created_at; ties are broken by price_list_price_id.
created_atupdated_at
sort_directionenumSort direction. Defaults to desc.
ascdesc
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
updated_afterstringInclusive lower bound on updated_at.
updated_beforestringExclusive upper bound on updated_at.
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen this price was added, as an RFC3339 timestamp.
price_list_idstringRequiredIdentifier of the price list that owns this price.
price_list_price_idstringRequiredStable identifier of this price within its list.
product_idstringRequiredIdentifier of the product that owns this variant.
quantity_price_breaksarray of objectRequiredUp to 10 quantity breaks, ordered by increasing minimum_quantity and strictly decreasing unit price. [] means the base price applies at every quantity.
unit_price_moneyobjectRequiredPositive base net unit price in the price list's currency, in the currency's smallest unit.
updated_atstringRequiredWhen this price last changed, as an RFC3339 timestamp.
variant_idstringRequiredIdentifier of the priced product variant. Bundles and gift cards are not supported.
versionintegerRequiredVersion of this variant price and its quantity schedule. No-op writes preserve it.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q/prices \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"created_at": "2026-11-07T12:00:00Z",
"price_list_id": "prl_01J00000000000000000000000",
"price_list_price_id": "prlp_01J00000000000000000000000",
"product_id": "prod_01J00000000000000000000000",
"quantity_price_breaks": [
{
"minimum_quantity": 10,
"unit_price_money": {
"amount": 700,
"currency": "USD"
}
}
],
"unit_price_money": {
"amount": 800,
"currency": "USD"
},
"updated_at": "2026-11-07T12:00:00Z",
"variant_id": "var_01J00000000000000000000000",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "example",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Add price list prices#
/v1/price-lists/{price_list_id}/pricesIdempotentRequires scope commerce.catalog.write
Rate limit: write
Atomically adds 1 to 500 variant prices. on_variant_conflict defaults to return_existing; update replaces an existing price and its full schedule. Each addition reports created, existing, or updated. Returns 201 if any price was created, otherwise 200. One changed batch advances the list version once. A list holds up to 10,000 prices.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
expected_price_list_versionintegerPrice list aggregate version last read. A mismatch rejects the entire batch.
on_variant_conflictenumBehavior when the list already prices a variant.
return_existingupdate
pricesarray of objectRequiredBetween 1 and 500 variant prices. A price list holds at most 10,000 prices.
quantity_price_breaksarray of objectComplete quantity schedule, up to 10 breaks. Omit or send [] for no quantity breaks. Each price must be lower than the preceding one.
unit_price_moneyobjectRequiredPositive base net unit price, in the price list's currency.
variant_idstringRequiredProduct variant to price. Bundles and gift cards are refused.
Response · 201
At least one requested variant price was created.
dataobjectRequiredResource, collection, or operation result returned by this request.
additionsarray of objectRequiredOne result for each requested variant price, in request order.
price_listobjectRequiredThe price list after the batch, including its new count and aggregate version.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
Response · 200
Every requested variant matched an existing price in the list, reported as existing or updated; nothing was created.
Same attributes as 201.
curl -X POST https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q/prices \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"prices": [
{
"quantity_price_breaks": [
{
"minimum_quantity": 10,
"unit_price_money": {
"amount": 700,
"currency": "USD"
}
}
],
"unit_price_money": {
"amount": 800,
"currency": "USD"
},
"variant_id": "var_01J00000000000000000000000"
}
]
}'Get price list price#
/v1/price-lists/{price_list_id}/prices/{price_list_price_id}Requires scope commerce.catalog.read or commerce.catalog.write
Rate limit: read
Returns a variant price and its complete quantity schedule within this price list.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
price_list_price_idstringRequiredFlint price list price id. Must be a valid ID with prefix prlp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 200
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen this price was added, as an RFC3339 timestamp.
price_list_idstringRequiredIdentifier of the price list that owns this price.
price_list_price_idstringRequiredStable identifier of this price within its list.
product_idstringRequiredIdentifier of the product that owns this variant.
quantity_price_breaksarray of objectRequiredUp to 10 quantity breaks, ordered by increasing minimum_quantity and strictly decreasing unit price. [] means the base price applies at every quantity.
unit_price_moneyobjectRequiredPositive base net unit price in the price list's currency, in the currency's smallest unit.
updated_atstringRequiredWhen this price last changed, as an RFC3339 timestamp.
variant_idstringRequiredIdentifier of the priced product variant. Bundles and gift cards are not supported.
versionintegerRequiredVersion of this variant price and its quantity schedule. No-op writes preserve it.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q/prices/prlp_01KEZF7C007DQ721A29CDR73DN \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": {
"created_at": "2026-11-07T12:00:00Z",
"price_list_id": "prl_01J00000000000000000000000",
"price_list_price_id": "prlp_01J00000000000000000000000",
"product_id": "prod_01J00000000000000000000000",
"quantity_price_breaks": [
{
"minimum_quantity": 10,
"unit_price_money": {
"amount": 700,
"currency": "USD"
}
}
],
"unit_price_money": {
"amount": 800,
"currency": "USD"
},
"updated_at": "2026-11-07T12:00:00Z",
"variant_id": "var_01J00000000000000000000000",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update price list price#
/v1/price-lists/{price_list_id}/prices/{price_list_price_id}IdempotentRequires scope commerce.catalog.write
Rate limit: write
Updates a variant price or its quantity schedule. Omit quantity_price_breaks to preserve it; send [] to clear it. The resulting complete schedule must remain valid. expected_version fences this child price; an actual change also advances the parent list version once.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
price_list_price_idstringRequiredFlint price list price id. Must be a valid ID with prefix prlp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
expected_versionintegerVersion of this child price last read. Required when quantity_price_breaks is present. A mismatch returns VERSION_CONFLICT.
quantity_price_breaksarray of objectReplace the complete quantity schedule. Omit to preserve it; send [] to clear it. The resulting complete schedule must remain valid. Include expected_version whenever quantity_price_breaks is supplied.
minimum_quantityintegerRequiredMinimum whole-number quantity on one line for this price to apply; fractional quantities are not supported. Must strictly increase between entries.
unit_price_moneyobjectRequiredNet unit price in the base unit price's currency. Must be greater than zero and below the preceding price, starting with the base unit price.
unit_price_moneyobjectNew positive base net unit price in the list's currency. The resulting complete schedule must remain valid.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
curl -X PATCH https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q/prices/prlp_01KEZF7C007DQ721A29CDR73DN \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1,
"unit_price_money": {
"amount": 750,
"currency": "USD"
}
}'Remove price list price#
/v1/price-lists/{price_list_id}/prices/{price_list_price_id}IdempotentRequires scope commerce.catalog.write
Rate limit: write
Permanently removes this variant price from its list and returns the parent price list with its new count and version. expected_version fences the parent price list. Repeating without the original Idempotency-Key returns RESOURCE_NOT_FOUND.
Path parameters
price_list_idstringRequiredFlint price list id. Must be a valid ID with prefix prl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
price_list_price_idstringRequiredFlint price list price id. Must be a valid ID with prefix prlp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
expected_versionintegerVersion last read by the caller.
curl -X DELETE https://api.withflintpay.com/v1/price-lists/prl_01KEZF7C00EH39P59GN3XMGS2Q/prices/prlp_01KEZF7C007DQ721A29CDR73DN \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Was this helpful?