Settings

Settings control how your Flint integration behaves across checkout, tipping, tax, receipts, inventory, branding, legal, subscriptions, 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 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.

Tip preselections#

Use PATCH /v1/settings to update tipping. Omitted fields keep their current values. Percentage presets contain exactly three values from 1 through 100. A preselected percentage must match an effective percentage preset; a preselected fixed tip must match an effective fixed preset's amount and currency.

When changing presets, explicitly replace or clear a preselection that the new presets exclude:

{
  "tipping": {
    "tip_percent_options": [10, 15, 25],
    "default_tip_percent": null
  }
}

Send null for default_tip_percent or default_smart_tip_money to clear the merchant override. Raw settings return the cleared field as null. Effective settings can still inherit a preselection from the organization; read GET /v1/settings/effective to see the result. Preset arrays and tipping booleans do not accept null. default_tip_percent and every tip_percent_options value must be between 1 and 100 with at most four decimal places.

Catalog settings#

Use catalog.default_delivery_profile_id to choose the active delivery profile that new physical products inherit. Read it from GET /v1/settings and change it with PATCH /v1/settings:

{
  "catalog": {
    "default_delivery_profile_id": "dprof_...",
    "expected_version": 4
  }
}

Use the catalog version returned by GET /v1/settings as expected_version. Use 0 only when catalog settings do not exist yet. Send a catalog change in its own PATCH /v1/settings request. Do not combine it with other settings sections.

This changes the default for new catalog items. It does not replace an existing variant or bundle-component assignment. To fill only unconfigured physical items, call POST /v1/delivery-profiles/{delivery_profile_id}/assign-to-unconfigured with the profile's current version as expected_version. If this action is based on the current default, also send the catalog version as expected_catalog_default_version so a later default change cannot apply the old profile.

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.

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

Checkout reminder emails#

checkout.recovery_email sends one email to a buyer who enters an email address at hosted checkout and leaves without paying. It lists the cart and total and links back to checkout.

{
  "checkout": {
    "recovery_email": {
      "enabled": true,
      "delay_seconds": 3600
    }
  }
}

A reminder can count as commercial email, so each one carries an unsubscribe link and the merchant's business address. Turning reminders on therefore requires an address on the merchant with a street, city, postal code, and country; without one, PATCH /v1/settings returns 400 with CHECKOUT_RECOVERY_EMAIL_ADDRESS_REQUIRED. If the address is removed later, no reminders go out until it is back.

Which checkouts send one:

• A hosted checkout session for an order, including one a one-time payment link opens, after the buyer saves an email as buyer_contact.
• Never an embedded session, or a checkout for an invoice, a subscription plan, or a return.

When the reminder is due, Flint checks again and sends nothing if reminders were turned off, the buyer cleared their email, the checkout was paid, closed, or replaced, or the order was paid or closed or has nothing left to pay. A reminder that sends nothing doesn't block a later one: the next time the buyer saves an email while reminders are on, a new reminder is scheduled. While a payment on the order is still in progress, such as a card waiting on 3D Secure or a bank debit that takes days to settle, the reminder waits, including when the payment starts just before the email goes out. It goes out if that payment fails, is canceled, or is abandoned, and not at all once the order is paid. An expired order checkout still gets its reminder, because the link can open a new checkout for the same order. An expired payment link checkout does not.

Each checkout session sends at most one reminder, and a buyer gets at most one from the same merchant per UTC day. The unsubscribe link, and the one-click unsubscribe header mail clients show, stop checkout reminders from that merchant only. Receipts and other emails keep arriving.

The link in the email works for 7 days and resolves when the buyer opens it:

The reminder goes to the email saved at checkout, which nobody confirmed, so a checkout opened from the link doesn't use the saved cards or details of a customer whose email the buyer confirmed with a code earlier. The buyer confirms their email again to use them. A customer you created the session for is unaffected.

Saved payment details#

checkout.saved_payment_details controls the unchecked option hosted checkout shows under the card fields: "Save my details for faster checkout at {business name}".

{
  "checkout": {
    "saved_payment_details": {
      "enabled": false
    }
  }
}

Nothing is saved unless the buyer checks the option and the payment succeeds. The card is then saved for the customer the checkout acts for, as a payment method with usage: "on_session": the customer you created the session for or, for a guest, the customer whose email the buyer confirmed with a code Flint emailed them. Flint charges such a card only in checkouts the buyer completes. It can't pay a subscription or an automatic invoice or become a customer's default, so it never pays for something without the buyer. See Cards buyers save in checkout.

Checkout never offers the option:

• When customer_account.mode is merchant_hosted, because your own accounts own the buyer's saved cards.
• On a checkout for an invoice, a subscription plan, or a return.
• For Apple Pay, Google Pay, ACH debit, or Affirm. Only a card the buyer types can be saved this way.
• On a checkout created for no customer, until Flint can email codes for your account.

A checkout session read with its checkout credential reports the result as save_payment_method_offered.

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.

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:

{
  "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.

Branding settings#

Use the top-level branding object to style the pages Flint hosts for your buyers: checkout, including payment link pages, and the customer account. A checkout session's or payment link's theme can override primary_color and accent_color; the other fields always come from these settings. Flint adjusts or replaces a color that wouldn't be readable, such as text too close to the background color.

Subscription settings#

Use the top-level subscriptions object to choose the default schedule owner and failed-payment policy. Read effective settings when you need the inherited values that a new subscription or billing workflow will use.

{
  "subscriptions": {
    "default_billing_schedule_owner": "external",
    "external_dunning_end_action": "notify_only",
    "dunning_retry_days": 16
  }
}

notify_only leaves an exhausted subscription past_due so your integration can update the payment method and create a manual payment retry. See Subscription billing.

Invoice settings#

Use the top-level invoices object for the defaults an invoice inherits at create time and the follow-up Flint runs after you issue it. The values that drive follow-up are frozen onto the invoice at issue, so editing them changes new invoices and leaves the ones already collecting alone.

{
  "invoices": {
    "reminder_policy": {"rules": [{"days_from_due": -3}, {"days_from_due": 7}]},
    "autopay_retry_policy": {"retry_day_offsets": [1, 3, 7]},
    "timezone": "America/New_York",
    "credit_note_number_prefix": "CN-"
  }
}

Late fees come from the payment term rather than from settings. When the term carries a late fee policy, Flint emits invoice.late_fee_due after the grace period with the computed amount. Charging it is a separate call that adds the fee to the invoice balance. See Late fees.

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 settings. Locations and devices can't override them.

Send "customer_account": null to remove the account configuration. Flint then serves the default Flint-hosted account, and GET /v1/settings omits customer_account. If the configuration had a presentation.custom_domain, removing it starts the same redirect window as removing the hostname.

presentation holds:

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.

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

buyer_capabilities holds:

Buyers can always cancel. Requests made with your API key aren't limited by buyer_capabilities. See What buyers can do to their subscriptions.

customer_account_domain_status#

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

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.

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.