Affiliate billing is a critical aspect of managing partnerships and ensuring timely payouts to your affiliates. With Trackdesk, handling affiliate billing can be efficiently managed via API endpoints. This article provides a detailed flow of the process to handle affiliate billing using Trackdesk's API. Each step involves specific API calls, which are explained below.
Overview of the billing flow
The process of handling affiliate billing via API consists of the following steps:
Add affiliate billing details: create billing information for affiliates.
Add affiliate payment methods: define at least one payout method for affiliates.
Update affiliate payment methods: modify existing payment method details for affiliates.
Retrieve open balances: identify all outstanding balances for affiliates.
Settle balances: create settlements for the outstanding balances.
Review account settlements: fetch previously created account settlements to ensure proper tracking.
Review settlements: review settlements that have been created to ensure accuracy.
Update settlement statuses: mark settlements as in progress or paid as you process payouts.
Delete settlements or account settlements (if necessary): manage and delete any incorrect settlements if required.
Below, we dive into each step in detail, including the API endpoints used and their purposes. There is also a separate section for Tipalti payment synchronization, which has its own dedicated endpoint set.
Add affiliate billing details
Before affiliates can be included in settlements, they must have billing details created in the system. Without this information, affiliates will be skipped during the settlement process.
Endpoint: POST /api/node/billing-details/v1
Key details:
This API call creates billing details for an affiliate account.
Required parameters are account ID, company or individual details, tax/VAT ID, and address information.
The account ID is acquired during registration of an affiliate via API, or you can retrieve it by filtering the affiliates endpoint (for example, by email).
Create affiliate payment methods
Affiliates also require at least one valid payment method before payouts can be processed. Payment methods can include bank transfer, PayPal, or other methods defined in your program settings.
Endpoint: POST /api/node/payment-methods/v1
Key details:
This API call creates a new payment method for an affiliate account.
Required parameters are account ID, type of payment method (for example, bank transfer or PayPal), and the necessary details for that method.
The account ID is acquired during registration of an affiliate via API, or you can retrieve it by filtering the affiliates endpoint (for example, by email).
Update affiliate payment methods
If an affiliate's payout details change, you can update their existing payment method instead of creating a new one.
Endpoint: PATCH /api/node/payment-methods/v1/{id}
Key details:
This API call updates an existing payment method for an affiliate account.
The
{id}parameter is required and represents the ID of the payment method to be updated.You can update details depending on the payment method type (for example, a new IBAN for bank transfers or a new PayPal email) and the currency combination.
Retrieve open balances
Use the open balances endpoint to retrieve a list of open balances for affiliates. Open balances represent amounts owed to affiliates that have not yet been settled.
Endpoint: GET /api/node/billing/v1/open-balances
Key details:
This API call returns a list of all affiliates with outstanding balances.
Use this data to identify affiliates who need to be paid and their corresponding amounts.
Settle balances
After reviewing open balances, you can settle the outstanding amounts using the settle balances endpoint.
Key details:
This API call creates settlements for the specified open balances.
You will need to provide details such as affiliate IDs and the amount to be settled.
After successful execution, this endpoint generates new settlement records.
Review account settlements
Use the account settlements endpoint to retrieve a history of created account settlements.
Key details:
This API call lists all existing account settlements, providing a history of previous actions.
Reviewing this information helps avoid duplicate settlements and ensures proper tracking.
Review settlements
To verify the accuracy of created settlements, retrieve the full list, or fetch a specific settlement by ID.
Endpoints:
Key details:
Use the general settlements endpoint to review all settlements.
If you need to examine a specific settlement, the
{id}parameter allows you to fetch detailed information for that settlement, including status counters.
Update settlement statuses
After processing payouts, you can update the status of individual settlements or bulk-update many at once. This lets you track which settlements have been paid, are in progress, or need attention.
Endpoints:
Key details:
Use the PUT endpoint to update a single settlement's status.
Use the POST bulk endpoint to update many settlements at once; the response includes the IDs of any settlements that were skipped (for example, settlements already in the target status).
Manual updates support the New, In progress, and Paid statuses. The Error status is system-driven and cannot be set manually.
See Settlement statuses for the full list of status values and the rules around manual versus automatic updates.
Tipalti payment synchronization
If your program uses Tipalti for payouts, settlement statuses for Tipalti rows are managed automatically through Tipalti sync rather than the manual status endpoints above. The Tipalti-specific endpoints and the Tipalti-to-Trackdesk status mapping are documented in the Settlement statuses article.
Delete settlements or account settlements
In some cases, you may need to delete settlements or account settlements due to errors or adjustments. The following endpoints allow this:
Endpoints:
Key details:
Use the account settlements DELETE endpoint to remove an account settlement.
Use the settlements DELETE endpoint to delete a settlement.
Ensure that you correctly specify the settlement ID to avoid unintended deletions.
Summary of API endpoints
Quick reference for the endpoints used in the affiliate billing flow:
Add billing details:
POST /api/node/billing-details/v1Add payment methods:
POST /api/node/payment-methods/v1Update payment methods:
PATCH /api/node/payment-methods/v1/{id}Retrieve open balances:
GET /api/node/billing/v1/open-balancesSettle balances:
POST /api/node/billing/v1/settle-balancesReview account settlements:
GET /api/node/billing/v1/account-settlementsReview settlements:
Update settlement status (single):
PUT /api/node/billing/v1/account-settlements/{id}/statusUpdate settlement status (bulk):
POST /api/node/billing/v1/account-settlements/bulk-update-statusDelete account settlements:
DELETE /api/node/billing/v1/account-settlements/{id}Delete settlements:
DELETE /api/node/billing/v1/settlements/{id}
See also
Settlement statuses: status values, manual versus automatic updates, and the Tipalti-to-Trackdesk status mapping.