Create/Update Campaign

The Create/Update Campaign API is designed for creating or updating advertising campaigns within our platform. This functionality is crucial for launching new campaigns.

warning

It is important to handle campaign data securely and ensure that access is restricted to authorized users only.

API Endpoint

Method: POST

URL: https://<PA_RM_END_POINT>/retail-media/campaigns/supplier/{supplierId}/upsert-campaign

info

Please refer to the Supplier API documentation for detailed instructions on how to retrieve the supplierId.

Request Header

Name	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer ACCESS_TOKEN`

info

Please refer to the Authentication API documentation for bearer token.

Path Parameters

Parameter	Type	Description
`supplierId`	`string`	Get the supplier ID from the supplier API

Example Request Payload

{
    "retailerId": "xxxxxxxxxxxxxxxxxxxxxxxxx"
    "campaign": {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "Campaign Name",
        "startDate": "2025-02-19",
        "endDate": "2025-02-28",
        "totalBudget": 12.3,
        "dailyCap": 1
    },
    "adSets": [
      {
          "adSetInformation": {
              "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
              "name": "check",
              "placements": [
                {
                    "id": "898e5677-97e9-ef11-acff-06be30a1c1a7",
                    "slot": "",
                    "maxCost": 2,
                    "startDate": "2025-02-19",
                    "endDate": "2025-02-19"
                }
              ],
              "audienceSegment": ["age10", "advance"],
              "customerSegment": ["frequest buyer"]
          },
          "adSetCollection": {
              "collectionId": "guid", // Optional: Use existing collection
              "collection": { // Required if collectionId is not provided
                  "name": "string",
                  "productRefIds": ["string"]
              }
          },
          "bannerInformation": { // Optional
              "bannerId": "guid", // Optional: Required only for updates
              "banner": {
                  "name": "string",
                  "callToAction": "string",
                  "images": [
                      {
                          "deviceType": "string",
                          "url": "string"
                      }
                  ]
              }
          }
      }
    ]
}

Request Payload Explanation

Campaign Object

Parameter	Type	Required	Description
`id`	`GUID`		Id of the existing campaign. If is it provided existing campaing will be updated otherwise a new campaign will be created.
`name`	`string`	✅	Name of the campaign.
`startDate`	`string`	✅	The start date of the campaign in ISO format (YYYY-MM-DDTHH:mm:ssZ).Campaign start date time.
`endDate`	`string`		The end datetime of the campaign. Can be left empty (e.g., "") if the campaign does not have a predefined end date.
`totalBudget`	`decimal`	✅	The total budget allocated for the campaign.
`dailyCap`	`decimal`		Maximum daily spending limit for the campaign.If not set than dailyCap will be same as total budget.

AdSets Object

AdSets is an array of object, each object should have the details information to create the AdSet. It has three different object adSetInformation, adSetCollection and bannerInformation.

AdSetInformation Object

Parameter	Type	Required	Description
id	Guid	No	AdSet ID (required for updates)
name	string	✅	Name of the AdSet
placements	array	✅	List of placements
audienceSegment	array	No	List of audience segments
customerSegment	array	No	List of customer segment IDs

info

For a single adset each placement should have same strategy and adset type. Check Placement API for placement details.

Placement Object

Parameter	Type	Required	Description
`id`	`GUID`	✅	Unique identifier for the placement.
`slot`	`string`		The slot number that you want to target.
`maxCost`	`decimal`		Maximum cost for this placement. Should be greater than Placement cost.
`startDate`	`string`	✅ (If placement Strategy type is Fixed)	Start date for this placement in ISO format (YYYY-MM-DDTHH:mm:ss.sssZ)
`endDate`	`string`	✅ (If placement Strategy type is Fixed)	End date for this placement in ISO format (YYYY-MM-DDTHH:mm:ss.sssZ).

adSetCollection Object

Parameter	Type	Required	Description
`collectionId`	`GUID`		Unique identifier of the existing collection.
`collection`	object		Collection details (required if collectionId not provided)

info

If collection id is provided than System will be used that prebuild collection, if left empty than System will create a fixed collection using the product refIds (Need atleast one and each should be valid)and use that collection. If both is empty than the request will be invalidate and error will return.

Collection Object

Parameter	Type	Required	Description
name	string	Yes	Name of the collection
productRefIds	array	Yes	List of product reference IDs

bannerInformation Object

Parameter	Type	Required	Description
`bannerId`	`GUID`		Unique identifier of the existing banner.
`banner`	`Object`		Contains banner details.

banner Object

Parameter	Type	Required	Description
`name`	`GUID`		A human readable name for the banner.
`images`	`Object`		Image details.

BannerImage Object

Parameter	Type	Required	Description
deviceType	string	✅	Type of device (e.g., "Desktop", "Mobile")
url	string	✅	URL of the banner image

Response Payload

Success Response

Status Code: 200 OK
Payload: Returns the created campaign information in JSON format

{
    "status": "Success",
    "message": "Campaign saved successfully.",
    "errorCode": "",
    "data": "00000000-0000-0000-0000-000000000000", // ID of the created/updated campaign
    "metadata": {
        "requestId": "fd74722d-5926-4a8b-b259-d6a06cc16a58",
        "timestamp": "2025-06-10T06:53:27.5316006Z"
    }
}

Error Response

If an error occurs, the API will return an appropriate status code along with an error message.

Sample Error Response:

{
    "status": "Error"
    "errorCode": 401,
    "errors": ["error message 1", "error message 2"],
    "message": "Details error message",
    "metadata": {
        "requestId": "3d65d860-5acd-4663-b14d-c0bb55317660",
        "timeStamp": "2025-04-28T00:00:00.000Z"
    },
}

Example Usage (JavaScript)

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "BEARER YOUR_ACCESS_TOKEN");

const body = JSON.stringify(
  {
    "retailerId": "xxxxxxxxxxxxxxxxxxxxxxxxx"
    "campaign": {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "Campaign Name",
        "startDate": "2025-02-19",
        "endDate": "2025-02-28",
        "totalBudget": 12.3,
        "dailyCap": 1
    },
    "adSets": [
      {
          "adSetInformation": {
              "name": "check",
              "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
              "placements": [
                {
                    "id": "898e5677-97e9-ef11-acff-06be30a1c1a7",
                    "slot": "",
                    "maxCost": 2,
                    "startDate": "2025-02-19",
                    "endDate": "2025-02-19"
                }
              ],
              "audienceSegment": ["age10", "advance"]
          },
          "adSetCollection": {
            "collectionId": "GUID",
            "productRefId": ["XXX", "YYY", "ZZZ"]
          },
          "bannerInformation": {
            "bannerId": "GUID",
            "banner": {
                "name": "bannerName",
                "images": [
                  {
                      "deviceType": "Desktop",
                      "url": ""
                  },
                  {
                      "deviceType": "Tablet",
                      "url": ""
                  },
                  {
                      "deviceType": "Mobile",
                      "url": ""
                  }
                ]
            }
          }
      }
    ]
}
)

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: body
};

fetch("https://<PA_RM_END_POINT>/retail-media/campaigns/supplier/{supplierId}/upsert-campaign", requestOptions)
  .then(response => response.json())
  .then(result=> { 
    console.log(result);
  })
  .catch(error => console.log('error', error));

API Endpoint​

Request Header​

Path Parameters​

Example Request Payload​

Request Payload Explanation​

Campaign Object​

AdSets Object​

Response Payload​

Success Response​

Error Response​

Example Usage (JavaScript)​

API Endpoint

Request Header

Path Parameters

Example Request Payload

Request Payload Explanation

Campaign Object

AdSets Object

Response Payload

Success Response

Error Response

Example Usage (JavaScript)