FlintflintDocs

Bundles

Bundles group product variants sold together as a single sellable unit: a meal combo, a starter kit, a multi-pack. A bundle has its own price, SKU, image, tax settings, and categories, independent of its components. Each component references a product variant with a quantity and display position.

Bundles are sellable the same way variants are: pass a bundle_id on an order line item and Flint resolves price and display from the catalog. available_for_sale reflects catalog eligibility, meaning every component is active and sellable; it is not a stock guarantee. To know whether a bundle can actually be fulfilled right now, run an inventory availability check against its components, which evaluates stock per Location. Bundles can also carry modifier set assignments for buyer customization.

Endpoints

List bundles#

GET/v1/bundlesRequires scope: commerce.bundles.read or commerce.bundles.write

List bundles.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

querystring

Search across bundle_id, name, description, and SKU.

statusenum

Filter by bundle status.

activeinactivedeleted
sort_byenum

Sort field.

created_atupdated_atname
sort_directionenum

Sort direction.

ascdesc
delivery_profile_idstring

Filter bundles with at least one component assigned to this delivery profile.

delivery_configuration_statusenum

Filter by aggregated delivery readiness across bundle components.

configuredaction_requirednot_applicable
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/bundles \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create bundle#

POST/v1/bundlesIdempotentRequires scope: commerce.bundles.write

Create bundle.

Request body
barcodestring
categoriesarray of string
componentsarray of object
descriptionstring
imagesarray of object
metadatamap of string
namestringrequired
skustring
statusenum
activeinactive
tax_categoryenum

Flint line-item tax category.

generalphysical_goodsdigital_goodssoftwaresaasservicesprofessional_servicesfoodprepared_foodclothingmedical_goodsadmission
taxableboolean
unit_price_moneyobjectrequired

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/bundles \
  -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 bundle#

GET/v1/bundles/{bundle_id}Requires scope: commerce.bundles.read or commerce.bundles.write

Get bundle.

Path parameters
bundle_idstringrequired

Flint bundle 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/bundles/{bundle_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update bundle#

PATCH/v1/bundles/{bundle_id}IdempotentRequires scope: commerce.bundles.write

Update bundle.

Path parameters
bundle_idstringrequired

Flint bundle ID.

Request body
barcodestring
categoriesarray of string
descriptionstring
metadatamap of string
namestring
skustring
statusenum
activeinactive
tax_categoryenum

Flint line-item tax category.

generalphysical_goodsdigital_goodssoftwaresaasservicesprofessional_servicesfoodprepared_foodclothingmedical_goodsadmission
taxableboolean
unit_price_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/bundles/{bundle_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 bundle#

DELETE/v1/bundles/{bundle_id}IdempotentRequires scope: commerce.bundles.write

Delete bundle.

Path parameters
bundle_idstringrequired

Flint bundle 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/bundles/{bundle_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace bundle categories#

PUT/v1/bundles/{bundle_id}/categoriesIdempotentRequires scope: commerce.bundles.write

Replace bundle categories.

Path parameters
bundle_idstringrequired

Flint bundle ID.

Request body
categoriesarray of stringrequired
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/bundles/{bundle_id}/categories \
  -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"
}

List bundle components#

GET/v1/bundles/{bundle_id}/componentsRequires scope: commerce.bundles.read or commerce.bundles.write

List bundle components.

Path parameters
bundle_idstringrequired

Flint bundle ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

delivery_profile_idstring

Filter by assigned delivery profile ID.

delivery_configuration_statusenum

Filter by fulfillment readiness.

configuredaction_requirednot_applicable
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

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

Add bundle components#

POST/v1/bundles/{bundle_id}/componentsIdempotentRequires scope: commerce.bundles.write

Add bundle components.

Path parameters
bundle_idstringrequired

Flint bundle ID.

Request body
componentsarray of objectrequired
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/bundles/{bundle_id}/components \
  -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 bundle component#

PATCH/v1/bundles/{bundle_id}/components/{bundle_component_id}IdempotentRequires scope: commerce.bundles.write

Update bundle component.

Path parameters
bundle_idstringrequired

Flint bundle ID.

bundle_component_idstringrequired

Stable bundle component ID.

Request body
delivery_profile_idstring
positioninteger
quantityinteger

Whole-number quantity; fractional quantities are not supported.

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/bundles/{bundle_id}/components/{bundle_component_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 bundle component#

DELETE/v1/bundles/{bundle_id}/components/{bundle_component_id}IdempotentRequires scope: commerce.bundles.write

Delete bundle component.

Path parameters
bundle_idstringrequired

Flint bundle ID.

bundle_component_idstringrequired

Stable bundle component 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/bundles/{bundle_id}/components/{bundle_component_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace bundle images#

PUT/v1/bundles/{bundle_id}/imagesIdempotentRequires scope: commerce.bundles.write

Atomically replaces the complete ordered image gallery. The first image is primary, and an empty array clears the gallery. Omitting expected_image_revision uses last-write-wins replacement.

Path parameters
bundle_idstringrequired

Flint bundle ID.

Request body
expected_image_revisioninteger

Optional optimistic concurrency check. Omit it for last-write-wins replacement.

imagesarray of objectrequired

The complete desired gallery in display order. The first image is primary. Send [] to clear the gallery.

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/bundles/{bundle_id}/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "images": [
      {
        "source_url": "https://merchant.example/products/front.png",
        "alt": "Front view",
        "external_reference_id": "front"
      },
      {
        "source_url": "https://merchant.example/products/back.png",
        "alt": "Back view",
        "external_reference_id": "back"
      }
    ],
    "expected_image_revision": 4
  }'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc