> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/release-notes/api-release-notes.md).

# API Release Notes

### June 3, 2026 <a href="#id-12-12-2019-archiving-wallets-and-external-ids" id="id-12-12-2019-archiving-wallets-and-external-ids"></a>

#### **Bug Fixes (General Availability)**

**Partner APIs — Banner X**

Fixed an issue where Banner X CTA validation failed when CTA text is disabled in content standards CTA validation now follows content standard settings. When CTA is enabled but CTA text is disabled, `ctaLink` and `ctaTextAccessibility` are required; `ctaText` is required only when text is enabled and mandatory in the content standard. Resolves errors when creating or updating Banner X campaigns with text-disabled CTAs.

Affected APIs:

* [Create Banner X campaign](https://developers.citrusad.com/partner/reference/createbannerxcampaign-1)
* [Update Banner X campaign](https://developers.citrusad.com/partner/reference/updatebannerxcampaign)
* [Create campaigns in bulk](https://developers.citrusad.com/partner/reference/bulkcreatecampaign) (Banner X)
* [Update campaigns in bulk](https://developers.citrusad.com/partner/reference/bulkupdatecampaign-1) (Banner X)

No schema changes. Integrations sending valid CTA payloads for their content standard should see fewer validation errors.

### May 13, 2026

#### **Bug Fixes (General Availability)**

**Partner APIs — Wallets**

Fixed an issue where updating `externalId` only succeeded when the supplier wallet external ID flag was enabled, even if the retailer flag was on. Updates now succeed when either flag is enabled.

Affected APIs:

* [Update wallet](https://developers.citrusad.com/partner/reference/updatewallet-1)
* [Update wallets in bulk](https://developers.citrusad.com/partner/reference/bulkupdatewallet)

Existing integrations are unaffected unless they were blocked by the incorrect validation. No request or response schema changes.\\

### March 18, 2026 <a href="#id-12-12-2019-archiving-wallets-and-external-ids" id="id-12-12-2019-archiving-wallets-and-external-ids"></a>

#### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability" id="bug-fixes-general-availability"></a>

**Partner APIs - Content Standards**

**Minimum impression price did not support decimal values** This has been improved by introducing a new optional field, `minImpressionPrice`, which returns the minimum impression price as a decimal value at the content standard level.

Affected APIs:

* [Get Banner X content standard details](https://developers.citrusad.com/partner/reference/getbannerxcontentstandard-1)
* [Retrieve list of content standards for Banner X campaigns](https://developers.citrusad.com/partner/reference/listbannerxcontentstandard)
* [Get banner content standard details](https://developers.citrusad.com/partner/reference/getbannercontentstandard)
* [Retrieve list of content standards for banner campaigns](https://developers.citrusad.com/partner/reference/listbannercontentstandard)

This enhancement does not impact any existing integrations that already use the `minImpressionPrice` field. All current integrations will continue to function as expected without modification.

> The new field is optional across all endpoints listed above.

### March 04, 2026 <a href="#id-39.0" id="id-39.0"></a>

#### Enhancements (General Availability) <a href="#new-features-general-availability" id="new-features-general-availability"></a>

**Partner APIs**

The following APIs has been enhanced:

* [Upload a campaign file](https://developers.citrusad.com/partner/reference/uploadfile-2): This endpoint now supports creatives from Brand Pages. The maximum supported file size has been increased to 4 GB, allowing larger campaign files to be uploaded.
* [Retrieve campaign file URL](https://developers.citrusad.com/partner/reference/getcampaignfileurl): This endpoint has been enhanced to support creatives from Brand Pages. The image ID and URL for Brand Page creatives are now returned, with updated enums reflecting this support.

### February 25, 2026 <a href="#february-25-2026" id="february-25-2026"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-1" id="new-features-general-availability-1"></a>

**Partner APIs**

The following APIs has been added:

* [Invite users to teams in bulk](https://developers.citrusad.com/partner/reference/bulkinviteusers): This endpoint enables adding multiple users to a team in a single request. It also supports assigning a single user to multiple teams, simplifying bulk user onboarding and team access.
* [Remove users from teams in bulk](https://developers.citrusad.com/partner/reference/bulkremoveusers): This endpoint allows removing multiple users from teams in a single request, streamlining bulk user removal across teams.

#### **Enhancements** (General Availability) <a href="#enhancements-general-availability" id="enhancements-general-availability"></a>

[Retrieve bulk team operation status](https://developers.citrusad.com/partner/reference/bulkteamstatus): The bulk team operation status response has been enhanced with a new field, `inviteUsersRequest`. This provides better visibility into bulk user invite requests and their processing status.

### January 14, 2026 <a href="#january-14-2026" id="january-14-2026"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-2" id="new-features-general-availability-2"></a>

**Partner APIs**

The following API has been added:

[Retrieve user key](https://developers.citrusad.com/partner/reference/getuserkey-1): This new endpoint allows partners to retrieve a **user key** by passing valid user credentials (username and password). The user key can then be used to generate authentication tokens for secure API access.

#### **Enhancements** (General Availability) <a href="#enhancements-general-availability-1" id="enhancements-general-availability-1"></a>

[Create Banner Campaign in bulk](https://developers.citrusad.com/partner/reference/bulkcreatecampaign): This endpoint creates multiple campaigns simultaneously (up to 1,000) based on campaign type. With this code, API users will be able to create multiple Banner Campaigns in one go which reduces the time and effort.

**Environment-Specific API Host URL Update:** Updated API host URLs to include environment-specific subdomains (for example, `campaign.<env>.citrusad.com`) to ensure proper client access across different environments for [Product Campaign](https://developers.citrusad.com/partner/reference/productcampaign-1) operations.

#### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-1" id="bug-fixes-general-availability-1"></a>

**Unable to launch or save BannerX campaign in New UI due to API validation error** The validation logic has been updated to allow `application/octet-stream` as one of the valid file types for banner and BannerX campaigns. This resolves issues where users were unable to create or update BannerX campaigns due to file type validation errors.

**User key revocation fails after Okta account suspension for Partner API usage** Implemented an Okta account status check (ACTIVE or SUSPENDED) when creating an `auth_token` using a user key. This ensures tokens are only generated for active users, preventing unauthorized access after account suspension or deactivation.

**BannerX CTA text validation allows equal to limit** Modified the validation logic for BannerX CTA text to accept character lengths that are equal to or less than the limit defined in content standards. Previously, the API only allowed lengths strictly less than the limit, causing errors for valid inputs. This fix resolves issues where users were unable to submit campaigns due to incorrect validation.

### December 16, 2025 <a href="#december-16-2025" id="december-16-2025"></a>

**Partner APIs**

**Bug Fix (General Availability)**

**Unable to submit BannerX campaign in new UI due to file type validation error** The validation logic has been enhanced to support files with the `application/octet-stream` MIME type. This update allows users to create and update BannerX campaigns without submission errors when such files are used.

### November 12, 2025 <a href="#november-12-2025" id="november-12-2025"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-3" id="new-features-general-availability-3"></a>

**Partner APIs**

The following APIs have been added:

* [Create campaigns in bulk](https://developers.citrusad.com/partner/reference/bulkcreatecampaign): This endpoint allows users to create up to 1,000 campaigns in a single request, reducing manual effort and setup time. It supports Product and BannerX campaign types.
* [Create teams in bulk](https://developers.citrusad.com/partner/reference/bulkcreateteam): This endpoint enables partners to create up to 50 teams in a single request. This streamlines large-scale team onboarding by allowing users to specify team details, company information, and business settings to organize advertising campaigns and manage user access efficiently. If a request includes more than 50 teams, the API returns an error indicating that the limit has been exceeded.

#### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-3" id="bug-fixes-general-availability-3"></a>

**Unable to launch/save BannerX campaign in V2 UI due to API validation error** Validator logic updated to skip checks if image dimensions (width, height) or maxSize are null or not specified in content standard by Retailers, allowing campaign creation in those edge cases.

**BannerX campaign creation fails when image positions are not provided as inputs** Default values are now applied when image position values are not provided during Banner X campaign creation. This update ensures campaigns can be created when image positions are optional and values are not provided.

### November 5, 2025 <a href="#november-5-2025" id="november-5-2025"></a>

**Partner APIs**

**Host URL updates** Updated API host URLs to include environment-specific subdomains (e.g., campaign.\<env>.citrusad.com) to enable proper client access across different environments for the following operations:

* [Team](https://developers.citrusad.com/partner/reference/team) and [User](https://developers.citrusad.com/partner/reference/user-1)
* [Wallet](https://developers.citrusad.com/partner/reference/wallet) and [Spend](https://developers.citrusad.com/partner/reference/getcampaignspend)

#### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-4" id="bug-fixes-general-availability-4"></a>

**Bulk Wallets API** Secondary retailer permission checks have been added to the Bulk Wallet APIs. This update ensures that when a secondary retailer user attempts to [Create](https://developers.citrusad.com/partner/reference/bulkcreatewallet) or [Update](https://developers.citrusad.com/partner/reference/bulkupdatewallet) wallets via bulk operations, the system now throws an appropriate error. This prevents unauthorized wallet modifications and enforces correct permission boundaries for secondary retailer roles.

**Bulk Teams API** Supplier users are now limited to a maximum of 50 team entries per request when using [Update teams in bulk](https://developers.citrusad.com/partner/reference/bulkupdateteam). This update helps mitigate performance issues in the Auth Service that could arise from large payloads submitted by supplier accounts.

### October 29, 2025 <a href="#id-39.0-1" id="id-39.0-1"></a>

#### Enhancements (General Availability) <a href="#new-features-general-availability-4" id="new-features-general-availability-4"></a>

**Partner APIs**

The following APIs has been enhanced:

* **Host URL updates**: Updated API host URLs to include environment-specific subdomains (e.g., campaign.\<env>.citrusad.com) to enable proper client access across different environments for the following operations:
  * [Banner X campaign](https://developers.citrusad.com/partner/reference/bannerxcampaign-1)
  * [Banner campaign](https://developers.citrusad.com/partner/reference/bannercampaign)
  * [Campaign files](https://developers.citrusad.com/partner/reference/uploadfile-2)
  * [Content standard](https://developers.citrusad.com/partner/reference/bannerxcontentstandard)
  * [Campaign](https://developers.citrusad.com/partner/reference/listcampaigns-1)
* **Pagination support for Bulk Operations**: Bulk operations have been enhanced to include pagination (default: 20 items per page) and status-based filtering (supported values: `BULK_ITEM_SUCCESS` and `BULK_ITEM_FAILED`), delivering improved performance and more targeted data retrieval. Pagination support is now available for the following operations:
  * [Retrieve bulk operation status](https://developers.citrusad.com/partner/reference/bulkcampaignstatus-1)
  * [Retrieve bulk wallet operation status](https://developers.citrusad.com/partner/reference/bulkwalletstatus)
  * [Retrieve bulk team operation status](https://developers.citrusad.com/partner/reference/bulkteamstatus)

#### **Bug Fixes** (General Availability) <a href="#enhancements-general-availability-2" id="enhancements-general-availability-2"></a>

[Update a team](https://developers.citrusad.com/partner/reference/updateteam): With this update, the `companyType` is no longer required in the request payload. The following fields have been excluded from the Update Team API:

* `companyType`
* `industryType`
* `namespaceId`

### October 22, 2025 <a href="#id-39.0-2" id="id-39.0-2"></a>

### New Features (General Availability) <a href="#new-features-general-availability-5" id="new-features-general-availability-5"></a>

#### Partner APIs <a href="#partner-apis-8" id="partner-apis-8"></a>

The following APIs have been added:

* [Create wallets in bulk](https://developers.citrusad.com/partner/reference/bulkcreatewallet): Added support to create wallets in bulk (up to 1,000) with configurable details such as currency, limits, and team assignments.
* [Create team - v3](https://developers.citrusad.com/partner/reference/createteam): This endpoint introduces the ability to create teams to streamline campaign management and user access. In v3, direct addition of users to a team using `userIds` has been removed; users must now be invited through the invite flow, enabling better control and traceability.

### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-5" id="bug-fixes-general-availability-5"></a>

[Retrieve bulk operation status](https://developers.citrusad.com/partner/reference/bulkcampaignstatus-2) Suppliers can now successfully retrieve the status of bulk team update operations they initiate. Previously, this resulted in a 403 Forbidden error, blocking validation and testing.

### October 8, 2025 <a href="#id-39.0-3" id="id-39.0-3"></a>

### New Features (General Availability) <a href="#new-features-general-availability-6" id="new-features-general-availability-6"></a>

#### Partner APIs <a href="#partner-apis-9" id="partner-apis-9"></a>

The following APIs have been added:

**Bulk campaign approval**

* [Update teams in bulk](https://developers.citrusad.com/partner/reference/bulkupdateteam): This endpoint allows bulk updates of Teams (up to 1,000) in a single API call. Supported fields include team name, company information, contact details, or team settings across several teams.
* [Retrieve bulk team operation status](https://developers.citrusad.com/partner/reference/bulkteamstatus): This endpoint provides the progress and completion status of a bulk team update operation.

### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-6" id="bug-fixes-general-availability-6"></a>

[Upload a campaign file](https://developers.citrusad.com/partner/reference/uploadfile-2): The validation logic has been updated to make slot ID optional for logo and PDF file uploads. This resolves issues where users were unable to upload these file types without providing a slot ID, which was not required for these specific campaign file formats.

In `v4/campaign-file-upload`, slot ID is no longer mandatory when `campaignFileType` is one of the following:

* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_PDF_FILE`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_PDF_FILE`

### October 1, 2025 <a href="#october-1-2025" id="october-1-2025"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-7" id="new-features-general-availability-7"></a>

**Partner APIs**

The following APIs have been added:

[Retrieve list of all campaigns](https://developers.citrusad.com/partner/reference/listcampaigns-1): This endpoint has been enhanced to support a new date range filter (`from` and `to`), allowing users to narrow results to a specific time period. It returns a list of campaigns based on specified filters and parameters such as campaign name, campaign type, placement ID, team ID, approval state, and others. Pagination and sorting are supported to efficiently handle large datasets.

[Upload a campaign file - v4](https://developers.citrusad.com/partner/reference/uploadfile-2): This endpoint enables the upload of various campaign file types. It supports hero image display modes and background positioning controls. Content files must be in standard PDF format. Display logos are supported in JPEG, JPG, or PNG formats. **File type details:**

Banner (`Campaign_File_Type_Banner_Image`)

* Accepted formats: JPEG, JPG, PNG, GIF
* Required fields: `slot ID`, `content standard ID`, `team ID`

BannerX (`Campaign_File_Type_Banner_X_Image`)

* Accepted format&#x73;**:** PDF, SVG
* Required fields: `slot ID`, `content standard ID`, `slotType`, `imageType`

### September 24, 2025 <a href="#september-24-2025" id="september-24-2025"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-8" id="new-features-general-availability-8"></a>

**Partner APIs**

The following API has been added:

[Retrieve campaign spend details](https://developers.citrusad.com/partner/reference/getcampaignspend): This endpoint calculates the remaining budget for specific campaigns based on their available balance and spending limits. It helps advertisers monitor how much budget is left across different time intervals (daily, hourly, or total) to better manage campaign spending and budget allocation.

### September 17, 2025 <a href="#id-39.0-4" id="id-39.0-4"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-9" id="new-features-general-availability-9"></a>

**Partner APIs**

The following APIs have been added:

* [Retrieve bulk wallet operation status](https://developers.citrusad.com/partner/reference/bulkwalletstatus): Allows users to check the progress and completion status of a bulk wallet operation using its `bulk ID`.
* [Update wallets in bulk](https://citrusad-group.readme.io/partner/reference/bulkupdatewallet): Enables simultaneous updates to multiple wallets. Use this endpoint to update name, external ID, archived status, daily budget, and credit limit.
* [Update campaigns in bulk](https://developers.citrusad.com/partner/reference/bulkupdatecampaign-1): Supports bulk updates of Banner X campaigns using the new enum `CAMPAIGN_TYPE_BANNERX`. Enables modifications to banner-specific parameters such as creative assets, targeting criteria, and bid strategies across multiple campaigns.

#### Enhancements (General Availability) <a href="#enhancements-general-availability-3" id="enhancements-general-availability-3"></a>

**Banner X API**

[Create a banner X](https://developers.citrusad.com/partner/reference/createbannerxcampaign-1) and[ Update banner X](https://developers.citrusad.com/partner/reference/updatebannerxcampaign) has been enhanced with field-level validations for key configuration fields. These validations ensure data integrity and alignment with the `contentStandardId` specifications.

### September 10, 2025 <a href="#id-39.0-5" id="id-39.0-5"></a>

#### Enhancements (General Availability) <a href="#new-features-general-availability-10" id="new-features-general-availability-10"></a>

**Partner APIs**

The following API has been enhanced:

**Bulk Campaign API**

The [Update campaigns in bulk](https://developers.citrusad.com/partner/reference/bulkupdatecampaign) API now supports bulk updates of **Banner Campaigns** using the new Enum `CAMPAIGN_TYPE_BANNER`. This feature allows for bulk modifications of banner-specific parameters, including creative assets, targeting criteria, and bid strategies across multiple campaigns.

**Wallet API**

The [List all wallets](https://developers.citrusad.com/partner/reference/listwallets) API now supports filtering by an array of `walletIds`, reducing repetitive API calls and improving performance for V2 UI use cases.

#### **Bug Fixes** (General Availability) <a href="#enhancements-general-availability-4" id="enhancements-general-availability-4"></a>

**Create campaign**

The API validation logic has been updated to prevent submission errors when creating a campaign with an excluded placement. An additional check was added to ensure that an error is raised only if a placement ID is excluded for a question and the user attempts to submit an answer. This resolves issues where campaigns without customQuestions in the payload were incorrectly blocked during submission.

**Banner API**

Addressed a validation error in the link field that previously resulted in incorrect responses for certain input formats. The API has been updated to handle valid inputs as expected.

### August 20, 2025 <a href="#id-39.0-7" id="id-39.0-7"></a>

#### New Features (General Availability) <a href="#new-features-general-availability-11" id="new-features-general-availability-11"></a>

**Partner APIs**

The following API has been added:

[Update campaigns in bulk](https://developers.citrusad.com/partner/reference/bulkupdatecampaign): This endpoint updates up to 1000 campaigns simultaneously within a specified namespace using a single API call. Use this to modify campaigns based on campaign type and field mask.

#### Enhancements (General Availability) <a href="#enhancements-general-availability-5" id="enhancements-general-availability-5"></a>

**Campaign API - Placement-level minimum bid enhancements**

Placement-level minimum bid changes have been introduced to the [Retrieve minimum bid details for keywords](https://developers.citrusad.com/partner/reference/retrievekeywordsminbid) and [Retrieve minimum bid details for category](https://developers.citrusad.com/partner/reference/retrievecategoryminbid) APIs, enabling more accurate and structured bidding strategies across campaigns and individual placements.

**Wallet API**

* [Create a wallet](https://developers.citrusad.com/partner/reference/createwallet): This endpoint has been enhanced to enforce role-based and permission-based restrictions, ensuring wallet creation complies with business rules and permissions.
* [Update a wallet](https://developers.citrusad.com/partner/reference/updatewallet-1): This endpoint has been improved to validate `retailerTeamID` and the `supplierCreditLimitManagement` setting, enabling retailers to update supplier wallets and manage credit limits more effectively.

**Team and User API**

[List all teams](https://developers.citrusad.com/partner/reference/listteams): This endpoint now supports partial matching on the `team name` filter, replacing the previous exact match requirement. This improvement aligns filtering behavior with other list endpoints and provides enhanced search flexibility.

### August 6, 2025 <a href="#id-39.0-8" id="id-39.0-8"></a>

### New Features (General Availability) <a href="#new-features-general-availability-12" id="new-features-general-availability-12"></a>

#### Partner APIs <a href="#partner-apis-15" id="partner-apis-15"></a>

The following APIs have been added:

**Bulk campaign approval**

* [**Update campaign approval state**](https://developers.citrusad.com/partner/reference/bulkcampaignapproval): This endpoint allows you to approve or reject multiple campaigns in bulk within a specified namespace and assign them to a team. It efficiently updates campaign statuses and team associations for large batches. Campaign approval may take longer due to GCS rate-limiting during backend processing.
* [**Retrieve bulk operation status**](https://developers.citrusad.com/partner/reference/bulkcampaignstatus): This endpoint serves as a common status API for all bulk operations. It allows users to retrieve the status and details of any bulk campaign operation request using the bulk operation ID.

### Enhancements (General Availability) <a href="#enhancements-general-availability-6" id="enhancements-general-availability-6"></a>

**Banner campaign API**

The [**Create** ](https://developers.citrusad.com/partner/reference/createbannercampaign-1)**and** [**Update** ](https://developers.citrusad.com/partner/reference/updatebannercampaign-1)**Banner Campaign** endpoints have been enhanced to include field-level validations for the `bannerConfig` object. These validations ensure compliance with content standards defined by each retailer, improving data integrity and consistency across banner submissions. This enhancement helps ensure that banner content adheres to retailer guidelines, reducing errors and improving campaign quality.

### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-8" id="bug-fixes-general-availability-8"></a>

**Improved pagination**

The behavior of the `nextPageToken` across several List API endpoints has been improved to ensure consistent and accurate pagination. The following changes have been implemented:

* `nextPageToken` is now only returned when additional data is available.
* Final pages no longer include a `nextPageToken`.
* When a `pageToken` is used and no further records exist, the correct `totalCount` is returned.

### July 9, 2025 <a href="#id-39.0-9" id="id-39.0-9"></a>

### New Features (General Availability) <a href="#new-features-general-availability-13" id="new-features-general-availability-13"></a>

#### Partner APIs <a href="#partner-apis-16" id="partner-apis-16"></a>

The following API has been added:

* [**Retrieve minimum bid details for category**](https://developers.citrusad.com/partner/reference/retrievecategoryminbid): This endpoint allows you to retrieve individual minimum bid details and the overall campaign minimum bid for **Category** placement type campaigns.

### Enhancements (General Availability) <a href="#enhancements-general-availability-7" id="enhancements-general-availability-7"></a>

#### Retrieve user details **API** <a href="#fixed-issues-general-availability" id="fixed-issues-general-availability"></a>

We have enhanced the [Retrieve User Details](https://developers.citrusad.com/partner/reference/getusersforteam) API to support filtering by User ID. You can now retrieve user information such as first name, last name, and email address by simply providing the User ID.

#### Retrieve campaign history **API** <a href="#fixed-issues-general-availability-1" id="fixed-issues-general-availability-1"></a>

We have enhanced the [Retrieve Campaign History API](https://developers.citrusad.com/partner/reference/getcampaignhistory) by adding two new filters: `fromDate` and `toDate`. You can now specify a start and end timestamp to retrieve campaign history. For example, if you set `fromDate` to July 8, 2024, and `toDate` to July 8, 2025, the API will retrieve campaign history from July 8, 2024, to July 8, 2025.

### Fixed Issues (General Availability) <a href="#fixed-issues-general-availability-2" id="fixed-issues-general-availability-2"></a>

#### Upload a campaign file **API** <a href="#fixed-issues-general-availability-3" id="fixed-issues-general-availability-3"></a>

The supported files types for banner, banner X, and content standard display logo file types is updated. Here are the supported file types:

* **Banner file types**: The API now supports PNG, JPEG, and JPG formats.
* **Banner X file types**: The API now supports PNG, JPEG, JPG, SVG, and GIF formats.
* **Content standard display logo file types**: The API now supports JPEG, JPG, and PNG formats.

For more information, see [Upload a campaign file](https://developers.citrusad.com/partner/reference/uploadfile).

### June 25, 2025 <a href="#id-39.0-10" id="id-39.0-10"></a>

### New Features (General Availability) <a href="#new-features-general-availability-14" id="new-features-general-availability-14"></a>

#### Partner APIs <a href="#partner-apis-17" id="partner-apis-17"></a>

The following APIs have been added:

* [**Retrieve minimum bid details for keywords**](https://developers.citrusad.com/partner/reference/retrievekeywordsminbid): This endpoint allows you to retrieve individual minimum bid details and the overall campaign minimum bid for a specified array of keywords in **Search** and **Category & Search** placement type campaigns. You can specify up to 1000 search keywords.
* [**Retrieve campaign history**](https://developers.citrusad.com/partner/reference/getcampaignhistory): This endpoint allows you to retrieve a campaign's history using its campaign ID.

### Enhancements (General Availability) <a href="#enhancements-general-availability-8" id="enhancements-general-availability-8"></a>

#### Update a team **API** <a href="#fixed-issues-general-availability-4" id="fixed-issues-general-availability-4"></a>

You can now update a team's logo ID using the update a team API. For more information, see [Update a team](https://developers.citrusad.com/partner/reference/updateteam-1) API.

#### **Retrieve list of all campaign types** **API** <a href="#fixed-issues-general-availability-5" id="fixed-issues-general-availability-5"></a>

You can now filter campaigns using specified campaign IDs. For more information, see [Retrieve list of all campaign types](https://developers.citrusad.com/partner/reference/listcampaigns-1) **API**.

### June 11, 2025 <a href="#id-39.0-11" id="id-39.0-11"></a>

### New Features (General Availability) <a href="#new-features-general-availability-15" id="new-features-general-availability-15"></a>

#### Partner APIs <a href="#partner-apis-18" id="partner-apis-18"></a>

The following APIs have been added:

* [Update current user detail](https://developers.citrusad.com/partner/reference/updateuserprofile): This endpoint allows you to modify the details of the user currently logged into the Epsilon Retail Media platform.
* [Modify user permission](https://developers.citrusad.com/partner/reference/modifyuserpermission): This endpoint allows you to update a user's permissions based on the provided user ID and team ID.
* [Upload a file](https://developers.citrusad.com/partner/reference/uploadfile-1): This endpoint allows you to upload logo for user profiles and teams.
* [Retrieve file URL](https://developers.citrusad.com/partner/reference/getfileurl): This endpoint retrieves the URL for a team or user logo using the specified file ID.

### Enhancements (General Availability) <a href="#enhancements-general-availability-9" id="enhancements-general-availability-9"></a>

#### Retrieve campaign file URL **API** <a href="#fixed-issues-general-availability-6" id="fixed-issues-general-availability-6"></a>

The [Retrieve campaign file URL](https://developers.citrusad.com/partner/reference/getcampaignfileurl) API retrieves the URL of a campaign file using the specified file ID and file type. It has been enhanced to support both banner and banner X content standard PDF and display logo. This improvement allows partners to upload both asset types using the existing endpoint, streamlining the creative submission process. The following additional campaign file types have been added:

* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_PDF_FILE`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_PDF_FILE`

#### Wallet API <a href="#wallet-api" id="wallet-api"></a>

The [List all wallets](https://developers.citrusad.com/partner/reference/listwallets) API has been enhanced to allow filtering by:

* **External ID**: Enables tracking with custom identifiers such as purchase order numbers.
* **Wallet name**: Allows filtering by specified wallet name.

### March-May 2025 - Managed Rollout <a href="#id-39.0-12" id="id-39.0-12"></a>

#### Enhancements (General Availability) <a href="#fixed-issues-general-availability-7" id="fixed-issues-general-availability-7"></a>

**Wallet API**

The [List all wallets](https://developers.citrusad.com/partner/reference/listwallets) API is now enhanced to support new sorting options:

* Wallet Name { name }
* Available Balance { availableBalance }

Sorting can be done in ascending or descending order, giving integration partners more flexibility in organizing wallet data.

**Upload the creative asset API**

The [Upload creative asset API](https://developers.citrusad.com/partner/reference/uploadfile) has been enhanced to support both banner and banner X content standard PDF and display logo. This enhancement allows partners to upload both asset types using the existing endpoint, streamlining the creative submission process.

The following additional campaign file types have been added:

* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_PDF_FILE`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_PDF_FILE`

### May 14, 2025 <a href="#id-39.0-14" id="id-39.0-14"></a>

#### New Features (General Availability) <a href="#fixed-issues-general-availability-8" id="fixed-issues-general-availability-8"></a>

**Partner APIs**

The following APIs have been added:

* [Retrieve user details](https://developers.citrusad.com/partner/reference/getusersforteam): This endpoint fetches details of all users associated with a specified team ID.
* [Retrieve current user detail](https://developers.citrusad.com/partner/reference/getuserdetail): This endpoint fetches detailed information about the user currently logged into the Epsilon Retail Media platform.

#### Enhancements (General Availability) <a href="#fixed-issues-general-availability-9" id="fixed-issues-general-availability-9"></a>

**Wallet API**

The [List all wallets](https://developers.citrusad.com/partner/reference/listwallets) API has been enhanced to allow filtering by a specified wallet name.

#### Fixed Issues (General Availability) <a href="#fixed-issues-general-availability-10" id="fixed-issues-general-availability-10"></a>

**Removed UUID validation from Retrieve File URL API**

We've fixed a minor bug in the [Retrieve File URL](https://developers.citrusad.com/partner/reference/getcampaignfileurl) API by removing the UUID validation check. This change allows support for both old and new banner creative images that do not adhere to the UUID format.

### April 30, 2025 <a href="#id-39.0-15" id="id-39.0-15"></a>

### New Features (General Availability) <a href="#new-features-general-availability-16" id="new-features-general-availability-16"></a>

#### Partner APIs <a href="#partner-apis-19" id="partner-apis-19"></a>

The following APIs have been added:

* [Remove a user](https://developers.citrusad.com/partner/reference/removeuser): This endpoint lets a retailer, supplier, or admin remove a user from the team.
* [Lists all suggested search terms](https://developers.citrusad.com/partner/reference/listsuggestedsearchterms): List suggested search terms based on specified parameters like catalog ID, product code, etc.

#### Enhancements (General Availability) <a href="#fixed-issues-general-availability-11" id="fixed-issues-general-availability-11"></a>

**Enhancements to the `campaignFileType` object**

The `campaignFileType` object in the [Retrieve file URL](https://developers.citrusad.com/partner/reference/getcampaignfileurl) is now enhanced to retrieve content standard PDFs and logos. This update allows our partners to easily access the latest copies of these files via our Partner API, eliminating the need to hardcode this information in the UI layer.

The following additional file types have been added:

* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_X_CONTENT_STANDARD_PDF_FILE`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_DISPLAY_LOGO`
* `CAMPAIGN_FILE_TYPE_BANNER_CONTENT_STANDARD_PDF_FILE`

#### Fixed Issues (General Availability) <a href="#fixed-issues-general-availability-12" id="fixed-issues-general-availability-12"></a>

**Removal of approval object for banner and banner x endpoints**

By default all the campaign approval state is defaulted to `APPROVAL_STATE_PENDING`. Hence, the approval object is removed from the `bannerXCampaign` and `bannerCampaign` object. For more information, see [banner](https://developers.citrusad.com/partner/reference/bannercampaign) and [banner X](https://developers.citrusad.com/partner/reference/bannerxcampaign-1) endpoints.

**API update failure for banner and banner X campaigns without mask field**

An error has been resolved where updates to [banner](https://developers.citrusad.com/partner/reference/bannercampaign) and [banner X](https://developers.citrusad.com/partner/reference/bannerxcampaign-1) campaigns via the API failed if the `mask` field was not included.

**Error message**:

```
{
    "code": 3,
    "message": "Unknown campaign type: UNDEFINED",
    "details": []
}
```

**Resolution**: The update process for banner and banner X campaigns via the `PATCH` method now correctly processes updates even when the `mask` field is not included.

**Enhanced error handling for joining a team with invitation token**

**Issue**: Previously, if a user attempted to join a team using an already used invitation token, the API provided a 200 OK response instead of a valid error message.

**Solution**: The error handling has been updated to provide a 400 Bad Request response with an error message: `User already a member of the team.`

### April 16, 2025 <a href="#id-39.0-16" id="id-39.0-16"></a>

### New Features (General Availability) <a href="#new-features-general-availability-17" id="new-features-general-availability-17"></a>

#### Partner APIs <a href="#partner-apis-20" id="partner-apis-20"></a>

The following APIs have been added:

* [Join a team with invitation token](https://developers.citrusad.com/partner/reference/jointeam-invitetoken): Allows users to join a team using a valid, unexpired invitation token.
* [Invite a user to the team](https://developers.citrusad.com/partner/reference/createuserteaminvite): Sends an invitation to a user to join a specified team.

#### Enhancements (General Availability) <a href="#fixed-issues-general-availability-13" id="fixed-issues-general-availability-13"></a>

**Lists all teams API**

The [Lists all teams](https://developers.citrusad.com/partner/reference/listteams) API has been enhanced to support filtering by seller ID. You can now filter the team list using the seller ID.

#### Fixed Issues (General Availability) <a href="#fixed-issues-general-availability-14" id="fixed-issues-general-availability-14"></a>

**Upload the creative asset API**

Fixed an issue with the [Upload Creative Asset](https://developers.citrusad.com/partner/reference/uploadfile-2) API's file upload option. We have added a `file` body parameter to support the upload of creative assets.

**Reporting system**

Fixed an issue affecting both retailer and supplier product reports, where products were incorrectly displayed as deleted and incorrect product data retrieval occurred. This was addressed by ensuring proper handling of marketplace seller ID and product seller ID associations.

**Campaign editing in Citrus client**

Resolved an issue in the Citrus client where the **Scheduled start date** for **Always On** campaigns was incorrectly reset to today's date upon loading the **Campaign Setting** stage. The original date set is now retained and displayed correctly.

### April 2, 2025 <a href="#id-39.0-17" id="id-39.0-17"></a>

### New Features (General Availability) <a href="#new-features-general-availability-18" id="new-features-general-availability-18"></a>

#### Partner APIs <a href="#partner-apis-21" id="partner-apis-21"></a>

The following APIs are added:

* [Retrieve list of all campaign types](https://developers.citrusad.com/partner/reference/listcampaigns)
* [Update a team](https://developers.citrusad.com/partner/reference/updateteam-1)

#### Fixed Issues (General Availability) <a href="#fixed-issues-general-availability-15" id="fixed-issues-general-availability-15"></a>

**Update a wallet API**

The `name` is now an optional parameter in the [update a wallet](https://developers.citrusad.com/partner/reference/updatewallet-1) API. Only `id` is a mandatory field for this API.

**Create a banner API**

The [create a banner](https://developers.citrusad.com/partner/reference/createbannercampaign) API is updated to include an example for the `slotConfiguration` field.

### March 19, 2025 <a href="#id-39.0-18" id="id-39.0-18"></a>

### New Features (General Availability) <a href="#new-features-general-availability-19" id="new-features-general-availability-19"></a>

#### Partner APIs <a href="#partner-apis-22" id="partner-apis-22"></a>

The following APIs are added:

* [Retrieve list of content standards for Banner X campaigns](https://developers.citrusad.com/partner/reference/listbannerxcontentstandard)
* [Retrieve list of content standards for banner campaigns](https://developers.citrusad.com/partner/reference/listbannercontentstandard)
* [Update banner campaign](https://developers.citrusad.com/partner/reference/updatebannercampaign)

### Enhancements (General Availability) <a href="#enhancements-general-availability-10" id="enhancements-general-availability-10"></a>

#### Partner APIs <a href="#partner-apis-23" id="partner-apis-23"></a>

The following Team APIs are updated for the [Digital Services Act](https://developers.citrusad.com/integration/reference/digital-services-act) (DSA) support:

* [Create team](https://developers.citrusad.com/partner/reference/createteam-1)
* [Lists all teams](https://developers.citrusad.com/partner/reference/listteams-1)
* [Get team for specified id](https://developers.citrusad.com/partner/reference/getteam-1)

### Bug Fixes (General Availability) <a href="#bug-fixes-general-availability-9" id="bug-fixes-general-availability-9"></a>

#### Banner X APIs <a href="#banner-x-apis" id="banner-x-apis"></a>

We have updated the [Create a Banner X Campaign](https://developers.citrusad.com/partner/reference/createbannerxcampaign-1) `bannerXConfig` object requirements. The following fields are no longer mandatory, enhancing the flexibility of API interactions:

* `background_image_id`
* `secondary_background_image_id`
* `hero_image_id`
* `secondary_hero_image_id`

### March 10, 2025 <a href="#id-39.0-19" id="id-39.0-19"></a>

### New Features <a href="#new-features" id="new-features"></a>

#### Partner APIs (General availability) <a href="#partner-apis-general-availability" id="partner-apis-general-availability"></a>

The following APIs are added:

* [Update a wallet](https://developers.citrusad.com/partner/reference/updatewallet-1)
* [Update banner X campaign](https://developers.citrusad.com/partner/reference/updatebannerxcampaign)

### Enhancements: General Availability <a href="#enhancements-general-availability-11" id="enhancements-general-availability-11"></a>

The following APIs are enhanced to display the value of `currentBalance`, `availableBalance`, and `cappedAvailableBalance`:

* [Retrieve wallet by ID](https://developers.citrusad.com/partner/reference/getwallet-1)
* [Lists all wallets](https://developers.citrusad.com/partner/reference/listwallets-1)

### February 19, 2025 <a href="#id-39.0-20" id="id-39.0-20"></a>

### New Feature: General Availability <a href="#new-feature-general-availability" id="new-feature-general-availability"></a>

#### Partner APIs <a href="#campaign-search-term-length-validation-1" id="campaign-search-term-length-validation-1"></a>

The following banner campaigns, banner X campaigns, and creative assets APIs are added:

**Banner**

* [Create a banner campaign](https://developers.citrusad.com/partner/reference/createbannercampaign-1)
* [Get banner campaign details](https://developers.citrusad.com/partner/reference/getbannercampaign)
* [Update banner campaign approval state](https://developers.citrusad.com/partner/reference/approvebannercampaign)

**Banner X**

* [Create a banner X campaign](https://developers.citrusad.com/partner/reference/createbannerxcampaign)
* [Get banner X campaign details](https://developers.citrusad.com/partner/reference/getbannerxcampaigndetails)
* [Update banner X campaign approval state](https://developers.citrusad.com/partner/reference/approvebannerxcampaign)
* [Retrieve list of all banner X campaigns](https://developers.citrusad.com/partner/reference/listbannerxcampaigns-1)

**Creative assets**

* [Upload the creative asset](https://developers.citrusad.com/partner/reference/uploadfile-1)
* [Retrieve file URL](https://developers.citrusad.com/partner/reference/getcampaignfileurl)

**Retrieve campaigns**

* [Retrieve list of all campaign types](https://developers.citrusad.com/partner/reference/listcampaigns-1)

**Content standard**

* [Get banner X content standard details](https://developers.citrusad.com/partner/reference/getbannerxcontentstandard-1)
* [Get banner content standard details](https://developers.citrusad.com/partner/reference/getbannercontentstandard)

### October 31, 2024 <a href="#id-39.0-24" id="id-39.0-24"></a>

### Improvement: General Availability <a href="#improvement-general-availability" id="improvement-general-availability"></a>

#### Enhanced API Validation for Realized Ad IDs <a href="#enhanced-api-validation-for-realized-a-d-ids" id="enhanced-api-validation-for-realized-a-d-ids"></a>

This feature is not enabled by default and is currently controlled by a feature toggle. It will be enforced on the endpoint by March 30th, 2025. If you wish to activate it prior to that date, please contact your CitrusAd representative.

We've updated our API to enhance realized ad ID validation, ensuring data integrity and preventing invalid impressions. Requests with improperly encoded or incorrectly prefixed ad IDs will be rejected with a 400 error and an explanatory message.

**Example Error Message**

"Invalid ad ID. Must be properly encoded and prefixed with '`display_`', '`banner_`', or '`shotgun_`'."

**Key Benefits**

* **Faster Resolution**: Immediate feedback for retailers reduces investigation times and enhances operational efficiency.
* **Increased Accuracy**: Fewer invalid impressions lead to more accurate reporting and attribution.

For more information, see [Reporting Impressions and Clicks](https://developers.citrusad.com/integration/reference/reporting-impressions-clicks).

### Improvement: General Availability <a href="#improvement-general-availability-1" id="improvement-general-availability-1"></a>

#### Delete Products Using Seller ID from the Catalog <a href="#delete-products-using-seller-id-from-the-catalog" id="delete-products-using-seller-id-from-the-catalog"></a>

This feature is not enabled by default. To register your interest in this feature for your platform, please contact your CitrusAd representative or submit a support case so we can discuss the feature activation.

You can now delete products from your catalog by specifying a seller ID in the query parameter when the product includes it.

To delete a product with a seller ID, specify the seller ID as a query parameter:

```
DELETE $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE>?sellerId=abc123> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
```

For more information, see [Syncing products via API](https://citrusad-group.readme.io/integration/reference/syncing-products-via-api#deleting-products).

## 33.0: August 3, 2022

The 33.0 release introduces the /v3 endpoint into production!

This brings some updates to the `targeting` section of the `v3/product-campaigns/` endpoint, as well as the launch of our billing API.

## product-campaign

### General changes

* Retailers no longer need to send us the approval state when creating or updating a Product campaign through our API. This is now handled by internal business rules.
* We are introducing a new product campaign endpoint which will allow partner platforms to approve and reject campaigns
* We have a new v3 product campaign API introduced. We will ask partners to migrate to this new API but will keep our current v2 version available for a short period of time to allow for the migration.

### Targeting updates

33.0 brings some changes to how targeting works in the API. Instead of `targetedFilters` and `filterWhitelists`, there is now `includeFitlers` and `excludeFitlers`.

The structure of the exclude filters and include filters is the same as the old targetedFilters:

```
 {
    "targeting": {
        "excludeFilters": [
            {
                "catalogId": "string",
                "filter": "string"
            }
        ],
        "includeFilters": [
            {
                "catalogId": "string",
                "filter": "string"
            }
        ]
    }
}
```

If you are still using v2 to manage targeting, these will be internally updated to include/exclude filters, and then mapped backwards. Due to business rules, this means that `filterWhitelists` are mapped to the v3 exclude/include filters, and when they are round tripped back to v2, they appear as targeted filters.

#### Include and exclude filters

**includeFilters**

An include list that means Epsilon Retail Media will only consider these explicit filters for the fitler class. It doesn't matter what filters are against the product in the catalogue. This allows targeting to remain static, set at the time of campaign creation.

Used for:

* Fixed tenancy category campaigns
* All category cross-sell campaigns **(fixed tenancy support coming in a later release)**

**excludeFilters**

An exclude list that means Epsilon Retail Media will consider all filters except the stated explicit filters for the fitler class. This allows targeting to be dynamic and respect catalogue updates.

For example, if a product is served organically into a new category or location, the campaign will automatically appear there.

Used for:

Auction category campaigns

Auction campaigns with location targeting enabled

**Why change?**

This is a unification and re-building of our category and location targeting capabilities set to do what we expect it to do. An exclude list allows us to update live campaigns in line with catalog changes, as we only store what a campaign creator doesn’t want to target, so anything newly added to the product is automatically targeted.

**Can a campaign have both an include list and exclude list?**

No, this is not currently possible.

## Wallets API

The Wallets API will allow integrators to:

* Create new wallets
* Retrieve a list of wallets for a specific team
* Retrieve a specific wallet
* Retrieve a specific wallet’s balance
* Use a new endpoint for retailers to enable/disable a supplier team editing their wallet's monthly credit limit


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/release-notes/api-release-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.