Billing API

Integrate with our Billing API

Topsort’s Billing API lets you manage vendor balances, wallets and billing contacts. All Billing API endpoints use your Advanced API key. See API Key Types.

Vendor Balance and Wallet Management

• Get the current balance for a specific vendor.
• Add funds to a vendor’s balance, including a description for the transaction.
• Burn (reduce) a vendor’s balance for a specified reason.
• List all wallets associated with a vendor.
• Create a new wallet for a vendor (limit of 3 per vendor).
• Adjust the balance of a specific wallet (add positive amount, burn negative amount).

Billing Contacts

A billing contact records who an ad is for and who pays for it. Each campaign can have one billing contact, which you can display next to the ad. EU marketplaces use this to meet the advertiser transparency rules of the Digital Services Act (DSA).

Digital Services Act (DSA) Setup

Step-by-step guide: create billing contacts, link them to vendors, assign them to campaigns and show them with each ad.

Fields

Field	Description
ID	Your own identifier, set in the request path. Unique within your marketplace and case-sensitive.
advertiserName	The agency or advertiser that runs the campaign. Advertisers see this name when they choose a contact in the campaign form.
brandName	The brand the ad promotes.
invoiceTo	The company responsible for paying the invoice.

All three fields are required whenever you create or update a contact.

How Billing Contacts Are Used

1. Your marketplace creates billing contacts. Vendors and advertisers can’t create them in the Topsort UI.
2. You link each contact to one or more vendors. A vendor can have several contacts, and one contact can be shared by several vendors.
3. Each campaign gets one billing contact. Advertisers choose from their vendor’s contacts when they create a campaign in the Topsort UI. For campaigns created through the Campaign API, assign it with a separate call.
4. You fetch a campaign’s billing contact on demand. When a shopper clicks to see an ad’s details, your backend looks it up with the campaignId from the auction response, and your storefront shows it.

Endpoints

Method	Endpoint	Purpose
PUT	/billing-contacts/{billing_contact_id}	Create or update a billing contact
GET	/billing-contacts/{billing_contact_id}	Get one billing contact
GET	/billing-contacts	List billing contacts, optionally filtered by vendor ID
PUT	/vendor-billing-contact	Link a billing contact to a vendor
DELETE	/vendors/{external_vendor_id}/vendor-billing-contact/{billing_contact_id}	Unlink a billing contact from a vendor
PUT	/campaign-billing-contact	Assign or replace a campaign’s billing contact
GET	/campaign-billing-contact?campaign_id=	Get a campaign’s billing contact

All paths are relative to https://api.topsort.com/public/v1/billing-service.

Good to Know

• Updating a billing contact changes it for every campaign that uses it.
• Unlinking a contact from a vendor hides it from that vendor’s campaign forms. Campaigns that already use it keep it.
• Billing contacts can’t be deleted, and a campaign’s billing contact can be replaced but not removed.