--- title: /v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups slug: campaign-reporting-apis/v2advertisersadvertiseridcampaignscampaignidspaad-groups docTags: createdAt: 2026-03-25T10:57:30.256Z --- { "id": "vbp_je9dz1BSnewiVDgfR", "type": "api-oas-v2", "data": { "method": "POST", "url": "https:///v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups", "servers": [ { "url": "https:///v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups", "description": "Generated server url" } ], "name": "", "description": "

Creates a SPA ad group.

\n

The ad group can be only associated to publishers the user has access to, publishers being\nassociated to the advertiser of the ad group and publishers having a product feed\nin the market of the ad groups campaign.\nThe eligible values for publisherId can be retrieved from the API endpoint\nGET /v2/advertisers/{advertiserId}/eligible/publisher-markets.\nMake sure to pass the query string parameter marketId representing the market of\nthe ad groups campaign as well as adGroupType with value SPA.

\n

The ad group can only target sites available for the ad groups publisher and campaigns market.\nThe site must contain at least one SPA ad unit.\nFurthermore, the ad group can only target locations available in the site the ad group\nis targeting.\nThe eligible values for targetingSiteIds and targetingLocations can be retrieved from the\nAPI endpoint GET /v2/advertisers/{advertiserId}/eligible/site-locations.\nMake sure to pass the query string parameter adGroupType with value SPA.\nBy default, all eligible sites are targeted available at the time of the ad group\ncreation are targeted. The locations HOME_PAGE, CHECKOUT and EMAIL are not targeted by default.\nAll other available locations are targeted by default.

\n

Rules:

\n\n

Notes:

\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "advertiserId", "type": "integer", "description": "", "format": "int32" }, { "kind": "required", "name": "campaignId", "type": "integer", "description": "", "format": "int32" } ], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "", "customType": "SpaAdGroupCreateRequest", "schema": [ { "name": "publisherId", "kind": "required", "type": "integer", "description": "", "example": 0, "format": "int32" }, { "name": "name", "kind": "required", "type": "string", "description": "", "example": "", "minLength": 3, "maxLength": 200, "pattern": "^(?!\\s*$).+" }, { "name": "startDate", "kind": "required", "type": "string", "description": "", "example": "", "format": "date-time" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "", "example": "", "format": "date-time" }, { "name": "budget", "kind": "required", "type": "number", "description": "", "example": "" }, { "name": "dailyBudget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "weeklyBudget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "monthlyBudget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "useDynamicBudget", "kind": "optional", "type": "boolean", "description": "Whenever dynamic budget is activated daily limits are calculated in order that the remaining budget is evenly distributed over the ad group's lifetime.", "example": "" }, { "name": "dailySpendPacing", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "ASAP", "EVEN" ] }, { "name": "status", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "ADVERTISED", "ARCHIVED", "PAUSED" ] }, { "name": "targetedSiteIds", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "integer", "customType": "integer[]", "itemExample": "", "itemDefault": "" }, { "name": "targetedLocations", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/AdGroupTargetLocation", "customType": "AdGroupTargetLocation[]", "schema": [ { "name": "location", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "CATEGORY_PAGE", "SEARCH_PAGE", "HOME_PAGE", "PRODUCT_PAGE", "CHECKOUT", "MINI_SEARCH", "EMAIL", "EMAIL_ABANDONED_CART" ] }, { "name": "pagePosition", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "MAIN_GRID", "CAROUSEL", "BELOW_THE_FOLD", "ABOVE_THE_FOLD", "L1", "L2", "L3", "L4" ] } ] }, { "name": "bidOptimization", "kind": "required", "type": "string", "description": "The default value for bid optimization to be used for every ad within the ad group.\nBid optimization enables automated bidding: CONVERSIONS, BALANCED, and AWARENESS set the bid using the lower bound, midpoint, and upper bound of the suggested bid, respectively.\nMANUAL requires setting the bid explicitly.\n", "example": "", "enum": [ "MANUAL", "CONVERSIONS", "BALANCED", "AWARENESS" ] } ], "modelRef": "#/components/schemas/SpaAdGroupCreateRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [] }, "responses": [ { "statusCode": "200", "description": "OK", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "SpaAdGroupResponse", "schema": [ { "name": "id", "kind": "optional", "type": "integer", "description": "", "example": 0, "format": "int32" }, { "name": "publisher", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/PublisherWithGlobalFloorPriceResponse", "customType": "PublisherWithGlobalFloorPriceResponse", "schema": [ { "name": "id", "kind": "optional", "type": "integer", "description": "", "example": 0, "format": "int32" }, { "name": "name", "kind": "optional", "type": "string", "description": "", "example": "" }, { "name": "bidBelowGlobalFloorPrice", "kind": "optional", "type": "boolean", "description": "", "example": "" } ] }, { "name": "name", "kind": "optional", "type": "string", "description": "", "example": "" }, { "name": "type", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "DISPLAY", "SPA", "SPONSORED_BRAND" ] }, { "name": "status", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "ARCHIVED", "EXPIRED", "LIVE", "PAUSED", "SCHEDULED", "WAITING", "REJECTED" ] }, { "name": "budget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "budgetSpent", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "dailyBudget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "weeklyBudget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "monthlyBudget", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "useDynamicBudget", "kind": "optional", "type": "boolean", "description": "Whenever dynamic budget is activated daily limits are calculated in order that the remaining budget is evenly distributed over the ad group's lifetime.", "example": "" }, { "name": "dailySpendPacing", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "ASAP", "EVEN" ] }, { "name": "spendVelocity", "kind": "optional", "type": "number", "description": "The pacing of the ad group measures budget efficiency over time, where a value of 1.0 reflects ideal spend considering temporal progress of the ad group, less than 1.0 underspending, and more than 1.0 overspending. The value is not set whenever the ad group has no end date.", "example": "", "format": "double" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "", "example": "", "format": "date-time" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "", "example": "", "format": "date-time" }, { "name": "targetedSiteIds", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "integer", "customType": "integer[]", "itemExample": "", "itemDefault": "" }, { "name": "targetedLocations", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/AdGroupTargetLocation", "customType": "AdGroupTargetLocation[]", "schema": [ { "name": "location", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "CATEGORY_PAGE", "SEARCH_PAGE", "HOME_PAGE", "PRODUCT_PAGE", "CHECKOUT", "MINI_SEARCH", "EMAIL", "EMAIL_ABANDONED_CART" ] }, { "name": "pagePosition", "kind": "optional", "type": "string", "description": "", "example": "", "enum": [ "MAIN_GRID", "CAROUSEL", "BELOW_THE_FOLD", "ABOVE_THE_FOLD", "L1", "L2", "L3", "L4" ] } ] }, { "name": "advertised", "kind": "optional", "type": "boolean", "description": "", "example": "" }, { "name": "globalFloorPrice", "kind": "optional", "type": "number", "description": "", "example": "" }, { "name": "modifiedAt", "kind": "optional", "type": "string", "description": "", "example": "", "format": "date-time" } ], "modelRef": "#/components/schemas/SpaAdGroupResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "Unauthorized", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Forbidden", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "Not Found", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ExceptionResponse", "schema": [ { "name": "messages", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ExceptionResponse", "isExpanded": true } ] }, { "statusCode": "409", "description": "Conflict", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ExceptionResponse", "schema": [ { "name": "messages", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ExceptionResponse", "isExpanded": true } ] }, { "statusCode": "422", "description": "Unprocessable Entity", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ExceptionResponse", "schema": [ { "name": "messages", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ExceptionResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "lL4V4TFWw3mAFF4q3lsAG", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https:///v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"publisherId\": 0,\n \"name\": \"\",\n \"startDate\": \"\",\n \"budget\": \"\",\n \"bidOptimization\": \"\"\n }'" }, { "id": "7G5if3RVTB8bRK9tmfoeG", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"publisherId\": 0,\n \"name\": \"\",\n \"startDate\": \"\",\n \"budget\": \"\",\n \"bidOptimization\": \"\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https:///v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "6Re_LlF-O6Vsl0GZold5m", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https:///v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"publisherId\": 0,\n \"name\": \"\",\n \"startDate\": \"\",\n \"budget\": \"\",\n \"bidOptimization\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "Wjcu7_T1fzg2Ee33qgOoT", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https:///v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups\"\n\npayload = json.dumps({\n \"publisherId\": 0,\n \"name\": \"\",\n \"startDate\": \"\",\n \"budget\": \"\",\n \"bidOptimization\": \"\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "lL4V4TFWw3mAFF4q3lsAG" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// OK\n{\n \"id\": \"\",\n \"publisher\": {\n \"id\": \"\",\n \"name\": \"\",\n \"bidBelowGlobalFloorPrice\": false\n },\n \"name\": \"\",\n \"type\": \"\",\n \"status\": \"\",\n \"budget\": 0,\n \"budgetSpent\": 0,\n \"dailyBudget\": 0,\n \"weeklyBudget\": 0,\n \"monthlyBudget\": 0,\n \"useDynamicBudget\": false,\n \"dailySpendPacing\": \"\",\n \"spendVelocity\": \"\",\n \"startDate\": \"\",\n \"endDate\": \"\",\n \"targetedSiteIds\": [\n 0\n ],\n \"targetedLocations\": [\n {\n \"location\": \"\",\n \"pagePosition\": \"\"\n }\n ],\n \"advertised\": false,\n \"globalFloorPrice\": 0,\n \"modifiedAt\": \"\"\n}" }, { "id": "response-1-401", "language": "401", "code": "// Unauthorized\n" }, { "id": "response-2-403", "language": "403", "code": "// Forbidden\n" }, { "id": "response-3-404", "language": "404", "code": "// Not Found\n{\n \"messages\": [\n \"\"\n ]\n}" }, { "id": "response-4-409", "language": "409", "code": "// Conflict\n{\n \"messages\": [\n \"\"\n ]\n}" }, { "id": "response-5-422", "language": "422", "code": "// Unprocessable Entity\n{\n \"messages\": [\n \"\"\n ]\n}" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }