> 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/partner/bulk-operation-api/bulk-operation-overview.md). # Bulk Operations overview ## 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](/retail-media-interface/partner/bulk-operation-api/bulkcampaignoperations/bulkcreatecampaign.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update campaigns in bulk](/retail-media-interface/partner/bulk-operation-api/bulkcampaignoperations/bulkupdatecampaign-1.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update campaign approval state](/retail-media-interface/partner/bulk-operation-api/bulkcampaignoperations/bulkcampaignapproval.md) | POST | Admin, Primary Retailer | Admin, Primary Retailer | | [Retrieve bulk operation status](/retail-media-interface/partner/bulk-operation-api/bulkcampaignoperations/bulkcampaignstatus-1.md) | GET | — | Admin, Primary Retailer, Creator (including Supplier) | | **Wallet** | | | | | [Create wallets in bulk](/retail-media-interface/partner/bulk-operation-api/bulkwalletoperations/bulkcreatewallet.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update wallets in bulk](/retail-media-interface/partner/bulk-operation-api/bulkwalletoperations/bulkupdatewallet.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Retrieve bulk wallet operation status](/retail-media-interface/partner/bulk-operation-api/bulkwalletoperations/bulkwalletstatus.md) | GET | — | Admin, Primary Retailer, Creator (including Supplier) | | **Team** | | | | | [Create teams in bulk](/retail-media-interface/partner/bulk-operation-api/bulkwalletoperations-1/bulkcreateteam.md) | POST | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Update teams in bulk](/retail-media-interface/partner/bulk-operation-api/bulkwalletoperations-1/bulkupdateteam.md) | PATCH | Admin, Primary Retailer, Supplier, General User | Admin, Primary Retailer, Creator (including Supplier) | | [Retrieve bulk team operation status](/retail-media-interface/partner/bulk-operation-api/bulkwalletoperations-1/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 %} --- # 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/partner/bulk-operation-api/bulk-operation-overview.md?ask=&goal= ``` `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.