# Scheduled Charges
A scheduled charge is a payment that runs on a future date. You create it with Create Charge and a scheduled_at after today. The response contains the id of the scheduled charge, which the endpoints below use.
# List Scheduled Charges
Lists the scheduled charges that are still due, soonest first, as Console does. Paid charges and charges that failed on every attempt are not listed. A charge that failed but has attempts left is listed, because Tratta retries it.
You can filter the list by Debt Account, Customer or Payment Method, and combine the filters. An unknown ID returns an empty list, not an error.
GET https://<org-uuid>.production.tratta.io/api/v1/scheduled-charges
curl https://<org-uuid>.production.tratta.io/api/v1/scheduled-charges \
-H "Authorization: Bearer eyJ0eXA3asdk..." \
-d debt_account_id="123456" \
-d limit=50 \
-G
# Parameters
debt_account_id optional|string
Returns only the scheduled charges of this Debt Account. It accepts the Tratta id or the external_id.
customer_id optional|string
Returns only the scheduled charges of this Customer, on all of their Debt Accounts. It accepts the Tratta id or the external_id.
payment_method_id optional|string
Returns only the scheduled charges that use this Payment Method. It accepts the Tratta id.
limit optional|integer|between:1,100
Number of results per page. Defaults to 15.
page optional|integer
Page number for pagination.
# Returns
A json with data property that contains array of scheduled charge objects.
Each scheduled charge contains its Debt Account in debt_account.
{
"id": "3ca1119d-5e08-4e41-8a9f-7272e755003a",
"payment_method_type": "card",
"payment_method": {
"id": "839a0a09-5f51-45aa-a0e3-00261112109d",
"type": "card",
"card_token": {
"card_holder": "Test Holder",
"card_number": "4242",
"expiration_month": "12",
"expiration_year": "28",
"card_type": "Visa",
"card_zip": "10001"
},
"is_primary": false,
"has_active_payment_plan": false,
"has_active_settlement_offer": false,
"has_active_scheduled_charge": true,
"created_at": "2026-11-09 13:21:16",
"updated_at": "2026-11-09 13:21:16"
},
"debt_account": {
// Debt Account
},
"scheduled_at": "2026-12-01",
"successfully_charged_at": null,
"amount": 1000,
"source": "API",
"source_name": "1234",
"fees": [
{
"type": "convenience_fee",
"name": "Convenience Fee",
"amount": 250
}
],
"total_amount": 1250,
"settlement_offer": null,
"created_at": "2026-11-09 13:21:16",
"updated_at": "2026-11-09 13:21:16"
}
# Get Scheduled Charge
Returns a scheduled charge of a Debt Account. Unlike List Scheduled Charges, it also returns paid charges and charges that failed on every attempt.
GET https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{debt_account_id}/scheduled-charges/{id}
curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{debt_account_id}/scheduled-charges/{id} \
-H "Authorization: Bearer eyJ0eXA3asdk..."# Parameters
debt_account_id required|string
Tratta id or external_id of the Debt Account.
id required|string
id of the scheduled charge, returned by Create Charge or List Scheduled Charges.
Returns 404 if the scheduled charge does not belong to the Debt Account.
# Returns
A json with data property that contains created scheduled charge object.
total_amount is amount plus fees. settlement_offer is the settlement offer that the charge pays, or null.
{
"id": "3ca1119d-5e08-4e41-8a9f-7272e755003a",
"payment_method_type": "card",
"payment_method": {
"id": "839a0a09-5f51-45aa-a0e3-00261112109d",
"type": "card",
"card_token": {
"card_holder": "Test Holder",
"card_number": "4242",
"expiration_month": "12",
"expiration_year": "28",
"card_type": "Visa",
"card_zip": "10001"
},
"is_primary": false,
"has_active_payment_plan": false,
"has_active_settlement_offer": false,
"has_active_scheduled_charge": true,
"created_at": "2026-11-09 13:21:16",
"updated_at": "2026-11-09 13:21:16"
},
"scheduled_at": "2026-12-15",
"successfully_charged_at": null,
"amount": 1500,
"source": "API",
"source_name": "1234",
"fees": [
{
"type": "convenience_fee",
"name": "Convenience Fee",
"amount": 250
}
],
"total_amount": 1750,
"settlement_offer": null,
"created_at": "2026-11-09 13:21:16",
"updated_at": "2026-11-10 09:42:05"
}
# Update Scheduled Charge
Changes the amount, the date or the Payment Method of a scheduled charge. Every parameter is optional. Parameters that you leave out keep their current value.
If amount or scheduled_at changes, the Customer can get a new payment reminder. Fees are not recalculated when amount changes.
Tratta sends the scheduled-charge.update webhook event.
PUT https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{debt_account_id}/scheduled-charges/{id}
curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{debt_account_id}/scheduled-charges/{id} \
-H "Authorization: Bearer eyJ0eXA3asdk..." \
-d amount=1500 \
-d scheduled_at="2026-12-15" \
-X PUT
# Parameters
debt_account_id required|string
Tratta id or external_id of the Debt Account.
id required|string
id of the scheduled charge, returned by Create Charge or List Scheduled Charges.
Returns 404 if the scheduled charge does not belong to the Debt Account.
amount optional|integer
The amount of payment in cents. It must be between Debt Account's min_payment_amount Rule and its current_balance.
scheduled_at optional|date|after:today
Date when the charge should be scheduled at.
payment_method_id optional|string
Tratta id of the Payment Method to charge. It must belong to the Customer of the Debt Account.
# Other validations
- The scheduled charge cannot be paid. Otherwise the request fails with
422and the messageCannot update paid-off charges. - The scheduled charge cannot have failed on every attempt. Otherwise the request fails with
422and the messageCannot update charges that failed on every attempt. - If the scheduled charge uses a bank account, the bank account cannot be blocked and the Customer's ACH payments cannot be blocked. This also applies to the current Payment Method when
payment_method_idis left out.
# Returns
A json with data property that contains created scheduled charge object.
{
"id": "3ca1119d-5e08-4e41-8a9f-7272e755003a",
"payment_method_type": "card",
"payment_method": {
"id": "839a0a09-5f51-45aa-a0e3-00261112109d",
"type": "card",
"card_token": {
"card_holder": "Test Holder",
"card_number": "4242",
"expiration_month": "12",
"expiration_year": "28",
"card_type": "Visa",
"card_zip": "10001"
},
"is_primary": false,
"has_active_payment_plan": false,
"has_active_settlement_offer": false,
"has_active_scheduled_charge": true,
"created_at": "2026-11-09 13:21:16",
"updated_at": "2026-11-09 13:21:16"
},
"scheduled_at": "2026-12-15",
"successfully_charged_at": null,
"amount": 1500,
"source": "API",
"source_name": "1234",
"fees": [
{
"type": "convenience_fee",
"name": "Convenience Fee",
"amount": 250
}
],
"total_amount": 1750,
"settlement_offer": null,
"created_at": "2026-11-09 13:21:16",
"updated_at": "2026-11-10 09:42:05"
}
# Cancel Scheduled Charge
Cancels a scheduled charge, so it does not run. If the scheduled charge pays an accepted settlement offer, the settlement offer is canceled too.
Tratta sends the scheduled-charge.delete webhook event.
DELETE https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{debt_account_id}/scheduled-charges/{id}
curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{debt_account_id}/scheduled-charges/{id} \
-H "Authorization: Bearer eyJ0eXA3asdk..." \
-X DELETE
# Parameters
debt_account_id required|string
Tratta id or external_id of the Debt Account.
id required|string
id of the scheduled charge, returned by Create Charge or List Scheduled Charges.
Returns 404 if the scheduled charge does not belong to the Debt Account.
# Other validations
- The scheduled charge cannot be paid. Otherwise the request fails with
422and the messageCannot delete paid-off charges.
# Returns
{
"success": "boolean"
}← Charges Payment Plans →