Retail campaigns

The various methods for Campaign Settings are listed below:

Clone template campaign (create retail campaign)

Creates a new retail campaign by cloning from a template campaign. Requires Campaigns_Clone permission.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account

Parameters

Parsed via parseJson[CampaignCloneRequestRMA]. Mandatory fields will throw a ValidationException if missing.

Field	Data Type	Requirement	Description
templateCampaignIdx	integer	Mandatory	Index of the template campaign to clone from.
retailCampaignName	string	Mandatory	Name for the new retail campaign.
email	string	Mandatory	Email address for notifications.
labelId	integer	Mandatory	Label ID to associate with the campaign.
assetSourceType	enum (string)	Mandatory	Asset source type. Values: `productFeed`, `uploadAsset`, `hybridAsset`
mediaChannelIdx	integer	Mandatory	Index of the media channel to use.
isDaVinciCreated	integer	Optional	Flag indicating whether the campaign was created via Da Vinci.
dspCampaignInfo	object (JSON string)	Optional	DSP campaign configuration object (serialized as JSON string).
dspAdditionalCampaignInfo	object	Optional	Additional DSP campaign info. See `DSPAdditionalCampaignInfo` below.
adServerId	string	Optional	ID of the ad server to use.
templateCampaignName	string	Optional	Name of the source template campaign.
faceCardAsset	string	Optional	Asset identifier for the face card.
faceCardAssetDimension	string	Optional	Dimension string for the face card asset (e.g. `300x250`).
inventoryType	enum (string)	Optional	Inventory type. Values: `offsite`, `onsite`
retailerId	integer	Optional	ID of the retailer.
landingUrl	string	Optional	Landing URL for the campaign.
agenticInfo	object	Optional	Agentic campaign info. See `CampaignAgenticInfo` below.

dspAdditionalCampaignInfo object (DSPAdditionalCampaignInfo)

Field	Data Type	Description
countryCode	string	Country code (e.g. `US`).
domain	string	Domain for the DSP campaign.
campaignType	enum (string)	DSP campaign type. Values: `Third_Party_Tags`, `Responsive_E_Commerce`, `Standard_Display_Creatives`, `Criteo_Creative_Generation`
amzSourceCampaignId	string	Amazon source campaign ID (default: `-1`).
isAdGroupCloned	boolean	Whether ad groups were cloned (default: `false`).
criteoAttributeAssetSourceMappings	array	List of Criteo attribute-to-asset-source mappings.

agenticInfo object (CampaignAgenticInfo)

Field	Data Type	Description
adIdx	integer	Index of the ad unit.
adUnitAssetPropertyMap	array	List of ad unit to asset property mappings.
adUnitAssetPropertyMap[].adUnitIdx	integer	Index of the ad unit.
adUnitAssetPropertyMap[].assetProperty	string	Asset property name.
ctaText	string	Call-to-action text for the campaign.
llmProvider	string	LLM provider name for agentic generation.

Sample Request

HTTP
    
 
POST https://jivoxapis.api.jivox.com/v2/accounts/:accountId/retail-campaigns
Copy

Request Body

JSON
    
 
{  "templateCampaignIdx": 81174,  "retailCampaignName": "Summer Promo 2025",  "email": "user@example.com",  "labelId": 12,  "assetSourceType": "productFeed",  "mediaChannelIdx": 101,  "inventoryType": "onsite",  "retailerId": 42,  "landingUrl": "https://example.com/summer",  "dspAdditionalCampaignInfo": {    "countryCode": "US",    "domain": "example.com",    "campaignType": "Responsive_E_Commerce",    "amzSourceCampaignId": "-1",    "isAdGroupCloned": false  }}
Copy

Response

Returns a CloneTemplateResponse JSON object.

Field	Data Type	Description
message	string	Success message.
retailCampaignIdx	integer	Index of the newly created retail campaign.

Request Body

JSON
    
 
{  "message": "Retail campaign created successfully",  "retailCampaignIdx": 98765}
Copy

Update retail campaign

Updates an existing retail campaign. Uses the same CampaignCloneRequestRMA request body as the clone operation. Requires Campaigns_Create permission.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignIdx	integer	Mandatory	path	Index of the retail campaign to update.

Parameters

Same structure as the Clone template campaign. All mandatory fields should be present; optional fields, if provided, are updated.

Field	Data Type	Requirement	Description
templateCampaignIdx	integer	Mandatory	Index of the source template campaign.
retailCampaignName	string	Mandatory	Updated name for the retail campaign.
email	string	Mandatory	Email address for notifications.
labelId	integer	Mandatory	Label ID to associate with the campaign.
assetSourceType	enum (string)	Mandatory	Asset source type. Values: `productFeed`, `uploadAsset`, `hybridAsset`
mediaChannelIdx	integer	Mandatory	Index of the media channel to use.
isDaVinciCreated	integer	Optional	Flag indicating whether the campaign was created via DaVinci.
dspCampaignInfo	object (JSON string)	Optional	DSP campaign configuration object.
dspAdditionalCampaignInfo	object	Optional	Additional DSP campaign info (see `DSPAdditionalCampaignInfo`).
adServerId	string	Optional	ID of the ad server to use.
templateCampaignName	string	Optional	Name of the source template campaign.
faceCardAsset	string	Optional	Asset identifier for the face card.
faceCardAssetDimension	string	Optional	Dimension string for the face card asset (e.g. `300x250`).
inventoryType	enum (string)	Optional	Inventory type. Values: `offsite`, `onsite`
retailerId	integer	Optional	ID of the retailer.
landingUrl	string	Optional	Landing URL for the campaign.
agenticInfo	object	Optional	Agentic campaign info (see `CampaignAgenticInfo`).

Sample Request

HTTP
    
 
PUT http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignIdx
Copy

Response

Returns an UpdateRetailCampaignResponse JSON object.

Field	Data Type	Description
msg	string	Result message describing the outcome of the update.
cloneId	string/null	Clone ID if a background clone was triggered.
messageId	string/null	Message/task ID for async processing, if applicable.

Request Body

JSON
    
 
{  "msg": "Retail campaign updated successfully",  "cloneId": null,  "messageId": null}
Copy

Delete retail campaign

Deletes an existing retail campaign. Requires Campaigns_Create permission.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignIdx	string	Mandatory	path	Index of the retail campaign to delete.

Parameters

None.

Sample Request

HTTP
    
 
DELETE http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignIdx
Copy

Response

Returns a fixed JSON confirmation message.

Field	Data Type	Description
message	string	Deletion confirmation.

Request Body

JSON
    
 
{  "message": "Retail Campaign deleted successfully"}
Copy

Get retail campaigns

Returns a paginated list of retail campaigns for the account. Requires Campaigns_List permission.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.

Query Parameters

Name	Data Type	Requirement	Parameter Type	Description
offset	integer	Optional	query	Pagination offset (e.g. 0).
limit	integer	Optional	query	Number of items per page (e.g. 25).

Sample Request

HTTP
    
 
GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns
Copy

Response

Returns a paginated JSON object with a campaigns array. Each item is a RetailCampaignMediaPlanMap serialized via Jackson.

Field	Data Type	Description
campaigns	array	List of retail campaign objects.
campaigns[].retailCampaignName	string/null	Name of the retail campaign.
campaigns[].retailCampaignIdx	integer/null	Index of the retail campaign.
campaigns[].mediaPlanName	string/null	Name of the associated media plan.
campaigns[].mediaPlanId	integer/null	ID of the associated media plan.
campaigns[].mediaChannelIdx	integer/null	Index of the media channel.
campaigns[].mediaChannelName	string/null	Name of the media channel.
campaigns[].dspLogoURL	string/null	Logo URL of the DSP.
campaigns[].status	enum (string)	Status of the retail media plan (e.g. `Active`, `Inactive`).
campaigns[].campaignIdx	integer/null	Index of the associated campaign.
campaigns[].dspCampaignId	string/null	DSP campaign ID.
campaigns[].creationDate	string/null	Creation date of the campaign.
campaigns[].modifiedDate	string/null	Last modified date.
campaigns[].dcmCampaignId	integer/null	DCM campaign ID, if applicable.
campaigns[].isDCMAdvertiserMappingExists	boolean/null	Whether a DCM advertiser mapping exists.
campaigns[].retailDSPCampaign	object/null	DSP campaign details (see `RetailDSPCampaign` in Get retail campaign by ID).
campaigns[].activationConfiguration	object/null	Activation configuration for the campaign.
campaigns[].activationConfiguration.tagGeneration	boolean	Whether tag generation is enabled.
campaigns[].activationConfiguration.creativeGeneration	boolean	Whether creative generation is enabled.
campaigns[].assetGenerationType	enum (string)	Asset generation type.
campaigns[].isRunningOrApproved	boolean/null	Whether the campaign is currently running or approved.
campaigns[].isMetaIntegrated	boolean/null	Whether the campaign is integrated with Meta.
count	integer	Total number of matching campaigns.
next	string/null	URL for the next page of results.
previous	string/null	URL for the previous page of results.

Request Body

JSON
    
 
{  "campaigns": [    {      "retailCampaignName": "Summer Promo 2025",      "retailCampaignIdx": 98765,      "mediaPlanName": "Summer Media Plan",      "mediaPlanId": 1023,      "mediaChannelIdx": 101,      "mediaChannelName": "Walmart DSP",      "dspLogoURL": "https://cdn.example.com/logos/walmart.png",      "status": "Active",      "campaignIdx": 4321,      "dspCampaignId": "dsp-001",      "creationDate": "2025-06-01",      "modifiedDate": "2025-06-10",      "dcmCampaignId": null,      "isDCMAdvertiserMappingExists": false,      "retailDSPCampaign": null,      "activationConfiguration": {        "tagGeneration": true,        "creativeGeneration": false      },      "assetGenerationType": "productFeed",      "isRunningOrApproved": true,      "isMetaIntegrated": false    }  ],  "count": 1,  "next": null,  "previous": null}
Copy

Get retail campaign by ID

Returns the details of a single retail campaign by its index. Requires Campaigns_View permission.

Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignIdx	integer	Mandatory	path	Index of the retail campaign to fetch.

Query Parameters

Name	Data Type	Requirement	Parameter Type	Description
offset	integer	Optional	query	Pagination offset
limit	integer	Optional	query	Number of items per page

Sample Request

HTTP
    
 
GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignIdx
Copy

Response

Returns a single RetailCampaign JSON object serialized via the explicit retailCampaignFmt writer.

Field	Data Type	Description
retailCampaignName	string/null	Name of the retail campaign.
retailCampaignIdx	integer/null	Index of the retail campaign
mediaPlanIdx	integer/null	Index of the associated media plan.
labelId	integer/null	Label ID associated with the campaign.
templateCampaignIdx	integer/null	Index of the source template campaign.
campaignIdx	integer/null	Index of the associated campaign.
cloneIdx	string/null	Clone index identifier.
assetSourceType	string/null	Asset source type. Values: `productFeed`, `uploadAsset`, `hybridAsset`
adIdx	integer/null	Index of the ad unit.
numOfCards	integer/null	Number of cards in the creative.
availableDimensions	array of string	List of available ad dimensions (e.g. `["300x250", "728x90"]`).
isVideoCampaign	boolean/null	Whether the campaign is a video campaign.
isSocialCampaign	boolean/null	Whether the campaign is a social campaign.
isDCMMediaPlanUsed	boolean/null	Whether a DCM media plan is used.
isDCMAdvertiserMappingExists	boolean/null	Whether a DCM advertiser mapping exists.
assetGenerationType	string/null	Asset generation type.
mediaChannel	object/null	Media channel mapping details.
retailDSPCampaign	object/null	DSP campaign details (see `RetailDSPCampaign` below).
isAnimatedImageSupported	boolean/null	Whether animated images are supported.
status	string/null	Status of the retail campaign
landingUrl	string/null	Landing URL for the campaign
dcmCampaignId	integer/null	DCM campaign ID, if applicable.
templateCampaignName	string/null	Name of the source template campaign.
faceCardAsset	string/null	Face card asset identifier.
faceCardAssetDimension	string/null	Dimension string for the face card asset.
faceCardAssetHtml	string/null	HTML content of the face card asset.
inventoryType	string/null	Inventory type. Values: `offsite`, `onsite`
retailerId	integer/null	Retailer ID.
ctaText	string/null	Call-to-action text.

retailDSPCampaign object (RetailDSPCampaign)

Field	Data Type	Description
rowIdx	integer/null	Row index.
retailCampaignId	integer/null	Retail campaign ID.
dspCampaignId	string/null	DSP campaign ID.
adServerId	string/null	Ad server ID.
isDaVinciCreated	boolean/null	Whether created via DaVinci.
createdTime	string/null	Creation timestamp.
dspAdditionalCampaignInfo	object/null	Additional DSP info (see `DSPAdditionalCampaignInfo`).

Request Body

JSON
    
 
{  "retailCampaignName": "Summer Promo 2025",  "retailCampaignIdx": 98765,  "mediaPlanIdx": 1023,  "labelId": 12,  "templateCampaignIdx": 81174,  "campaignIdx": 4321,  "cloneIdx": null,  "assetSourceType": "productFeed",  "adIdx": 55,  "numOfCards": 3,  "availableDimensions": ["300x250", "728x90"],  "isVideoCampaign": false,  "isSocialCampaign": false,  "isDCMMediaPlanUsed": false,  "isDCMAdvertiserMappingExists": false,  "assetGenerationType": "productFeed",  "mediaChannel": null,  "retailDSPCampaign": {    "rowIdx": 1,    "retailCampaignId": 98765,    "dspCampaignId": "dsp-001",    "adServerId": "walmart-dsp-001",    "isDaVinciCreated": false,    "createdTime": "2025-06-01T10:00:00Z",    "dspAdditionalCampaignInfo": null  },  "isAnimatedImageSupported": true,  "status": "Active",  "landingUrl": "https://example.com/summer",  "dcmCampaignId": null,  "templateCampaignName": "Summer Template",  "faceCardAsset": null,  "faceCardAssetDimension": null,  "faceCardAssetHtml": null,  "inventoryType": "onsite",  "retailerId": 42,  "ctaText": "Shop Now"}
Copy

Clones an existing campaign from a source account to a destination account. This is a general-purpose campaign clone pipeline — not specific to RMA template cloning. Triggers an async clone via SQS. Requires Campaigns_Clone permission on both source and destination accounts.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the source account.
destAccountId	string	Mandatory	path	ID of the destination account. Needs to be same as `accountId`

Parameters

Parsed via `parseJson[CloneRequest].srcAccountId,destAccountId`, and `mode` are **set server-side** from path parameters — they do not need to be in the request body.

Field	Data Type	Requirement	Description
cloneObject	enum (string)	Mandatory	Type of object being cloned. For campaigns: `Campaign`
srcAdvertiserId	integer	Mandatory	Advertiser ID of the source account.
destAdvertiserId	integer	Mandatory	Advertiser ID of the destination account.
cloneObjectId	integer	Mandatory	ID of the campaign to clone.
email	string	Mandatory	Email address for notifications on completion.

Sample Request

HTTP
    
 
POST https://jivoxapis.api.jivox.com/v2/accounts/:accountId/dest-account/:destAccountId/campaigns/clone
Copy

Request Body

JSON
    
 
{  "cloneObject": "Campaign",  "srcAdvertiserId": 16696,  "destAdvertiserId": 16696,  "cloneObjectId": 81250,  "email": "user@example.com"}
Copy

Response

Returns a CloneResponse JSON object. The clone itself is processed asynchronously.

Field	Data Type	Description
messageId	string	SQS message ID for the async clone job.
cloneId	string	UUID generated for this clone request (for status tracking).

Request Body

JSON
    
 
{  "messageId": "sqs-msg-abc123",  "cloneId": "550e8400-e29b-41d4-a716-446655440000"}
Copy

Get campaign creation status

Returns the clone/creation status of a retail campaign. Useful for polling progress after triggering a clone. Requires Campaigns_Clone permission.

Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignIdx	integer	Mandatory	path	Index of the retail campaign to check status for.

Sample Request

HTTP
    
 
GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignIdx/creation-status
Copy

Response

Returns a GetCloneStatusResponse JSON object serialized via Jackson.

Field	Data Type	Description
clonePercentCompleted	integer	Percentage of clone completion (0–100).
cloneStatus	enum (string)	Current status of the clone. Values: `Queued`, `Completed`, `Failed`

Request Body

JSON
    
 
{  "clonePercentCompleted": 75,  "cloneStatus": "Queued"}
Copy

Fetch Templates by Label (Prospecting, Retargeting, Full-Funnel)

This will fetch campaigns by label/category.

Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the advertiser account created on the platform.

Sample Request

HTTP
    
 
GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/rma/campaigns?ids=<labelId>
Copy

Sample Response

JSON
    
{  "campaigns": [    {      "campaignId": 123,      "campaignName": "Campaign 1",      "description": "lorem ipsum",      "numOfCards" : 3,      "previewTag":         {      "adUnitCombination": {        "bDim": "300x600"      },      "tag": `<script type="text/javascript" src="https://as.jivox.com/unit/unit_renderer.php?bDim=600x250&ap_cgName=Pampers_300x250&isPreviewRequest=1&cId=102&bUnitId=2000"></script>`        }    },    {      "campaignId": 234,      "campaignName": "Campaign 2",      "description": "lorem ipsum",      "numOfCards" : 1,      "previewTag":         {      "adUnitCombination": {        "bDim": "300x600"      },      "tag": `<script type="text/javascript" src="https://as.jivox.com/unit/unit_renderer.php?bDim=600x250&ap_cgName=Pampers_300x250&isPreviewRequest=1&cId=102&bUnitId=2000"></script>`        }    }  ]}
Copy

Save Campaign

Create retail media campaign from the template - (to clarify against confluence doc "Save Campaign" versus google sheet Campaign -> CREATE -> POST).

Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the advertiser account created on the platform.

Sample Request

HTTP
    
 
POST http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaign
Copy

The Parameter:

accountId - is the Current account Id.

Request Body

JSON
    
 
{  "templateCampaignIdx": 1234,  "retailCampaignName": "Campaign1",  "email": "abc@jivox.com",  "labelId": 789}
Copy

Sample Response

JSON
    
 
{  "messageId": "cloneMessageId",  "retailCampaignIdx": 1234}
Copy

Last updated on

Was this page helpful?