Whitelabel

🛡

This API is secured — you need to pass access token in the Authorization header.

Sending an invitation to advertisers to the shop

Typically, inviting advertisers to the shop is done via the panel in the “Advertisers” tab (visible only to whitelabel). This endpoint provides the same functionality via API, which is useful when we want to automate the process of inviting advertisers.

POST https://api.adshero.io/v1/invitations/shop/{shopId}/whitelabel HTTP/2
Authorization: Bearer {access_token}
Content-Type: application/json

{ 
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "sellerIds": [ "string" ],
  "brands": [ "string" ]
}

curl --location --request POST \
    'https://api.adshero.io/v1/invitations/shop/{shopId}/whitelabel' \ 
    --header 'Authorization: Bearer {access_token}' \
    --header 'Content-Type: application/json' \
    --data '{ 
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "sellerIds": [ "string" ],
      "brands": [ "string" ]
    }'

Parameter descriptions:

firstName — Seller’s first name.
lastName — Seller’s last name.
email — Email address — this is the address where the seller will receive the invitation to create an account. If incorrect, the seller won’t be able to use Ads.
sellerIds — Seller ID — Identifier of the seller from the feed (external_seller_id). It can be empty, but in that case, the brands field must be filled. Defines the products the seller has access to advertise.
brands — Brand — Identifier of the brand from the feed (brand). It can be empty, but in that case, the sellerIds field must be filled. Defines the products the seller has access to advertise.

Costs report

This endpoint returns a report of advertiser costs grouped by advertising units (business slots).

GET https://api.adshero.io/v1/whitelabel/{whitelabelHash}/report/costs?startDate=2026-01-01&endDate=2026-06-30&page=1&pageSize=10 HTTP/2
Authorization: Bearer {access_token}

curl --location --request GET \
    'https://api.adshero.io/v1/whitelabel/{whitelabelHash}/report/costs?startDate=2026-01-01&endDate=2026-06-30&page=1&pageSize=10' \
    --header 'Authorization: Bearer {access_token}'

Parameter descriptions:

whitelabelHash (path, required) — whitelabel identifier (UUID), provided by Adshero as part of whitelabel configuration.
startDate (query, required) — start date, format YYYY-MM-DD. Cannot be earlier than 1 year before today.
endDate (query, optional) — end date, format YYYY-MM-DD. When not provided, defaults to yesterday (the most recent day with complete data). Cannot be earlier than startDate.
page (query, required) — page number (value > 0).
pageSize (query, required) — number of results per page (value > 0).

Example response:

{
  "data": [
    {
      "advertiserId": "adv-123",
      "sellerIds": ["seller-1", "seller-2"],
      "stats": {
        "bs-uuid-1": {
          "placementName": "Homepage",
          "regularWalletCost": "150.50",
          "bonusWalletCost": "25.00"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "itemsPerPage": 10,
    "totalResults": 42,
    "hasNext": true,
    "hasPrevious": false
  }
}

Response field descriptions:

advertiserId — advertiser identifier.
sellerIds — set of seller identifiers (seller IDs) associated with the advertiser.
stats — map of costs per advertising unit, where the key is the business slot ID:
- placementName — name of the advertising unit.
- regularWalletCost — cost from the regular wallet.
- bonusWalletCost — cost from the bonus wallet.
meta.page — current page.
meta.itemsPerPage — number of results per page.
meta.totalResults — total number of results.
meta.hasNext — whether a next page exists.
meta.hasPrevious — whether a previous page exists.

Get advertiser wallet

This endpoint returns the advertiser’s active wallet type and prepaid balance. The advertiser is identified by the seller ID (external_seller_id from the feed). The access token must be granted the wallet scope.

GET https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet HTTP/2
Authorization: Bearer {access_token}

curl --location --request GET \
    'https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet' \
    --header 'Authorization: Bearer {access_token}'

Parameter descriptions:

whitelabelHash (path, required) — whitelabel identifier (UUID), provided by Adshero as part of whitelabel configuration.
sellerId (path, required) — identifier of the seller from the feed (external_seller_id). It must match exactly one seller advertiser within the whitelabel — otherwise a 404 error is returned.

Example response:

{
  "data": {
    "type": "REGULAR",
    "balance": 150.00
  }
}

Response field descriptions:

type — the advertiser’s active wallet type: REGULAR (prepaid) or UNLIMITED (ads emission without a balance limit).
balance — prepaid balance.

Refill advertiser wallet

This endpoint credits the advertiser’s prepaid (REGULAR) wallet with the given amount. The wallet is created automatically if it does not exist yet. The refill always credits the REGULAR wallet — even when the UNLIMITED wallet is active. The access token must be granted the wallet scope.

POST https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet/refill HTTP/2
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "amount": 150.00,
  "deduplicationId": "partner-payment-2026-07-08-001"
}

curl --location --request POST \
    'https://api.adshero.io/v1/whitelabel/{whitelabelHash}/seller/{sellerId}/wallet/refill' \
    --header 'Authorization: Bearer {access_token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "amount": 150.00,
      "deduplicationId": "partner-payment-2026-07-08-001"
    }'

Parameter descriptions:

whitelabelHash (path, required) — whitelabel identifier (UUID), provided by Adshero as part of whitelabel configuration.
sellerId (path, required) — identifier of the seller from the feed (external_seller_id). It must match exactly one seller advertiser within the whitelabel — otherwise a 404 error is returned.
amount (body, required) — refill amount. Must be greater than 0.
deduplicationId (body, required) — deduplication identifier (at most 256 characters), e.g. the payment identifier on the partner side. It makes refills idempotent: repeating a request with the same deduplicationId for the same advertiser does not credit the wallet again and only returns the current wallet state.

The response has the same format as the wallet read and contains the post-refill wallet state:

{
  "data": {
    "type": "REGULAR",
    "balance": 300.00
  }
}