FlintflintDocs

Products

Products are the core of Flint's catalog: physical goods, services, fees, and digital items. The product is the parent record; its variants are the sellable units that carry price, SKU, and inventory. A simple product has a single default variant, while an optioned product defines options (like size or color) whose combinations map to distinct variants.

When an order line item references a variant_id, Flint resolves price, display name, SKU, image, and tax settings from the catalog and tracks inventory automatically; callers cannot override catalog-owned fields on those rows. Products carry a status of active or inactive (reversible), or deleted (permanent). Inventory changes go through dedicated inventory-adjustment endpoints with an audited reason, not through product updates.

Related catalog resources: modifiers for per-line-item choices, bundles for selling variants together, and catalog for SKU lookup across the whole catalog.

Endpoints

List products#

GET/v1/products

Returns a paginated list of products for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

product_typeenum

Filter by product type.

physicalservicefeedigital
statusenum

Filter by product status.

activeinactivedeleted
only_in_stockboolean

Only return products with at least one available active variant.

categorystring

Filter by category.

querystring

Search across product_id, name, description, and SKU.

sort_byenum

Sort field.

namecreated_atupdated_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "product_id": "prod_123",
      "name": "General Admission",
      "product_type": "physical",
      "status": "active",
      "metadata": {
        "event_id": "evt_123"
      },
      "categories": [
        "tickets",
        "events"
      ],
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "default_variant_id": "var_123",
      "variant_count": 1,
      "active_variant_count": 1,
      "option_count": 0,
      "price_range": {
        "min_unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "max_unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      },
      "available_for_sale": true,
      "total_quantity_available": 42
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create product#

POST/v1/productsIdempotent

Creates a product for the authenticated merchant.

Request body
option 1object
option 2object
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "General Admission",
    "product_type": "physical",
    "metadata": {
      "event_id": "evt_123"
    },
    "categories": [
      "tickets",
      "events"
    ],
    "default_variant": {
      "sku": "ga-001",
      "unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      }
    }
  }'
JSON
{
  "data": {
    "product_id": "prod_123",
    "name": "General Admission",
    "product_type": "physical",
    "status": "active",
    "metadata": {
      "event_id": "evt_123"
    },
    "categories": [
      "tickets",
      "events"
    ],
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "default_variant_id": "var_123",
    "variant_count": 1,
    "active_variant_count": 1,
    "option_count": 0,
    "price_range": {
      "min_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "max_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      }
    },
    "available_for_sale": true,
    "total_quantity_available": 42
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get product#

GET/v1/products/{product_id}

Returns a single product by ID.

Path parameters
product_idstringrequired

Flint product ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/products/prod_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "product_id": "prod_123",
    "name": "General Admission",
    "product_type": "physical",
    "status": "active",
    "metadata": {
      "event_id": "evt_123"
    },
    "categories": [
      "tickets",
      "events"
    ],
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "default_variant_id": "var_123",
    "variant_count": 1,
    "active_variant_count": 1,
    "option_count": 0,
    "price_range": {
      "min_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "max_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      }
    },
    "available_for_sale": true,
    "total_quantity_available": 42
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update product#

PATCH/v1/products/{product_id}Idempotent

Applies a sparse update to product-parent fields. When categories is present, it replaces the full category list; send an empty array to clear categories. Sellable price, SKU, and inventory live on variants.

Path parameters
product_idstringrequired

Flint product ID.

Request body
categoriesarray of string
default_variant_idstring
descriptionstring
image_urlstring
metadatamap of string
namestring
product_typeenum
physicalservicefeedigital
statusenum
activeinactive
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/products/prod_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "VIP Admission",
    "image_url": "https://cdn.withflintpay.com/products/vip.png",
    "status": "inactive",
    "categories": [
      "vip",
      "events"
    ]
  }'
JSON
{
  "data": {
    "product_id": "prod_123",
    "name": "General Admission",
    "product_type": "physical",
    "status": "active",
    "metadata": {
      "event_id": "evt_123"
    },
    "categories": [
      "tickets",
      "events"
    ],
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "default_variant_id": "var_123",
    "variant_count": 1,
    "active_variant_count": 1,
    "option_count": 0,
    "price_range": {
      "min_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "max_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      }
    },
    "available_for_sale": true,
    "total_quantity_available": 42
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete product#

DELETE/v1/products/{product_id}Idempotent

Permanently deletes a product.

Path parameters
product_idstringrequired

Flint product ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X DELETE https://api.withflintpay.com/v1/products/prod_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "product_id": "prod_123",
    "name": "General Admission",
    "product_type": "physical",
    "status": "active",
    "metadata": {
      "event_id": "evt_123"
    },
    "categories": [
      "tickets",
      "events"
    ],
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "default_variant_id": "var_123",
    "variant_count": 1,
    "active_variant_count": 1,
    "option_count": 0,
    "price_range": {
      "min_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "max_unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      }
    },
    "available_for_sale": true,
    "total_quantity_available": 42
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace product categories#

PUT/v1/products/{product_id}/categoriesIdempotent

Replace product categories.

Path parameters
product_idstringrequired

Flint product ID.

Request body
categoriesarray of stringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PUT https://api.withflintpay.com/v1/products/prod_123/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 product options#

GET/v1/products/{product_id}/options

List product options.

Path parameters
product_idstringrequired

Flint product ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by option status.

activeinactivearchived
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/products/prod_123/options \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create product option#

POST/v1/products/{product_id}/optionsIdempotent

Create product option.

Path parameters
product_idstringrequired

Flint product ID.

Request body
metadatamap of string
namestringrequired
positioninteger
statusenum
activeinactive
valuesarray of object
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products/prod_123/options \
  -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 product option#

GET/v1/products/{product_id}/options/{option_id}

Get product option.

Path parameters
product_idstringrequired

Flint product ID.

option_idstringrequired

Flint product option ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/products/prod_123/options/{option_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update product option#

PATCH/v1/products/{product_id}/options/{option_id}Idempotent

Update product option.

Path parameters
product_idstringrequired

Flint product ID.

option_idstringrequired

Flint product option ID.

Request body
metadatamap of string
namestring
positioninteger
statusenum
activeinactive
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/products/prod_123/options/{option_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Archive product option#

POST/v1/products/{product_id}/options/{option_id}/archiveIdempotent

Archive product option.

Path parameters
product_idstringrequired

Flint product ID.

option_idstringrequired

Flint product option ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products/prod_123/options/{option_id}/archive \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Add product option values#

POST/v1/products/{product_id}/options/{option_id}/valuesIdempotent

Add product option values.

Path parameters
product_idstringrequired

Flint product ID.

option_idstringrequired

Flint product option ID.

Request body
valuesarray of objectrequired
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products/prod_123/options/{option_id}/values \
  -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 product option value#

PATCH/v1/products/{product_id}/options/{option_id}/values/{option_value_id}Idempotent

Update product option value.

Path parameters
product_idstringrequired

Flint product ID.

option_idstringrequired

Flint product option ID.

option_value_idstringrequired

Flint product option value ID.

Request body
metadatamap of string
positioninteger
statusenum
activeinactive
valuestring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/products/prod_123/options/{option_id}/values/{option_value_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Archive product option value#

POST/v1/products/{product_id}/options/{option_id}/values/{option_value_id}/archiveIdempotent

Archive product option value.

Path parameters
product_idstringrequired

Flint product ID.

option_idstringrequired

Flint product option ID.

option_value_idstringrequired

Flint product option value ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products/prod_123/options/{option_id}/values/{option_value_id}/archive \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List product variants#

GET/v1/products/{product_id}/variants

List product variants.

Path parameters
product_idstringrequired

Flint product ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by variant status.

activeinactivedeleted
sort_byenum

Sort field.

positioncreated_atupdated_atunit_price
sort_directionenum

Sort direction.

ascdesc
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/products/prod_123/variants \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create product variant#

POST/v1/products/{product_id}/variantsIdempotent

Create product variant.

Path parameters
product_idstringrequired

Flint product ID.

Request body
variantobjectrequired
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products/prod_123/variants \
  -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 product variant#

GET/v1/products/{product_id}/variants/{variant_id}

Get product variant.

Path parameters
product_idstringrequired

Flint product ID.

variant_idstringrequired

Flint product variant ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/products/prod_123/variants/{variant_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update product variant#

PATCH/v1/products/{product_id}/variants/{variant_id}Idempotent

Update product variant.

Path parameters
product_idstringrequired

Flint product ID.

variant_idstringrequired

Flint product variant ID.

Request body
barcodestring
enforce_inventory_limitboolean
enforce_inventory_limit_on_subscriptionsboolean
image_urlstring
metadatamap of string
namestring
positioninteger
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
Bash
curl -X PATCH https://api.withflintpay.com/v1/products/prod_123/variants/{variant_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 product variant#

DELETE/v1/products/{product_id}/variants/{variant_id}Idempotent

Delete product variant.

Path parameters
product_idstringrequired

Flint product ID.

variant_idstringrequired

Flint product variant ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X DELETE https://api.withflintpay.com/v1/products/prod_123/variants/{variant_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Adjust product variant inventory#

POST/v1/products/{product_id}/variants/{variant_id}/inventory-adjustmentsIdempotent

Adjust product variant inventory.

Path parameters
product_idstringrequired

Flint product ID.

variant_idstringrequired

Flint product variant ID.

Request body
change_reasonenum
manual_adjustmentorder_fulfillmentorder_cancellationorder_refundreceived_stockinventory_countdamagetheftloss
notestring
quantity_deltaintegerrequired

Whole-number quantity delta; fractional quantities are not supported.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/products/prod_123/variants/{variant_id}/inventory-adjustments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'
JSON
{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc