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.
Note that the handling of billing via API is available starting from the Business plan and above.
Overview of the Billing Flow
The process of handling affiliate billing via API consists of the following steps:
Add/Update Affiliate Billing Details: Create or update 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.
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.
Add/Update 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 affiliate via API or you can retrieve it via this endpoint https://developers.trackdesk.com/#post-/api/node/affiliates/v1 filtering for the affiliate e.g. via 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 (e.g., bank transfer, PayPal), and the necessary details for that method.
The account ID is acquired during registration of affiliate via API or you can retrieve it via this endpoint https://developers.trackdesk.com/#post-/api/node/affiliates/v1 filtering for the affiliate e.g. via 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 account ID of the affiliate to be updated.You can update details depending on the payment method type (e.g., new IBAN for bank transfers, new PayPal email, etc.) and combination of currency.
Retrieve Open Balances
To begin, use the GET /api/node/billing/v1/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. Use the POST /api/node/billing/v1/settle-balances endpoint to accomplish this.
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 GET /api/node/billing/v1/account-settlements endpoint to retrieve this information.
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 the created settlements, use the GET /api/node/billing/v1/settlements endpoint to retrieve a list of all settlements. Additionally, you can use the GET /api/node/billing/v1/settlements/{id} endpoint to view details of a specific settlement.
Endpoints:
Key Details:
Use the general
GET /settlementsendpoint to review all settlements.If you need to examine a specific settlement, the
{id}parameter allows you to fetch detailed information for that settlement.
Delete Settlements or Account Settlements (if necessary)
In some cases, you may need to delete settlements or account settlements due to errors or adjustments. The following endpoints allow for this:
Endpoints:
Key Details:
Use the
DELETE /account-settlements/{id}endpoint to remove an account settlement.Use the
DELETE /settlements/{id}endpoint to delete a settlement.Ensure that you correctly specify the settlement ID to avoid unintended deletions.
Summary of API Endpoints
Here is a quick reference for the endpoints used in the affiliate billing flow:
Add/Update 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-balances
Settle Balances: POST /api/node/billing/v1/settle-balances
Review Account Settlements: GET /api/node/billing/v1/account-settlements
Review Settlements:
Delete Account Settlements: DELETE /api/node/billing/v1/account-settlements/{id}
Delete Settlements: DELETE /api/node/billing/v1/settlements/{id}
Conclusion
Handling affiliate billing via API is a streamlined and efficient process using Trackdesk's endpoints. By following the steps outlined above, you can ensure accurate management of affiliate payouts and maintain clean billing records. Refer to the linked API documentation for additional details about request and response structures, parameters, and examples.