> For the complete documentation index, see [llms.txt](https://developers.citrusad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.citrusad.com/partner/reference/bulk-operation-overview.md). # Bulk Operations overview {% hint style="info" %} Epsilon Retail Media's documentation is now centralized with our knowledgebase! For up to date guides, please view [this page](https://help.citrusad.com/retail-media-interface/partner/bulk-operation-api/bulk-operation-overview) in the new Partner APIs space of our documentation. {% endhint %} ## Bulk Campaigns The Bulk Action APIs are designed to help users such as AdOps, Managed Services, and Suppliers perform large-scale update and create operations to **campaign**, \*\*wallets \*\*and \*\*teams \*\*in a single API call. This ASync API approach streamlines workflows, reduces manual effort, and enhances operational efficiency. These APIs are especially valuable for high-volume scenarios like onboarding, seasonal launches, or major campaign adjustments, where making individual API calls would be time-consuming and error-prone. ### Key Benefits * Efficiency: Reduces the number of API calls and removes unnecessary manual steps by allowing multiple operations in a single request. * Performance: Bulk APIs minimize HTTP round‑trip overhead. Instead of sending many individual requests (for example, 100 separate calls), a single bulk request reduces network load and lowers the chances of hitting rate limits. * Idempotency: Ensures each operation in the bulk request is idempotent, preventing unintended side effects during retries (such as those triggered by UI actions). * Granular security and authorization model: Applies the correct access controls for each operation and entity type within the bulk payload, ensuring secure handling of all actions. * Audit and logging: Maintains proper logging and audit trails for all operations within a bulk request, ensuring traceability. * Preview capability: Some implementations support previewing changes before applying them, helping to catch errors early. * Transactional integrity: A bulk API allows clients to bundle a group of actions into a single API call, which can ensure that: * Each entity in the bulk request is independently validated. * Granular error messages are returned to identify which entities failed and why. * The entire operation is not blocked if one entity fails. ### How to Use Bulk Campaign APIs #### 1. Submit a Bulk Request You send a request to create, edit, or approve multiple campaigns at once. * For creating: `/v3/campaigns/bulk/create` * For editing: `/v3/campaigns/bulk/update` * For approvals: `/v3/campaigns/bulk/approve` Once you send the request, the system gives you a bulk ID and a status like `submitted`. The actual processing happens in the background. **Example (Update campaigns in bulk):** ```http PATCH /v3/campaigns/bulk/update { "campaigns": [ { "campaign": { "id": "campaign_123", "name": "Updated Summer Sale Campaign", "startTime": "2025-08-01T00:00:00Z", "endTime": "2025-08-31T23:59:59Z", "campaignState": "CAMPAIGN_STATE_ACTIVE", "strategy": { "auction": { "maxBid": "6.5" } } }, "mask": "name,startTime,endTime,campaignState,strategy.auction.maxBid", "campaignType": "CAMPAIGN_TYPE_BANNER" }, { "campaign": { "id": "campaign_456", "name": "Holiday Promotion", "campaignState": "CAMPAIGN_STATE_PAUSED", "strategy": { "auction": { "maxBid": "5.0" } } }, "mask": "name,campaignState,strategy.auction.maxBid", "campaignType": "CAMPAIGN_TYPE_BANNER" } ] } ``` **Response:** ```json { "bulkId": "c40f4f98-9b6b-11ee-b9d1-0242ac120002", "status": "BULK_OPERATION_SUBMITTED", "message": "Bulk campaign update request received and is being processed." } ``` #### 2. Check the Status Use the bulk ID to check progress at: `/v3/campaigns/bulk/status/{bulkId}` You'll see: * Which campaigns succeeded or failed, with details for each. * Error messages (if any). **Example:** ```http GET /v3/campaigns/bulk/status/c40f4f98-9b6b-11ee-b9d1-0242ac120002 ``` {% hint style="info" %} **Notes:** * The APIs are asynchronous: you submit a job and poll for results. * Each entity in the bulk request is validated independently; errors are reported per item. * Bulk APIs are available for campaigns, wallets, and teams, with similar patterns for each resource. {% endhint %} ### Bulk Operations Access Matrix | Operation | Method | Who Can Create | Who Can View Status | | ------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | ----------------------------------------------------- | | **Campaigns** | | | | | [Create campaigns in bulk](/partner/reference/bulkcreatecampaign.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update campaigns in bulk](/partner/reference/bulkupdatecampaign-1.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update campaign approval state](/partner/reference/bulkcampaignapproval.md) | POST | Admin, Primary Retailer | Admin, Primary Retailer | | [Retrieve bulk operation status](/partner/reference/bulkcampaignstatus-1.md) | GET | — | Admin, Primary Retailer, Creator (including Supplier) | | **Wallet** | | | | | [Create wallets in bulk](/partner/reference/bulkcreatewallet.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update wallets in bulk](/partner/reference/bulkupdatewallet.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Retrieve bulk wallet operation status](/partner/reference/bulkwalletstatus.md) | GET | — | Admin, Primary Retailer, Creator (including Supplier) | | **Team** | | | | | [Create teams in bulk](/partner/reference/bulkcreateteam.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update teams in bulk](/partner/reference/bulkupdateteam.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Retrieve bulk team operation status](/partner/reference/bulkteamstatus.md) | GET | — | Admin, Primary Retailer, Creator (including Supplier) | {% hint style="info" %} Create and Update team in bulk: When a supplier attempts to update records in bulk, the API allows a maximum of 50 records per request. If the request contains more than 50 records, the API returns an error message indicating that the limit has been exceeded. {% endhint %}