Settings

Settings control how your Flint integration behaves across checkout, tipping, tax, receipts, inventory, branding, legal, subscriptions, and coupons. 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. The fees and payment_limits sections appear in reads but are operator-managed and read-only on the public API.

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

Endpoints

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

Get merchant settings #

GET/v1/settings

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

Response · 200

dataobjectrequired

metaobject

request_idstring

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
    },
    "receipts": {
      "header_text": "Thanks for your purchase",
      "is_auto_email_enabled": true
    },
    "inventory": {
      "low_stock_threshold": 5,
      "source_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
    },
    "processing_rates": {
      "rates": {
        "default": {
          "percent": 3.4,
          "flat_money": {
            "amount": 30,
            "currency": "USD"
          }
        },
        "payment_link": {
          "percent": 3.65,
          "flat_money": {
            "amount": 45,
            "currency": "USD"
          }
        }
      }
    },
    "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/settingsIdempotent

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

Request body

brandingobject

checkoutobject

couponsobject

inventoryobject

legalobject

metadatamap of string

receiptsobject

subscriptionsobject

taxobject

tippingobject

Response · 200

dataobjectrequired

metaobject

request_idstring

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
    },
    "receipts": {
      "footer_text": "Come back soon"
    },
    "coupons": {
      "max_coupons_per_order": 3
    },
    "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
    },
    "receipts": {
      "header_text": "Thanks for your purchase",
      "is_auto_email_enabled": true
    },
    "inventory": {
      "low_stock_threshold": 5,
      "source_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
    },
    "processing_rates": {
      "rates": {
        "default": {
          "percent": 3.4,
          "flat_money": {
            "amount": 30,
            "currency": "USD"
          }
        },
        "payment_link": {
          "percent": 3.65,
          "flat_money": {
            "amount": 45,
            "currency": "USD"
          }
        }
      }
    },
    "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/effective

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

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
    },
    "receipts": {
      "header_text": "Thanks for your purchase",
      "is_auto_email_enabled": true
    },
    "inventory": {
      "low_stock_threshold": 5,
      "source_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
    },
    "processing_rates": {
      "rates": {
        "default": {
          "percent": 3.4,
          "flat_money": {
            "amount": 30,
            "currency": "USD"
          }
        },
        "payment_link": {
          "percent": 3.65,
          "flat_money": {
            "amount": 45,
            "currency": "USD"
          }
        }
      }
    },
    "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/policies

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

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/policiesIdempotent

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

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

Get merchant settings#

Update merchant settings#

Get effective settings#

List settings policies#

Replace settings policies#

Get merchant settings #

Update merchant settings #

Get effective settings #

List settings policies #

Replace settings policies #