Digital Services Act (DSA) Setup

The EU Digital Services Act (DSA) requires online platforms that show ads to users in the European Union to tell users, for each ad and in real time:

that the content is an advertisement;
on whose behalf the ad is presented;
who paid for the ad, when that is someone different;
the main parameters used to decide who sees the ad.

Topsort stores the second and third items for you as a billing contact attached to each campaign. Your marketplace creates the billing contacts and links them to vendors, advertisers pick one when they create a campaign, and your site or app reads it back when it renders the ad.

This guide covers the data Topsort stores and how to get it to your storefront. Your legal team decides which details you must display and how. For ad labeling, see Going Live.

How It Works

Create billing contacts

Your marketplace creates one billing contact per advertiser and payer combination, using the Billing API.

Link contacts to vendors

Each billing contact is linked to the vendors it can be used for. Only linked contacts appear in the vendor’s campaign forms.

Assign a contact to each campaign

Advertisers select a billing contact when they create a campaign in the Topsort UI. Campaigns created through the API get one assigned with a separate call.

Show the disclosure with the ad

Auction winners include a campaignId. When a shopper clicks to see the ad’s details, for example an “About this ad” link, your backend fetches that campaign’s billing contact on demand and your storefront displays it.

All billing contact endpoints use your Advanced API key. See API Key Types.

The Billing Contact

A billing contact has an ID and three required text fields:

Field	What it holds	Typical DSA use
ID	Your own identifier for the contact, set in the request path.	Not displayed.
`advertiserName`	The agency or advertiser that runs the campaign. This is the name advertisers see when they choose a contact in the campaign form.	Who manages the campaign.
`brandName`	The brand the ad promotes.	On whose behalf the ad is presented.
`invoiceTo`	The company responsible for paying the invoice.	Who paid for the ad.

How billing contacts relate to vendors and campaigns:

You choose the ID. IDs are unique within your marketplace and case-sensitive. Sending a request with an existing ID updates that contact.
Contacts and vendors are many-to-many. One contact can be linked to several vendors, for example an agency that buys ads for more than one seller. One vendor can have several contacts, for example one per brand it sells.
A campaign has one billing contact at a time. Assigning a new one replaces the previous one.

Step 1: Create Billing Contacts

Call Upsert Billing Contact with the ID you want to use:

curl -X PUT https://api.topsort.com/public/v1/billing-service/billing-contacts/acme-media-brightsmile \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserName": "Acme Media Agency",
    "brandName": "BrightSmile",
    "invoiceTo": "BrightSmile Europe GmbH"
  }'

A successful call returns 204 No Content. Every call must include all three fields, because the request replaces the stored contact.

Use readable, stable IDs from your own system, such as an advertiser account number. You need the ID again in every later step.

Step 2: Link Contacts to Vendors

Call Upsert Vendor Billing Contact once for each vendor that can use the contact:

curl -X PUT https://api.topsort.com/public/v1/billing-service/vendor-billing-contact \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billingContactId": "acme-media-brightsmile",
    "vendorId": "vendor-123"
  }'

vendorId is your vendor ID, the same one you send in your catalog.
The billing contact must already exist. Otherwise the call returns 404.
Linking a contact that is already linked does nothing, so retries are safe.

To confirm which contacts a vendor has, call Get Billing Contacts with the vendor ID:

curl "https://api.topsort.com/public/v1/billing-service/billing-contacts?external_vendor_id=vendor-123" \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY"

{
  "billingContacts": [
    {
      "id": "acme-media-brightsmile",
      "advertiserName": "Acme Media Agency",
      "brandName": "BrightSmile",
      "invoiceTo": "BrightSmile Europe GmbH"
    }
  ],
  "hasMore": false,
  "nextPage": null
}

Leave out external_vendor_id to list every billing contact in your marketplace. Results come in pages of up to 100 (50 by default). When hasMore is true, send the nextPage value as the next_page query parameter to get the next page.

Step 3: Assign a Billing Contact to Each Campaign

Topsort UI
Campaign API

When a vendor has at least one linked billing contact, the campaign creation form shows a Billing Contact field in the launch step. The list contains only that vendor’s contacts, labeled by advertiserName.

Sponsored Listings campaigns require a billing contact once the vendor has one.
On other campaign types the field can be left empty. Use Step 5 to find campaigns without one.

Advertisers can change the billing contact later by editing the campaign.

Give each contact a distinct advertiserName. Two contacts with the same advertiser name look identical in the list.

Create Campaign does not accept a billing contact. After you create the campaign, assign one with Upsert Campaign Billing Contact:

curl -X PUT https://api.topsort.com/public/v1/billing-service/campaign-billing-contact \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billingContactId": "acme-media-brightsmile",
    "campaignId": "0193f2a1-7c4e-7d3a-9b2f-5e8c1a6d4f20"
  }'

campaignId is the Topsort campaign ID returned when the campaign is created.
Calling this again for the same campaign replaces its billing contact.
Assign a contact that is linked to the campaign’s vendor. The API does not check this, but the Topsort UI flags the mismatch when the campaign is edited.

Step 4: Show the Disclosure With Each Ad

Sponsored Listings and banner winners in the auction response include the campaignId of the winning campaign. Keep it with each ad you render. You don’t need the billing contact to render the ad. Fetch it on demand: when a shopper clicks to see the ad’s details, for example through an “About this ad” link, your backend calls Get Campaign Billing Contact with that campaignId:

curl "https://api.topsort.com/public/v1/billing-service/campaign-billing-contact?campaign_id=0193f2a1-7c4e-7d3a-9b2f-5e8c1a6d4f20" \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY"

{
  "id": "acme-media-brightsmile",
  "advertiserName": "Acme Media Agency",
  "brandName": "BrightSmile",
  "invoiceTo": "BrightSmile Europe GmbH"
}

Then show the details your legal team chose in the ad’s details panel. For example:

Sponsored · Advertiser: BrightSmile · Paid by: BrightSmile Europe GmbH

Build the lookup with these rules:

Fetch on demand. Call the endpoint when the shopper opens the ad’s details, not while you render ads or for every impression.
Call it from your backend. The Advanced API key must never reach a browser or mobile app. Your storefront calls your own backend endpoint, which calls Topsort.
Cache by campaign ID (optional). Many shoppers may open details for ads from the same campaign. A short cache, a few minutes, avoids repeat calls and keeps the details current. Don’t cache 404 responses, so a contact you assign later shows up right away.
Handle 404. A 404 means the campaign has no billing contact. Show a fallback, such as the vendor name, and fix the campaign as described in Step 5.

type BillingContact = {
  id: string;
  advertiserName: string;
  brandName: string;
  invoiceTo: string;
};

const cache = new Map<string, { contact: BillingContact; expiresAt: number }>();
const TTL_MS = 5 * 60 * 1000;

async function getBillingContact(campaignId: string): Promise<BillingContact | null> {
  const cached = cache.get(campaignId);
  if (cached && cached.expiresAt > Date.now()) return cached.contact;

  const res = await fetch(
    `https://api.topsort.com/public/v1/billing-service/campaign-billing-contact?campaign_id=${campaignId}`,
    { headers: { Authorization: `Bearer ${process.env.TOPSORT_ADVANCED_API_KEY}` } },
  );
  // Not cached, so a contact assigned later shows up on the next click.
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`Billing API error: ${res.status}`);

  const contact = (await res.json()) as BillingContact;
  cache.set(campaignId, { contact, expiresAt: Date.now() + TTL_MS });
  return contact;
}

Sponsored Brands winners do not include a campaignId. If you run Sponsored Brands in the EU, contact your Topsort account team.

Step 5: Check Coverage

Before you go live in the EU, and periodically after that, make sure every active campaign has a billing contact:

List your campaigns with Get Campaigns.
For each campaign, call Get Campaign Billing Contact.
For every 404, assign a contact with Upsert Campaign Billing Contact.

To find vendors that can’t pick a contact yet, call Get Billing Contacts with each vendor’s ID. An empty billingContacts list means the vendor needs a contact linked (Step 2).

Managing Billing Contacts Over Time

Correcting a contact. Send Upsert Billing Contact again with the same ID. The change applies immediately to every campaign that uses the contact. When the advertiser or payer changes. Create a new billing contact and assign it to the affected campaigns, instead of editing the existing one. Editing would change the details shown for every campaign that still uses the old contact. Unlinking a contact from a vendor. Call Delete Vendor Billing Contact:

curl -X DELETE https://api.topsort.com/public/v1/billing-service/vendors/vendor-123/vendor-billing-contact/acme-media-brightsmile \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY"

This removes the contact from the vendor’s campaign forms. Campaigns that already use it keep it. To change those campaigns, assign them a different contact.

Billing contacts can’t be deleted, and a campaign’s billing contact can’t be removed, only replaced.

Endpoint Reference

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 for one vendor
`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 a billing contact to a campaign
`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.

Troubleshooting

The Billing Contact field doesn't appear in the campaign form

The vendor has no linked billing contacts. Check with Get Billing Contacts and the vendor’s ID, then link a contact (Step 2). If the vendor has contacts and the field still doesn’t appear, contact your Topsort account team.

404: Billing contact not found

The billing contact ID doesn’t exist in your marketplace. IDs are case-sensitive and must match the ID used in Step 1 exactly. Create the contact before linking or assigning it.

404 when linking a contact to a vendor

If the billing contact exists, the vendor ID wasn’t found. Use your own vendor ID, the same one you send in your catalog, not a Topsort internal ID.

404: Campaign not found

campaignId must be the Topsort campaign ID of a campaign in your marketplace.

422: Validation error

A required field is missing or empty. Upsert Billing Contact needs advertiserName, brandName and invoiceTo on every call.

Overview

Ad Platform

Ad Server

Toppie

Advanced Integrations

API

How It Works

The Billing Contact

Step 1: Create Billing Contacts

Step 2: Link Contacts to Vendors

Step 3: Assign a Billing Contact to Each Campaign

Step 4: Show the Disclosure With Each Ad

Step 5: Check Coverage

Managing Billing Contacts Over Time

Endpoint Reference

Troubleshooting

​How It Works

​The Billing Contact

​Step 1: Create Billing Contacts

​Step 2: Link Contacts to Vendors

​Step 3: Assign a Billing Contact to Each Campaign

​Step 4: Show the Disclosure With Each Ad

​Step 5: Check Coverage

​Managing Billing Contacts Over Time

​Endpoint Reference

​Troubleshooting

How It Works

The Billing Contact

Step 1: Create Billing Contacts

Step 2: Link Contacts to Vendors

Step 3: Assign a Billing Contact to Each Campaign

Step 4: Show the Disclosure With Each Ad

Step 5: Check Coverage

Managing Billing Contacts Over Time

Endpoint Reference

Troubleshooting