Bulk Operations overview

Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view this page in the new Partner APIs space of our documentation.

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):

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:

{
  "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:

GET /v3/campaigns/bulk/status/c40f4f98-9b6b-11ee-b9d1-0242ac120002

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.

Bulk Operations Access Matrix

Operation	Method	Who Can Create	Who Can View Status
Campaigns
Create campaigns in bulk	POST	Admin, Primary Retailer, Supplier, General User	Admin, Primary Retailer, Creator (including Supplier)
Update campaigns in bulk	PATCH	Admin, Primary Retailer, Supplier, General User	Admin, Primary Retailer, Creator (including Supplier)
Update campaign approval state	POST	Admin, Primary Retailer	Admin, Primary Retailer
Retrieve bulk operation status	GET	—	Admin, Primary Retailer, Creator (including Supplier)
Wallet
Create wallets in bulk	POST	Admin, Primary Retailer, Supplier, General User	Admin, Primary Retailer, Creator (including Supplier)
Update wallets in bulk	PATCH	Admin, Primary Retailer, Supplier, General User	Admin, Primary Retailer, Creator (including Supplier)
Retrieve bulk wallet operation status	GET	—	Admin, Primary Retailer, Creator (including Supplier)
Team
Create teams in bulk	POST	Admin, Primary Retailer, Supplier, General User	Admin, Primary Retailer, Creator (including Supplier)
Update teams in bulk	PATCH	Admin, Primary Retailer, Supplier, General User	Admin, Primary Retailer, Creator (including Supplier)
Retrieve bulk team operation status	GET	—	Admin, Primary Retailer, Creator (including Supplier)

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.