Managing Fee Configurations

Overview

Standard Fee Configurations are managed through the Fee Configurations API. All configuration management is done at the sub account level — each sub account's configurations are created and managed individually.

The API is fee-type-centric: a configuration is created for a specific fee type (e.g., processing_ecomm), and if one already exists, the new one automatically retires the old one. There are no update or delete operations — to change a rate, you create a replacement configuration.

Optional fee types (brand-specific and platform) can additionally be retired to stop charging them entirely, without a replacement. Base processing fees are required and cannot be retired. See Retiring an Optional Configuration.

API Endpoints

Method	Endpoint	Description
`POST`	`/v1/sub_accounts/:id/fee_configurations/:fee_type`	Create a configuration (auto-retires existing config of the same fee type)
`GET`	`/v1/sub_accounts/:id/fee_configurations`	List all active configurations
`GET`	`/v1/sub_accounts/:id/fee_configurations/:fee_type`	Get active configuration for a specific fee type
`GET`	`/v1/sub_accounts/:id/fee_configurations/:fee_type/history`	Get configuration history for a fee type
`GET`	`/v1/sub_accounts/:id/fee_configurations/scheduled`	List upcoming/scheduled configurations

Configuration Parameters

Parameter	Type	Required	Description
`variable_rate`	number	Yes	Percentage rate. `2.75` = 2.75%
`transaction_fee_cents`	integer	No	Flat fee in cents added to each transaction. Defaults to `0`
`fee_cap_cents`	integer	No	Maximum fee amount in cents. If the calculated fee exceeds this amount, the cap is used instead
`effective_start`	datetime	No	When the configuration takes effect. Defaults to immediately
`effective_end`	datetime	No	When the configuration expires. Must be later than `effective_start` — the current time or earlier is rejected. Defaults to `null` — which means it stays active indefinitely. Only accepted on optional fee types (brand-specific and platform)

Creating a Configuration

To set up fees for a sub account, use the create a fee configuration API for each fee type you want to configure.

Set a base processing fee

POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

{
  "variable_rate": 2.75,
  "transaction_fee_cents": 25,
  "fee_cap_cents": 1000
}

Response:

{
  "id": "sfc_abc123",
  "type": "standard_fee_configuration",
  "data": {
    "id": "sfc_abc123",
    "account_id": "acc_xxx",
    "platform_account_id": "acc_yyy",
    "fee_type": "processing_ecomm",
    "variable_rate": 2.75,
    "transaction_fee_cents": 25,
    "transaction_fee_currency": "usd",
    "fee_cap_cents": 1000,
    "effective_start": "2026-02-25T00:00:00Z",
    "effective_end": null
  }
}

This sub account will now be charged 2.75% + $0.25 (capped at $10.00) on every card-not-present payment, unless a brand-specific configuration overrides it.

Add a brand-specific fee

POST /v1/sub_accounts/acc_xxx/fee_configurations/amex_brand_ecomm

{
  "variable_rate": 3.25,
  "transaction_fee_cents": 25
}

Amex online payments are now charged 3.25% + $0.25 instead of the base 2.75% + $0.25. All other card brands still use processing_ecomm.

Add a platform fee

POST /v1/sub_accounts/acc_xxx/fee_configurations/platform

{
  "variable_rate": 1.00
}

Every payment now also includes a 1.00% platform fee, in addition to the processing fee.

Replacing a Configuration

There is no update fee configuration API endpoint. To change a fee rate, use the create fee configuration API to create a new configuration for the same fee type. The previous configuration is automatically retired — its effective_end is set to the new configuration's effective_start.

POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

{
  "variable_rate": 2.50,
  "transaction_fee_cents": 30
}

The old processing_ecomm configuration (2.75% + $0.25) is retired, and the new one (2.50% + $0.30) takes effect immediately.

Scheduling a Future Configuration

To schedule a rate change in advance, set effective_start to a future date (in UTC):

POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

{
  "variable_rate": 2.50,
  "transaction_fee_cents": 30,
  "effective_start": "2026-04-01T00:00:00Z"
}

The current configuration stays active until April 1st, when the new one takes over automatically. The old config's effective_end is set to 2026-04-01T00:00:00Z, and the new config picks up from there with no gap in coverage.

Use the scheduled endpoint to view upcoming configurations:

GET /v1/sub_accounts/acc_xxx/fee_configurations/scheduled

Chaining Configurations

For base processing fee types, there must always be an active configuration — you cannot leave a gap in coverage, and the chain must always end with a configuration that has no effective_end (i.e., it stays active indefinitely). You can schedule temporary configs in between, but the final config in the chain must cover everything going forward.

When you POST a new config without effective_end, the system automatically retires any existing active config by setting its effective_end to the new config's effective_start.

Example: Simple rate change on April 1st

Current state:

processing_ecomm: 2.75% + $0.25 (effective_start: Feb 1, effective_end: null)

POST a new config:

{
  "variable_rate": 2.50,
  "transaction_fee_cents": 30,
  "effective_start": "2026-04-01T00:00:00Z"
}

Result:

processing_ecomm: 2.75% + $0.25 (effective_start: Feb 1,  effective_end: Apr 1)  ← auto-retired
processing_ecomm: 2.50% + $0.30 (effective_start: Apr 1,  effective_end: null)   ← takes over

Example: Temporary promotional rate

To run a promotion from March 1st through March 8th with reduced fees, then return to normal rates, build the chain by creating configs in sequence — each new config auto-retires the previous one:

1. Schedule the promotional rate starting March 1st:

POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

{
  "variable_rate": 2.00,
  "transaction_fee_cents": 15,
  "effective_start": "2026-03-01T00:00:00Z"
}

This auto-retires the current config (2.75% + $0.25) by setting its effective_end to March 1st. The promotional rate takes over from March 1st with no effective_end.

2. Schedule the return to normal rates on March 8th:

POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

{
  "variable_rate": 2.75,
  "transaction_fee_cents": 25,
  "effective_start": "2026-03-08T00:00:00Z"
}

This auto-retires the promotional config by setting its effective_end to March 8th. The normal rate takes over from March 8th indefinitely.

Result:

processing_ecomm: 2.75% + $0.25 (Feb 1  → Mar 1)   ← original, auto-retired by step 1
processing_ecomm: 2.00% + $0.15 (Mar 1  → Mar 8)   ← promotional, auto-retired by step 2
processing_ecomm: 2.75% + $0.25 (Mar 8  → forever)  ← back to normal

The chain is seamless — every moment has exactly one active configuration, and the last one extends indefinitely. There is no need to set effective_end explicitly; the system handles it when the next config in the chain is created.

Base Processing Configs Cannot Have an Effective End Date

The following base processing fee types do not accept an effective_end parameter:

processing_ecomm
processing_card_present
processing_ach
processing_ach_expedited

You only need to configure the types relevant to your sub account (e.g., only processing_ecomm if you only process online card payments). However, once created, these configurations must stay active indefinitely — they cannot be retired. If you include effective_end when creating one of these fee types, the API will reject the request with an effective_end_must_be_nil_for_fee_type error. The only way to transition to a new rate is to create a replacement config, which automatically retires the previous one by setting its effective_end to the new config's effective_start.

Retiring an Optional Configuration

Only optional fee types can be retired — turned off entirely, without a replacement:

Brand-specific fees (e.g., amex_brand_ecomm), which override the base processing rate for a single card brand.
Platform fees (platform), which add a fee on top of the processing fee.

Base processing fees (processing_ecomm, processing_card_present, processing_ach, processing_ach_expedited) are required and cannot be retired — the API rejects effective_end on those types (see the warning above). To change one of those, create a replacement configuration instead.

To retire an optional configuration, POST the same fee type with an effective_end. The configuration stops applying once that time passes.

Retire a brand-specific fee

POST /v1/sub_accounts/acc_xxx/fee_configurations/amex_brand_ecomm

{
  "variable_rate": 3.25,
  "transaction_fee_cents": 25,
  "effective_end": "2026-04-01T00:00:00Z"
}

After April 1st, Amex online payments fall back to the processing_ecomm rate.

Retire a platform fee

POST /v1/sub_accounts/acc_xxx/fee_configurations/platform

{
  "variable_rate": 1.00,
  "effective_end": "2026-04-01T00:00:00Z"
}

After April 1st, payments no longer include a platform fee.

Retire a fee as soon as possible

To turn an optional fee off right away, set effective_end to a timestamp just after the current time:

POST /v1/sub_accounts/acc_xxx/fee_configurations/platform

{
  "variable_rate": 1.00,
  "effective_end": "2026-02-25T00:01:00Z"
}

Once that time passes — typically within a minute — the configuration no longer applies. variable_rate is still required, but the rate you pass only applies during the brief window before effective_end.

note

effective_end must be later than effective_start, which defaults to the time the request is processed. The current time or earlier is rejected, so use a near-future timestamp to retire a configuration as soon as possible.

Viewing Configurations

List all active configurations

GET /v1/sub_accounts/acc_xxx/fee_configurations

Response:

{
  "type": "array",
  "page_info": {
    "has_previous": false,
    "has_next": false,
    "start_cursor": "...",
    "end_cursor": "..."
  },
  "data": [
    {
      "id": "sfc_abc123",
      "account_id": "acc_xxx",
      "platform_account_id": "acc_yyy",
      "fee_type": "processing_ecomm",
      "variable_rate": 2.75,
      "transaction_fee_cents": 25,
      "transaction_fee_currency": "usd",
      "fee_cap_cents": null,
      "effective_start": "2026-02-01T00:00:00Z",
      "effective_end": null
    },
    {
      "id": "sfc_def456",
      "account_id": "acc_xxx",
      "platform_account_id": "acc_yyy",
      "fee_type": "amex_brand_ecomm",
      "variable_rate": 3.25,
      "transaction_fee_cents": 25,
      "transaction_fee_currency": "usd",
      "fee_cap_cents": null,
      "effective_start": "2026-02-01T00:00:00Z",
      "effective_end": null
    }
  ]
}

Results are paginated. Use limit, after_cursor, and before_cursor query parameters to page through results.

Get a specific fee type

GET /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

Response:

{
  "id": "sfc_abc123",
  "type": "standard_fee_configuration",
  "data": {
    "id": "sfc_abc123",
    "account_id": "acc_xxx",
    "platform_account_id": "acc_yyy",
    "fee_type": "processing_ecomm",
    "variable_rate": 2.75,
    "transaction_fee_cents": 25,
    "transaction_fee_currency": "usd",
    "fee_cap_cents": null,
    "effective_start": "2026-02-01T00:00:00Z",
    "effective_end": null
  }
}

Returns the active configuration for that fee type, or 404 if none exists.

View configuration history

GET /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm/history

Returns all configurations for that fee type (active, retired, and scheduled), ordered by effective_start descending. Useful for auditing rate changes over time.

List scheduled configurations

GET /v1/sub_accounts/acc_xxx/fee_configurations/scheduled

Returns configurations with a future effective_start that haven't taken effect yet.

Next Steps

Fee Calculation & Examples — See how configurations translate to actual fee amounts on payments
Overview — Review the fee hierarchy and selection logic

Overview​

API Endpoints​

Configuration Parameters​

Creating a Configuration​

Set a base processing fee​

Add a brand-specific fee​

Add a platform fee​

Replacing a Configuration​

Scheduling a Future Configuration​

Chaining Configurations​

Retiring an Optional Configuration​

Retire a brand-specific fee​

Retire a platform fee​

Retire a fee as soon as possible​

Viewing Configurations​

List all active configurations​

Get a specific fee type​

View configuration history​

List scheduled configurations​

Next Steps​

Overview

API Endpoints

Configuration Parameters

Creating a Configuration

Set a base processing fee

Add a brand-specific fee

Add a platform fee

Replacing a Configuration

Scheduling a Future Configuration

Chaining Configurations

Retiring an Optional Configuration

Retire a brand-specific fee

Retire a platform fee

Retire a fee as soon as possible

Viewing Configurations

List all active configurations

Get a specific fee type

View configuration history

List scheduled configurations

Next Steps