Billing
frameOS gives platforms full control over how they charge fees on transfers. Define fee plans that specify calculation methods and amounts, then create billing agreements that link those plans to specific accounts or apply them platform-wide.
Fee plans support three application modes — deduct, add-on, and absorb — and three calculation types: flat, percentage, and flat-plus-percentage. Fee plans and billing agreements are scoped per merchant and per environment (live vs. test mode).
The Transfer Fee Plan object
Attributes
Unique identifier for the fee plan.
Always transfer_fee_plan.
The name of the fee plan.
How the fee is applied. One of deduct, add_on, or absorb.
true if the plan exists in live mode, false for test mode.
Unix timestamp of when the fee plan was created.
Unix timestamp of when the fee plan was last updated.
Array of fee plan item objects that define individual fee calculations.
Unique identifier for the fee plan item.
Always transfer_fee_plan_item.
The fee calculation model. One of flat, percentage, or flat_plus_percentage.
Flat fee amount in cents. Used by flat and flat_plus_percentage fee types.
Three-letter ISO 4217 currency code for the flat fee (e.g. USD).
Percentage rate applied to the transfer amount, as a decimal string (e.g. "2.9000" for 2.9%).
The event that triggers this fee (e.g. transfer.created).
Unix timestamp of when the item was created.
Unix timestamp of when the item was last updated.
{
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"object": "transfer_fee_plan",
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"items": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"object": "transfer_fee_plan_item",
"fee_type": "flat_plus_percentage",
"amount_fixed_cents": 25,
"amount_fixed_currency": "USD",
"amount_percentage": "2.9000",
"billable_event_type": "transfer.created",
"created": 1740657600,
"updated": 1740657600
}
]
}
Fee application modes
| Mode | Description |
|---|---|
deduct | The fee is deducted from the transfer amount (default) |
add_on | The fee is added on top of the transfer amount |
absorb | The platform absorbs the fee |
Fee types
| Fee type | Calculation |
|---|---|
flat | A fixed amount per transfer (amount_fixed_cents) |
percentage | A percentage of the transfer amount (amount * amount_percentage / 100) |
flat_plus_percentage | A fixed amount plus a percentage (amount_fixed_cents + amount * amount_percentage / 100) |
Create a transfer fee plan
Creates a new transfer fee plan.
Parameters
A name for the fee plan.
How the fee is applied. One of deduct, add_on, or absorb. Defaults to deduct.
An array of fee item objects to include in the plan.
One of flat, percentage, or flat_plus_percentage.
Flat fee amount in cents.
Currency for the flat fee. Defaults to USD.
Percentage rate (e.g. 2.9 for 2.9%).
The event that triggers the fee. Defaults to transfer.created.
Returns
Returns the newly created transfer fee plan object.
curl --request POST \
--url https://api.framepayments.com/v1/transfer_fee_plans \
--header 'Authorization: Bearer sk_test_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"items": [
{
"fee_type": "flat_plus_percentage",
"amount_fixed_cents": 25,
"amount_fixed_currency": "USD",
"amount_percentage": 2.9,
"billable_event_type": "transfer.created"
}
]
}'
{
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"object": "transfer_fee_plan",
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"items": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"object": "transfer_fee_plan_item",
"fee_type": "flat_plus_percentage",
"amount_fixed_cents": 25,
"amount_fixed_currency": "USD",
"amount_percentage": "2.9000",
"billable_event_type": "transfer.created",
"created": 1740657600,
"updated": 1740657600
}
]
}
Retrieve a transfer fee plan
Retrieves a transfer fee plan by ID. The response includes the plan's items.
Parameters
No parameters.
Returns
Returns a transfer fee plan object if a valid ID was provided.
curl --request GET \
--url https://api.framepayments.com/v1/transfer_fee_plans/d4e5f6a7-b8c9-0123-def4-567890abcdef \
--header 'Authorization: Bearer sk_test_API_KEY'
List transfer fee plans
Returns all transfer fee plans for your platform, ordered by most recently created. Results are scoped to the current environment (test vs. live mode).
Parameters
Number of results per page.
Page number.
Returns
A dictionary with a data property containing an array of transfer fee plan objects and a meta property with pagination details.
curl --request GET \
--url https://api.framepayments.com/v1/transfer_fee_plans \
--header 'Authorization: Bearer sk_test_API_KEY'
{
"data": [
{
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"object": "transfer_fee_plan",
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"items": [...]
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
The Transfer Billing Agreement object
A Transfer Billing Agreement links a fee plan to a specific account (or to the platform as a whole) and defines when that pricing becomes effective. Only one agreement can be active per account, merchant, and category combination at a time.
Attributes
Unique identifier for the billing agreement.
Always transfer_billing_agreement.
Current status. One of pending, active, or inactive.
The transfer category this agreement applies to. One of charge or payout.
The date when the agreement becomes effective.
The account this agreement applies to. null for platform-level agreements.
true if the agreement exists in live mode, false for test mode.
Unix timestamp of when the agreement was created.
Unix timestamp of when the agreement was last updated.
The associated transfer fee plan object.
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"object": "transfer_billing_agreement",
"status": "active",
"category": "charge",
"effective_date": "2026-03-01",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"fee_plan": {
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"object": "transfer_fee_plan",
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"items": [...]
}
}
Statuses
| Status | Description |
|---|---|
pending | Created but not yet active |
active | Currently applied to transfers for the account |
inactive | Deactivated and no longer applied |
Status transitions
| From | To | Allowed |
|---|---|---|
pending | active | Yes |
pending | inactive | Yes |
active | inactive | Yes |
inactive | active | Yes |
active | pending | No |
inactive | pending | No |
Category and fee mode compatibility
| Fee application mode | charge category | payout category |
|---|---|---|
deduct | Valid | Valid |
add_on | Valid | Not valid |
absorb | Not valid | Valid |
Create a transfer billing agreement
Creates a new transfer billing agreement that links a fee plan to an account.
Parameters
The ID of the transfer fee plan to assign.
The date when the agreement takes effect (e.g. 2026-03-01).
The transfer category. One of charge or payout.
The ID of the account to assign the agreement to. Omit for a platform-level agreement.
Initial status. One of pending, active, or inactive. Defaults to active.
Returns
Returns the newly created transfer billing agreement object with the associated fee plan.
curl --request POST \
--url https://api.framepayments.com/v1/transfer_billing_agreements \
--header 'Authorization: Bearer sk_test_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"transfer_fee_plan_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"effective_date": "2026-03-01",
"category": "charge"
}'
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"object": "transfer_billing_agreement",
"status": "active",
"category": "charge",
"effective_date": "2026-03-01",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"fee_plan": {
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"object": "transfer_fee_plan",
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"items": [...]
}
}
Retrieve a transfer billing agreement
Retrieves a transfer billing agreement by ID. The response includes the associated fee plan.
Parameters
No parameters.
Returns
Returns a transfer billing agreement object if a valid ID was provided.
curl --request GET \
--url https://api.framepayments.com/v1/transfer_billing_agreements/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
--header 'Authorization: Bearer sk_test_API_KEY'
List transfer billing agreements
Returns all transfer billing agreements for your platform, ordered by most recently created. Results are scoped to the current environment (test vs. live mode).
Parameters
Number of results per page.
Page number.
Returns
A dictionary with a data property containing an array of transfer billing agreement objects and a meta property with pagination details.
curl --request GET \
--url https://api.framepayments.com/v1/transfer_billing_agreements \
--header 'Authorization: Bearer sk_test_API_KEY'
{
"data": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"object": "transfer_billing_agreement",
"status": "active",
"category": "charge",
"effective_date": "2026-03-01",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"fee_plan": {...}
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
Update a transfer billing agreement
Updates the status of a transfer billing agreement. Only valid status transitions are allowed.
Parameters
Target status. One of active or inactive.
Returns
Returns the updated transfer billing agreement object.
curl --request PATCH \
--url https://api.framepayments.com/v1/transfer_billing_agreements/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
--header 'Authorization: Bearer sk_test_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"status": "inactive"
}'
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"object": "transfer_billing_agreement",
"status": "inactive",
"category": "charge",
"effective_date": "2026-03-01",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"livemode": false,
"created": 1740657600,
"updated": 1740744000,
"fee_plan": {
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"object": "transfer_fee_plan",
"name": "Standard Transfer Plan",
"fee_application_mode": "deduct",
"livemode": false,
"created": 1740657600,
"updated": 1740657600,
"items": [...]
}
}