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

Request 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"]
          },
          "adSetCollection": {
            "collectionId": "GUID",
            "productRefId": ["XXX", "YYY", "ZZZ"]
          },
          "bannerInformation": {
            "bannerId": "GUID",
            "banner": {
                "name": "bannerName",
                "images": [
                  {
                      "deviceType": "Desktop",
                      "url": ""
                  },
                  {
                      "deviceType": "Tablet",
                      "url": ""
                  },
                  {
                      "deviceType": "Mobile",
                      "url": ""
                  }
                ]
            }
          }
      }
    ]
}

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.

The adSetInformation object has four property id (if provided existing adset will be updated), name (name of the adset), placements which is a list of an object and audienceSegment an array of string. Check below for the details of the placement object.

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.
productRefId	Array of string		List of product reference IDs associated with the ad set.

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.

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.

Response Payload

Success Response

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

{
    "status": "success",
    "message": "Campaign created successfully",
    "campaignId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Error Response

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

• Sample Error Response (400 Bad Request):

{
  "errors": [
    "Error message 1",
    "Error message 2"
  ],
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "xxxxxxxxxxxxxxxxxxx"
}

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