Settings

Settings control how your Flint integration behaves across checkout, tipping, tax, receipts, inventory, branding, legal, subscriptions, coupons, promotions, customer accounts, and customer email delivery. The public surface is merchant-scoped for raw reads and writes, while effective settings resolve the full inheritance chain (organization, merchant, location, and device) into the values a given surface actually uses. Pass location_id or device_id to see what applies at that scope; device_id takes precedence and resolves its location automatically.

Settings policies add governance on top: a rule like inherit_only, subset_only, min_bound, or max_bound attached to a scope restricts what descendant scopes can set, never the scope it is attached to. payment_limits is operator-managed and read-only on the public API. What Flint charges to process a payment is not a setting; see the Processing fees guide for how that fee is charged and reported.

Settings like checkout.enabled_payment_options, checkout.default_expires_in_seconds, and checkout.promotion_code_entry_enabled directly shape hosted surfaces; see the Checkout sessions guide and Payment links guide.

Checkout Settings#

Use the top-level checkout object for hosted checkout defaults. Checkout sessions and payment links can override some of these values on the object itself.

Field	Type	Description
`enabled_payment_options`	string array	Payment options offered by default on hosted checkout, such as `card`, `apple_pay`, and `google_pay`.
`require_email`	boolean	Requires buyer email by default.
`require_phone`	boolean	Requires buyer phone by default.
`require_billing_address`	boolean	Requires billing address by default.
`default_expires_in_seconds`	integer	Default generic checkout session lifetime, between `60` and `86400`. Invoice-owned checkout uses the fixed active invoice-link deadline instead.
`promotion_code_entry_enabled`	boolean	Merchant default for hosted checkout promotion-code entry. Object-level `promotion_config.codes_enabled` can override it for a checkout session or payment link.

First-party Connect settings clients use checkout.isPromotionCodeEntryEnabled for the same hosted-checkout default.

Inventory Settings#

Use the top-level inventory object to decide what happens when stock cannot be honored. It does not hold quantities; those live on inventory levels.

Field	Type	Description
`low_stock_threshold`	integer	The available quantity your team treats as low stock. Flint stores it and surfaces it in the dashboard; it does not change allocation, and the API does not filter or alert on it for you.
`origin_policies`	object	Failure handling keyed by order source.

origin_policies is keyed by where the order came from: checkout, payment_link, api, subscription, virtual_terminal, or default. Flint uses the entry matching the order's source and falls back to default. Each entry holds:

Field	Values	Description
`post_payment_inventory_failure_action`	`exception_state`, `auto_refund`	What happens when payment succeeds but stock cannot be committed. `exception_state` leaves the order at `inventory_exception_status: "paid_inventory_failed"` for an operator to resolve; `auto_refund` refunds the payment without asking.
`subscription_inventory_block_action`	`inventory_blocked_open_invoice`, `past_due`	What happens when a subscription renewal cannot get stock. The first leaves the invoice open and uncollectible; the second moves the subscription to past due.

JSON

{
  "inventory": {
    "low_stock_threshold": 5,
    "origin_policies": {
      "default": { "post_payment_inventory_failure_action": "exception_state" },
      "checkout": { "post_payment_inventory_failure_action": "auto_refund" }
    }
  }
}

Promotion Settings#

Use the top-level promotions object to control promotion evaluation.

Field	Type	Description
`automatic_enabled`	boolean	Enables automatic promotion evaluation.
`codes_enabled`	boolean	Merchant promotion-code redemption policy. Explicit `false` rejects promotion-code application even if a checkout session or payment link asks to show code entry.
`max_promotions_per_order`	integer	Caps pricing-active promotion discounts per order, including coupon-backed promotions. Must be between `1` and `10`.

Coupon Settings#

Use coupons only for legacy coupon behavior. New promotion-code integrations should use promotions.codes_enabled for redemption policy and checkout.promotion_code_entry_enabled or promotion_config.codes_enabled for hosted checkout entry.

Field	Type	Description
`enabled`	boolean	Legacy coupon policy and clamp. This does not enable promotion-code entry by default.
`max_coupons_per_order`	integer	Caps coupon-backed discounts per order. Must be between `1` and `10`.

Branding Settings#

Use the top-level branding object to style the surfaces Flint renders for your buyers: hosted checkout, the customer account, and transactional email.

Field	Type	Description
`primary_color`	string	Six-digit hex, such as `#1B4D3E`. Used for primary actions.
`accent_color`	string	Six-digit hex.
`background_color`	string	Six-digit hex. Page background.
`text_color`	string	Six-digit hex. Body text.
`font_family`	string	One of `instrument_sans`, `system_sans`, `system_serif`, `monospace`.
`corner_radius`	integer	Border radius in pixels, between `0` and `32`.

Customer Account Settings#

Use the top-level customer_account object to choose where buyers manage their orders, subscriptions, and Returns, and what that surface looks like. Flint sends every account link in transactional email to whatever this object currently says, resolved when the buyer clicks. See the customer accounts guide.

customer_account and customer_email_delivery are merchant-scoped. Sending either at an organization, location, or device scope returns CUSTOMER_SETTINGS_REQUIRE_MERCHANT_SCOPE.

Field	Type	Description
`mode`	`flint_hosted`, `merchant_hosted`	Who serves the account. Defaults to `flint_hosted`.
`merchant_account_url`	string	Required when `mode` is `merchant_hosted`. HTTPS URL on a verified payment method domain or a subdomain of one.
`route_templates`	object	Optional per-resource paths for `merchant_hosted`. Keys are `order`, `subscription`, and `return`; each value uses `{resource_id}` once.
`presentation`	object	Branding of Flint's hosted account. Only valid when `mode` is `flint_hosted`.

presentation holds:

Field	Type	Description
`account_name`	string	Name shown in the account. Defaults to your business name.
`custom_domain`	string	Exact ASCII/Punycode subdomain to serve the account from, such as `account.example.com`. Apex and wildcard hostnames are not supported. Register the hostname as an active payment method domain first. Flint verifies DNS control before activating it.
`is_flint_branding_hidden`	boolean	Removes the Flint mark and the "Powered by Flint" credit.

The two modes are mutually exclusive about which fields they accept. Sending presentation with merchant_hosted, or merchant_account_url or route_templates with flint_hosted, returns CUSTOMER_ACCOUNT_MODE_CONFLICT.

JSON

{
  "customer_account": {
    "mode": "flint_hosted",
    "presentation": {
      "account_name": "Cedar & Stone",
      "custom_domain": "account.cedarandstone.com",
      "is_flint_branding_hidden": true
    }
  }
}

`customer_account_domain_status`#

Read-only. Present once a custom_domain is set, and the only place the DNS records come from.

Field	Type	Description
`hostname`	string	The hostname being provisioned.
`domain_status`	`provisioning`, `active`, `attention_required`	`attention_required` means the hostname needs a DNS or certificate correction.
`dns_records`	array	Records to publish. Exact subdomains currently return one `cname` record with `name` and `value`.
`last_checked_at`	string	RFC3339 instant of the last health check.

While the hostname is anything other than active, account links keep working on Flint's own domain. Buyers are never sent to a hostname that does not resolve.

Customer Email Delivery Settings#

Use the top-level customer_email_delivery object to decide, per family of buyer email, whether Flint sends it or you do. Each field takes flint_sends (the default) or merchant_sends.

Field	Covers
`order_receipts`	Purchase receipts
`fulfillment_updates`	Shipment and delivery notices
`subscription_lifecycle`	Renewals, pauses, cancellations, trial endings
`dunning`	Failed payment and past-due notices
`returns`	Return approvals, labels, and resolutions
`invoices`	Invoice delivery and reminders

Setting a family to merchant_sends stops Flint's email for that family only. The webhook events behind it keep firing, which is how you send your own.

Endpoints

GET/v1/settings
PATCH/v1/settings
GET/v1/settings/effective
GET/v1/settings/policies
PUT/v1/settings/policies

Get merchant settings #

GET/v1/settingsRequires scope: settings.read or settings.write

Returns the raw merchant-scoped settings record for the authenticated merchant. No inheritance is applied.

Response · 200

dataobjectrequired

metaobject

request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYRATE_LIMIT_EXCEEDED

Bash

curl https://api.withflintpay.com/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "settings_id": "set_123",
    "settings_scope": "merchant",
    "tipping": {
      "default_enabled": true,
      "tip_percentages": [
        15,
        18,
        20
      ],
      "default_tip_percentage": 18,
      "is_custom_tip_enabled": true
    },
    "tax": {
      "default_enabled": true
    },
    "checkout": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "require_email": true,
      "default_expires_in_seconds": 3600,
      "promotion_code_entry_enabled": true
    },
    "receipts": {
      "header_text": "Thanks for your purchase",
      "is_auto_email_enabled": true
    },
    "inventory": {
      "low_stock_threshold": 5,
      "origin_policies": {
        "default": {
          "post_payment_inventory_failure_action": "exception_state"
        },
        "subscription": {
          "subscription_inventory_block_action": "inventory_blocked_open_invoice"
        }
      }
    },
    "branding": {
      "primary_color": "#0f766e",
      "accent_color": "#f59e0b"
    },
    "legal": {
      "terms_of_service_url": "https://example.com/terms",
      "require_terms_of_service": true
    },
    "subscriptions": {
      "dunning_end_action": "cancel",
      "dunning_retry_days": 16
    },
    "coupons": {
      "enabled": true,
      "max_coupons_per_order": 2
    },
    "promotions": {
      "automatic_enabled": true,
      "codes_enabled": true
    },
    "payment_limits": {
      "max_amounts": {
        "default": {
          "amount": 100000,
          "currency": "USD"
        },
        "payment_link": {
          "amount": 250000,
          "currency": "USD"
        }
      },
      "min_amounts": {
        "default": {
          "amount": 50,
          "currency": "USD"
        },
        "payment_link.donation": {
          "amount": 100,
          "currency": "USD"
        }
      }
    },
    "metadata": {
      "channel": "retail"
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update merchant settings #

PATCH/v1/settingsIdempotentRequires scope: settings.write

Applies a sparse patch to merchant-scoped settings. Fee and payment limit controls remain internal-only.

Request body

brandingobject

checkoutobject

couponsobject

customer_accountobject

customer_email_deliveryobject

fulfillmentobject

inventoryobject

legalobject

metadatamap of string

promotionsobject

receiptsobject

subscriptionsobject

taxobject

tippingobject

Response · 200

dataobjectrequired

metaobject

request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED

Bash

curl -X PATCH https://api.withflintpay.com/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "checkout": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "require_email": true,
      "promotion_code_entry_enabled": true
    },
    "receipts": {
      "footer_text": "Come back soon"
    },
    "coupons": {
      "max_coupons_per_order": 3
    },
    "promotions": {
      "codes_enabled": true
    },
    "metadata": {
      "channel": "omnichannel"
    }
  }'

JSON

{
  "data": {
    "settings_id": "set_123",
    "settings_scope": "merchant",
    "tipping": {
      "default_enabled": true,
      "tip_percentages": [
        15,
        18,
        20
      ],
      "default_tip_percentage": 18,
      "is_custom_tip_enabled": true
    },
    "tax": {
      "default_enabled": true
    },
    "checkout": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "require_email": true,
      "default_expires_in_seconds": 3600,
      "promotion_code_entry_enabled": true
    },
    "receipts": {
      "header_text": "Thanks for your purchase",
      "is_auto_email_enabled": true
    },
    "inventory": {
      "low_stock_threshold": 5,
      "origin_policies": {
        "default": {
          "post_payment_inventory_failure_action": "exception_state"
        },
        "subscription": {
          "subscription_inventory_block_action": "inventory_blocked_open_invoice"
        }
      }
    },
    "branding": {
      "primary_color": "#0f766e",
      "accent_color": "#f59e0b"
    },
    "legal": {
      "terms_of_service_url": "https://example.com/terms",
      "require_terms_of_service": true
    },
    "subscriptions": {
      "dunning_end_action": "cancel",
      "dunning_retry_days": 16
    },
    "coupons": {
      "enabled": true,
      "max_coupons_per_order": 2
    },
    "promotions": {
      "automatic_enabled": true,
      "codes_enabled": true
    },
    "payment_limits": {
      "max_amounts": {
        "default": {
          "amount": 100000,
          "currency": "USD"
        },
        "payment_link": {
          "amount": 250000,
          "currency": "USD"
        }
      },
      "min_amounts": {
        "default": {
          "amount": 50,
          "currency": "USD"
        },
        "payment_link.donation": {
          "amount": 100,
          "currency": "USD"
        }
      }
    },
    "metadata": {
      "channel": "retail"
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get effective settings #

GET/v1/settings/effectiveRequires scope: settings.read or settings.write

Returns the fully resolved effective settings for the authenticated merchant. Optional device_id or location_id can be used to resolve inherited overrides.

Query parameters

location_idstring

Optional Flint location ID to resolve effective settings for.

device_idstring

Optional Flint device ID to resolve effective settings for. When set, the device location takes precedence.

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/settings/effective \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "settings_id": "set_123",
    "settings_scope": "device",
    "tipping": {
      "default_enabled": true,
      "tip_percentages": [
        15,
        18,
        20
      ],
      "default_tip_percentage": 18,
      "is_custom_tip_enabled": true
    },
    "tax": {
      "default_enabled": true
    },
    "checkout": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "require_email": true,
      "default_expires_in_seconds": 3600,
      "promotion_code_entry_enabled": true
    },
    "receipts": {
      "header_text": "Thanks for your purchase",
      "is_auto_email_enabled": true
    },
    "inventory": {
      "low_stock_threshold": 5,
      "origin_policies": {
        "default": {
          "post_payment_inventory_failure_action": "exception_state"
        },
        "subscription": {
          "subscription_inventory_block_action": "inventory_blocked_open_invoice"
        }
      }
    },
    "branding": {
      "primary_color": "#0f766e",
      "accent_color": "#f59e0b"
    },
    "legal": {
      "terms_of_service_url": "https://example.com/terms",
      "require_terms_of_service": true
    },
    "subscriptions": {
      "dunning_end_action": "cancel",
      "dunning_retry_days": 16
    },
    "coupons": {
      "enabled": true,
      "max_coupons_per_order": 2
    },
    "promotions": {
      "automatic_enabled": true,
      "codes_enabled": true
    },
    "payment_limits": {
      "max_amounts": {
        "default": {
          "amount": 100000,
          "currency": "USD"
        },
        "payment_link": {
          "amount": 250000,
          "currency": "USD"
        }
      },
      "min_amounts": {
        "default": {
          "amount": 50,
          "currency": "USD"
        },
        "payment_link.donation": {
          "amount": 100,
          "currency": "USD"
        }
      }
    },
    "metadata": {
      "channel": "retail"
    },
    "merchant_id": "mer_123",
    "location_id": "loc_123",
    "device_id": "dev_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List settings policies #

GET/v1/settings/policiesRequires scope: settings.read or settings.write

Returns the configured descendant settings policy rules for the requested scope. Policies apply only to lower scopes, not to updates made at the same scope. Organization scope is authorized against the requested organization_id rather than being derived from the authenticated merchant tree.

Query parameters

settings_scopeenum

Optional settings policy scope.

merchantorganizationlocation

organization_idstring

Optional organization scope identifier.

location_idstring

Optional location scope identifier.

device_idstring

Rejected for settings policies; device scope is unsupported.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

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/settings/policies \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": [
    {
      "settings_policy_id": "spol_01JQEXAMPLEDEFAULT123456789",
      "settings_scope": "merchant",
      "merchant_id": "mer_123",
      "field_path": "checkout.default_expires_in_seconds",
      "policy_type": "max_bound",
      "value": 1800,
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace settings policies #

PUT/v1/settings/policiesIdempotentRequires scope: settings.write

Replaces the complete set of descendant settings policy rules for the requested scope. Policies apply only to lower scopes, not to updates made at the same scope. Organization scope is authorized against the requested organization_id rather than being derived from the authenticated merchant tree.

Request body

device_idstring

location_idstring

organization_idstring

settings_policiesarray of objectrequired

settings_scopeenum

organizationmerchantlocationdevice

Response · 200

dataarray of objectrequired

metaobject

next_page_tokenstring

request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED

Bash

curl -X PUT https://api.withflintpay.com/v1/settings/policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "settings_policies": [
      {
        "field_path": "checkout.default_expires_in_seconds",
        "policy_type": "max_bound",
        "value": 1800
      }
    ]
  }'

JSON

{
  "data": [
    {
      "settings_policy_id": "spol_01JQEXAMPLEDEFAULT123456789",
      "settings_scope": "merchant",
      "merchant_id": "mer_123",
      "field_path": "checkout.default_expires_in_seconds",
      "policy_type": "max_bound",
      "value": 1800,
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Rate this doc

Settings

Checkout Settings#

Inventory Settings#

Promotion Settings#

Coupon Settings#

Branding Settings#

Customer Account Settings#

customer_account_domain_status#

Customer Email Delivery Settings#

Get merchant settings#

Error codes

Update merchant settings#

Error codes

Get effective settings#

Error codes

List settings policies#

Error codes

Replace settings policies#

Error codes

`customer_account_domain_status`#

Get merchant settings #

Update merchant settings #

Get effective settings #

List settings policies #

Replace settings policies #