Create/Update Campaign fields
Field definitions
It is important to ensure the fields are used correctly for your unique platform. A definition and explanation of each field is below.
| Field | Purpose | Example value |
|---|---|---|
name | The name of your campaign | Christmas 2020 Chocolate |
namespaceId | Specifies the unique identifier of your namespace. This is the namespace name in the base url | The namespaceID for exampleretailer.citrusad.com is "exampleretailer" |
approval.state | Specifies the approval state. This is overwritten by our internal logic and will likely be removed in a future revision. | APPROVAL_STATE_APPROVED |
approval.rejectionReason | Specifies reason a campaign has been rejected. This is overwritten by our internal logic and will likely be removed in a future revision. | This campaign cannot target "milk" |
campaignState | Specifies the active state of the campaign. Defines if it is active, paused, draft, or archived. | CAMPAIGN_STATE_ACTIVE |
teamId | The supplier team the campaign is for. | 38d8ed2f-899c-452c-b938-fe2bd512d49f |
startTime | Specifies when the campaign starts as a precise ISO-8601 timestamp. Omit this value for always on campaigns. | 2021-09-01T04:00:00.920Z |
endTime | Specifies when the campaign ends as a precise ISO-8601 timestamp. Must be sent if startTime is specified.Omit this value for always on campaigns. | 2021-09-02T04:00:00.920Z |
walletId | Specifies the supplier's wallet for the campaign to spend from. | 296bcea3-eafe-4d60-a1fb-2e8928561c31 |
placementId | Specifies the placement for the campaign | 329f1e08-d3ee-4e04-90c4-068b3ce6b856 |
catalogIds | Specifies the retailer catalog(s) that the campaign will advertise within. | ["329f1e08-d3ee-4e04-90c4-068b3ce6b856","6c29a96a-f55a-497f-b03a-2fed85dd7198" ] |
advertisedProducts.productsByKey | Specifies the product code and catalogId combinations being advertised in the campaign. For a campaign appearing in two catalogs, specify two catalog product pairings. | [{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}] |
advertisedProducts.productsByAttributes | Specifies product groups to be advertised and the price range of the products advertised. Most integrations can omit this, and use productByKey | {"tags": [ "shoes","mens"], "priceRange": {"min": "100","max": "250"}} |
targeting.searchTerms | Specifies the search terms that a campaign will target and their match type. Only send this for search placements. | {"matchType": "MATCH_TYPE_EXACT_MATCH","phrase": "string"} |
targeting.excludeFilters | Specifies filters to be excluded within CitrusAd's targeting stage. These must only be location or category filters in alignment with your filterClassId. Most integrations can omit these values. If using two filter classes, specify one object per filter class | {"excludeFilters": [ { "catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", "filter": "category:chocolate" }, { "catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", "filter": "location:florida" } ] } |
| targeting.includeFilters | Specifies explicit filters to be targeted by the campaign. Omit this for standard integrations. Only populate this field if advised or when creating fixed tenancy campaigns. | {"includeFilters": [ { "catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", "filter": "category:flavoured-milk" } ] } |
targeting.crossSell | Specifies targeting on cross-sell placements. Omitted for most placements. | See following examples. |
targeting.crossSell. targetProductsByKey | Specifies explicit catalog product pairings to be targeted. | [{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}] |
targeting.crossSell. targetProductsByAttributes | Specifies product groups to be targeted, as well as the vendor (brand) and the price range of the products targeted. | "targetProductsByAttributes": {"subclassTags": ["Laptops"],"vendorTags": ["HP"],"allTags": ["Laptops" ],"priceRange": {"min": "250","max": "1000"}} |
targeting.upSell. targetProductsByKey | Specifies explicit catalog product pairings to be targeted. | [{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}] |
targeting.crossSell. targetProductsByAttributes | Specifies product groups to be targeted, as well as the vendor (brand) and the price range of the products targeted. | "targetProductsByAttributes": {"subclassTags": ["Laptops"],"vendorTags": ["HP"],"allTags": ["Laptops" ],"priceRange": {"min": "250","max": "1000"}} |
strategy.auction.maxBid | Specifies the maximum CPC bid of your campaign. | 2.99 |
strategy.auction.spendLimit | Used to specify if a campaign has a maximum daily or total spend. Can be omitted for a campaign to be "always on" and spend if the campaign's wallet has funds. | "daily": "1000" |
strategy.fixedTenancy.cost | The total cost of the campaign. This value is not charged to the wallet and is used for reporting purposes. This value is mutable in updates if the retailer is optimising across an entire package/IO. | 1000.99 |
strategy.fixedTenancy.catalogCostPercentage | A value between 0-1 to represent how much of the cost should be allocated to each catalog. If you're using one catalog, send the catalog and 1. | 0.5 |
strategy.fixedTenancy.fixedCosts | Used to specify any external data, creative, or other cost incurred for servicing the campaign. This is charged when the campaign is first approved and cannot be edited. Omit this unless you are incurring additional costs to your advertiser. | { "dataCost": "150", "creativeCost": "200", "otherCost": "400" } |
customFields.customFieldId | Specifies the unique customFieldId being configured. Custom fields are not required in a standard integration and it is likely not to use this field unless advised by your Technical Account Manager. | { "customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122", "content": "PO-12345" } |
customFields.content | The content for the custom field on the campaign. | { "customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122", "content": "PO-12345" } |
customQuestions.customQuestionId | Specifies the unique custom targeting question being configured. Custom questions are not required in a standard integration and it is likely not to use this field unless advised by your Technical Account Manager. | { "answers": [ "preference:delivery", "preference:online" ],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426" } |
customQuestions.answers | Specifies the answers selected by advertisers for customer targeting. Must align with customer targetingData values. | { "answers": [ "preference:delivery", "preference:online" ],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426" } |
Updated over 1 year ago