Skip to main content
광고 그룹은 광고 캠페인 안에 위치하며 광고의 게재를 제어합니다. 광고의 오디언스, 일정, 예산을 설정합니다. Ad Groups API를 사용하면 캠페인에 광고 그룹을 생성하고, 타기팅 및 게재 설정을 나열하거나 조회하고, 예산이나 타기팅을 업데이트하고, 더 이상 게재하지 않을 그룹을 삭제하고, 게재를 일시 중지하거나 재개할 수 있습니다.

엔드포인트

타기팅 제한

광고 그룹은 광고 가이드에 나열된 국가를 타기팅할 수 없습니다. 광고 그룹을 생성하거나 타기팅 국가를 업데이트하는 요청에서 regions.include.countries에 차단된 국가가 포함되면 요청이 거부됩니다.

속성

string
필수
adgrp_ 접두사가 붙은 광고 그룹의 고유 식별자입니다.
object
필수
이 광고 그룹이 속한 광고 캠페인입니다.

속성

string
필수
참조된 엔터티의 ID입니다.
number
필수
장바구니 담기 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 장바구니 담기 이벤트 수(라스트 클릭 기준)입니다.
object
필수
이 광고 그룹이 게재 대상으로 하거나 제외하는 저장된 오디언스입니다.

속성

string[]
필수
게재에서 제외되는 저장된 오디언스의 ID이며, adaud_ 접두사가 붙습니다.
string[]
필수
광고 그룹이 게재 대상으로 하는 저장된 오디언스의 ID이며, adaud_ 접두사가 붙습니다.
string | null
필수
광고 경매에서 게재 입찰가를 설정하는 방식입니다. 목표 기반 전략은 desired_cost_per_result를 사용합니다.사용 가능한 옵션: minimum_cost, average_target, maximum_target
number | null
필수
이 광고 그룹의 예산(USD)으로, 예산이 저장되고 청구되는 통화입니다. 대신 캠페인에 예산이 설정되어 있으면 null입니다.
number | null
필수
계정의 광고 보고 통화로 표시하기 위해 오늘 환율로 budget_currency로 나타낸 동일한 예산입니다. budget_amount가 null이면 null입니다.
string
필수
budget_amount_local의 ISO 4217 코드로, 계정의 ads_reporting_currency 설정입니다. 계정이 변경하지 않았다면 usd입니다.
string | null
필수
budget_amount를 하루 단위로 지출하는지(daily), 광고 그룹 전체 기간에 걸쳐 지출하는지(lifetime) 여부입니다. lifetime 광고 그룹에는 시작 시점으로부터 최소 24시간 이후인 ends_at도 필요합니다.사용 가능한 옵션: daily, lifetime
number
필수
클릭 수를 노출 수로 나눈 값으로, 0과 1 사이입니다.
number
필수
클릭 수입니다.
number
필수
등록 완료 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 등록 완료 이벤트 수(라스트 클릭 기준)입니다.
number
필수
문의 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 문의 이벤트 수(라스트 클릭 기준)입니다.
string | null
필수
최적화 대상 픽셀 이벤트입니다. 표준 이벤트 또는 임의의 맞춤 픽셀 이벤트 이름입니다.
number | null
필수
지출을 귀속된 장바구니 담기 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.
number
필수
지출을 클릭 수로 나눈 값입니다. 클릭이 없으면 0입니다.
number | null
필수
지출을 귀속된 등록 완료 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.
number | null
필수
지출을 귀속된 문의 이벤트 수로 나눈 값입니다. 문의가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.
number | null
필수
지출을 귀속된 리드 수로 나눈 값입니다. 리드가 목표가 아니고 귀속된 리드가 없으면 null입니다.
number
필수
노출 1,000회당 지출입니다. 노출이 없으면 0입니다.
number | null
필수
지출을 귀속된 구매 수로 나눈 값입니다. 구매가 목표가 아니고 귀속된 구매가 없으면 null입니다.
number | null
필수
지출을 Whop 픽셀에 귀속된 결과 수로 나눈 값입니다. Whop에 귀속될 수 있는 항목을 최적화하지 않으면 null입니다.
number | null
필수
지출을 귀속된 일정 예약 이벤트 수로 나눈 값입니다. 일정 예약이 목표가 아니고 귀속된 이벤트가 없으면 null입니다.
number | null
필수
지출을 귀속된 신청서 제출 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.
number | null
필수
지출을 고유 클릭 수로 나눈 값입니다. 고유 클릭이 없으면 null입니다.
number | null
필수
지출을 귀속된 콘텐츠 조회 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.
string
필수
광고 그룹이 생성된 시각(ISO 8601 타임스탬프)입니다.
number
필수
모든 맞춤 이벤트 이름에 걸쳐 Whop 픽셀에 귀속된 맞춤(판매자 정의) 전환 이벤트 수(라스트 클릭 기준)입니다.
object
필수
Whop 픽셀에 귀속된 맞춤 전환으로, 이벤트 이름을 키로, 라스트 클릭 기준 횟수를 값으로 가집니다. 귀속된 이름 있는 맞춤 이벤트가 없으면 비어 있습니다. 이름 없이 발생한 맞춤 이벤트는 custom_conversions에는 집계되지만 여기서는 제외되므로, 이 값들의 합은 최대 custom_conversions입니다.
object
필수
custom_event_counts와 마찬가지로 이벤트 이름을 키로 하여 각 맞춤 이벤트에 귀속된 전환 가치입니다. whop.track에 전달된 값을 USD로 정규화해 합산하며, 값 없이 발생한 이벤트는 0으로 계산됩니다.
object | null
필수
요일을 키로 하여 광고 그룹이 매주 게재되는 시간입니다. 게재하지 않는 요일은 생략됩니다. 모든 시간에 게재하면 null입니다. 일부 플랫폼에서는 일정을 사용하려면 광고 그룹에, 또는 캠페인이 예산을 보유한 경우 캠페인에 lifetime budget_type이 필요합니다.

속성

object[]
광고 그룹이 금요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
object[]
광고 그룹이 월요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
object[]
광고 그룹이 토요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
object[]
광고 그룹이 일요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
object[]
광고 그룹이 목요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
object[]
광고 그룹이 화요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
object[]
광고 그룹이 수요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.

속성

string
필수
게재가 종료되는 시각으로, 24시간제 HH:00 형식이며 자정은 최대 24:00입니다. start보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
string
필수
게재가 시작되는 시각으로, 00:00부터 23:00까지의 24시간제 HH:00 형식입니다.
string
필수
이 광고 그룹의 광고가 현재 게재 중인지 여부와, 게재 중이 아니라면 그 이유입니다. 여러 상태가 동시에 해당하면 우선순위가 가장 높은 상태가 반환됩니다.사용 가능한 옵션: all_ads_rejected, rejected, draft, campaign_paused, paused, in_review, processing, revise_content, issues, scheduled, completed, learning, active
object
필수
연령, 성별 및 자동 오디언스 타기팅입니다.

속성

boolean
필수
자동 오디언스 타기팅 사용 여부입니다. true이면 설정한 연령과 성별을 제안으로 취급해, 그 범위를 넘어서까지 게재될 수 있습니다.
string
필수
타기팅하는 성별입니다.사용 가능한 옵션: all, male, female
number | null
필수
타기팅하는 최고 연령입니다. 최댓값이 설정되지 않으면 null입니다.
number | null
필수
타기팅하는 최저 연령입니다. 최솟값이 설정되지 않으면 null입니다.
number | null
필수
목표로 하는(average_target) 또는 절대 초과하지 않을(maximum_target) 결과당 비용입니다. minimum_cost 입찰에서는 null입니다.
object
필수
타기팅하는 기기 플랫폼과 운영 체제입니다.

속성

object[]
필수
타기팅하는 운영 체제입니다. 비어 있으면 모든 운영 체제를 타기팅합니다.

속성

string
타기팅하는 최저 OS 버전으로, 18.0 등입니다. 모든 버전이 해당하면 없습니다.
string
필수
타기팅하는 운영 체제입니다.사용 가능한 옵션: ios, android
string[]
필수
타기팅하는 기기 유형입니다. 비어 있으면 모든 기기를 타기팅합니다.사용 가능한 옵션: mobile, desktop
string | null
필수
광고 그룹 게재가 종료되는 시각(ISO 8601 타임스탬프)입니다. 일시 중지할 때까지 게재되면 null입니다.
number | null
필수
노출 수를 도달 수로 나눈 값입니다.
number
필수
노출 수입니다.
object[]
필수
이 광고 그룹과 그 광고에 영향을 주는 미해결 이슈입니다. 없으면 비어 있습니다.

속성

string
필수
이슈의 고유 식별자입니다.
string
필수
이슈의 종류입니다. 게재에 관한 정보, 경고 또는 조치가 필요한 오류 중 하나입니다.사용 가능한 옵션: information, warning, error
string
필수
이슈의 내용과 해결 방법에 대한 설명입니다.
string | null
필수
이슈가 연결된 캠페인, 광고 그룹 또는 광고의 ID입니다.
string
필수
이슈가 연결된 리소스의 유형입니다.사용 가능한 옵션: ad_campaign, ad_group, ad
string
필수
크리에이터에게 표시되는 이슈의 짧은 제목입니다. 콘텐츠 검토 거부 시 지목된 규칙 또는 일반 레이블입니다.
object[]
이 광고 그룹의 광고가 표시될 수 있는 검색어와 절대 표시되지 않는 검색어입니다. 검색 캠페인 전용이며, 게재 시작 전에 각 광고 그룹에 최소 하나가 필요합니다.

속성

string
필수
검색어가 얼마나 정확히 일치해야 하는지입니다. broad는 관련 검색에도 도달하고, phrase는 구문의 의미가 포함되어야 하며, exact는 검색어와 의미가 같아야 합니다. 기본값은 broad입니다.사용 가능한 옵션: broad, phrase, exact
boolean
필수
이 검색어가 광고를 노출 대상으로 만드는 대신 광고가 표시되지 않도록 하는지 여부입니다. 기본값은 false입니다.
string
필수
검색어로, 최대 80자, 10단어입니다.
string[]
필수
en이나 es 같은 ISO 639 코드로 나타낸 타기팅 언어입니다. ISO 코드가 없는 지역별 로캘은 숫자 로캘 키로 표시됩니다. 비어 있으면 모든 언어를 타기팅합니다.
number
필수
리드 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 리드 수(라스트 클릭 기준)입니다.
object | null
필수
이 광고 그룹의 학습 단계에 필요한 전환을 향한 진행 상황입니다. 학습 중이거나 학습 제한 상태이고 유효한 집계가 있을 때만 값이 있으며, 그렇지 않으면 null입니다. 임곗값에 도달했다고 해서 게재 상태가 결정되지는 않습니다.

속성

integer
필수
이 광고 그룹의 학습 단계에 필요한 전환 수입니다. 게재 중에 변경될 수 있습니다.
integer
필수
이 광고 그룹의 학습 단계 중 마지막 주요 편집 이후 집계된 전환 수입니다.
number
필수
전환 수를 임곗값으로 나눈 백분율로, 0–100 범위로 제한됩니다. 광고 그룹의 delivery_status가 기준이 됩니다.
광고를 클릭한 사람들이 도착 페이지에서 발생시킨 페이지 조회 수로, Whop 픽셀이 기록합니다. 모든 광고 플랫폼에서 동일한 방식으로 집계됩니다.
number
필수
픽셀에 귀속된 구매의 USD 가치입니다.
number
필수
Whop 픽셀에 귀속된 구매 수(라스트 클릭 기준)입니다.
number
필수
이를 본 고유 사용자 수입니다.
object
필수
타기팅 및 제외 위치입니다.

속성

object
필수
타기팅에서 제외되는 위치입니다. 국가 그룹은 제외할 수 없습니다.

속성

object[]
필수
위치 분류 체계를 키로 하는 도시입니다.

속성

string
필수
위치 분류 체계에서의 도시 키입니다.
string
Austin 같은 도시 이름입니다. 위치 분류 체계에 이름이 없으면 없습니다.
string[]
필수
US 같은 ISO 3166-1 alpha-2 코드로 나타낸 국가입니다.
string[]
필수
worldwide나 europe 같은 다국가 그룹입니다.
object[]
필수
각각 좌표와 반경으로 이루어진 원형 영역입니다.

속성

string
지점이 속한 국가의 ISO 3166-1 alpha-2 코드입니다. 캠페인이 광고 세트가 도달하는 국가를 선언해야 하는 특별 광고 카테고리에서는 이 값을 보내세요.
string
필수
radius의 단위입니다.사용 가능한 옵션: mile, kilometer
number
필수
중심점의 위도입니다.
number
필수
중심점의 경도입니다.
string
도시나 주소 같은 위치 레이블입니다. 위치에 레이블이 없으면 없습니다.
number
필수
distance_unit 단위의 중심점 주변 반경입니다.
string[]
필수
US-CA 같은 ISO 3166-2 코드로 나타낸 미국 주 및 DC입니다. 미국 영토(PR, GU, VI, AS, MP)와 미국 외 모든 지역은 countries를 통해 타기팅합니다.
string[]
필수
US:78756처럼 COUNTRY:CODE 형식을 키로 하는 ZIP 및 우편번호입니다.
object
필수
광고 그룹이 타기팅하는 위치입니다.

속성

object[]
필수
위치 분류 체계를 키로 하는 도시입니다.

속성

string
필수
위치 분류 체계에서의 도시 키입니다.
string
Austin 같은 도시 이름입니다. 위치 분류 체계에 이름이 없으면 없습니다.
string[]
필수
US 같은 ISO 3166-1 alpha-2 코드로 나타낸 국가입니다.
string[]
필수
worldwide나 europe 같은 다국가 그룹입니다.
object[]
필수
각각 좌표와 반경으로 이루어진 원형 영역입니다.

속성

string
지점이 속한 국가의 ISO 3166-1 alpha-2 코드입니다. 캠페인이 광고 세트가 도달하는 국가를 선언해야 하는 특별 광고 카테고리에서는 이 값을 보내세요.
string
필수
radius의 단위입니다.사용 가능한 옵션: mile, kilometer
number
필수
중심점의 위도입니다.
number
필수
중심점의 경도입니다.
string
도시나 주소 같은 위치 레이블입니다. 위치에 레이블이 없으면 없습니다.
number
필수
distance_unit 단위의 중심점 주변 반경입니다.
string[]
필수
US-CA 같은 ISO 3166-2 코드로 나타낸 미국 주 및 DC입니다. 미국 영토(PR, GU, VI, AS, MP)와 미국 외 모든 지역은 countries를 통해 타기팅합니다.
string[]
필수
US:78756처럼 COUNTRY:CODE 형식을 키로 하는 ZIP 및 우편번호입니다.
string | null
필수
귀속된 횟수가 결과를 나타내는 Whop 픽셀 전환 이벤트입니다. 최적화 목표이거나, 광고 그룹별로 예산을 설정하는 캠페인의 경우 귀속된 횟수가 가장 많은 이벤트입니다. 목표가 Whop에 귀속되는 이벤트가 아니면 null입니다.사용 가능한 옵션: purchase, lead, schedule, submit_application, contact, complete_registration, view_content, add_to_cart, custom, messaging_conversation
string | null
필수
result_event가 custom일 때의 판매자 정의 이벤트 이름입니다. 표준 이벤트에서는 null입니다.
number | null
필수
result_event의 기반이 되는 Whop 픽셀 귀속 횟수입니다. 캠페인의 광고 그룹들이 서로 다른 목표를 최적화하면 단일 result_event가 없으며(null), 이 값은 대신 각 광고 그룹의 귀속 결과를 합산한 값입니다. Whop에 귀속될 수 있는 항목을 최적화하지 않으면 null입니다.
number
필수
구매 가치를 지출로 나눈 값으로, 둘 다 USD 기준입니다(통화 중립적인 비율). 지출이 없으면 0입니다.
number
필수
일정 예약 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 일정 예약 이벤트 수(라스트 클릭 기준)입니다.
number
필수
spend_currency로 표시된 청구 금액입니다.
string | null
필수
모든 금액 지표의 ISO 4217 통화 코드입니다.
string | null
필수
광고 그룹 게재가 시작되는 시각(ISO 8601 타임스탬프)입니다. 활성화되는 즉시 시작되면 null입니다.
string
필수
광고 그룹의 활성화 여부입니다. active와 paused는 사용자가 설정하며, rejected는 광고 검토를 통과하지 못했음을 의미하고, duplicating은 아직 내용이 채워지고 있는 복사본입니다.사용 가능한 옵션: active, paused, rejected, duplicating
number
필수
신청서 제출 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 신청서 제출 이벤트 수(라스트 클릭 기준)입니다.
string | null
필수
광고 그룹의 표시 이름입니다.
number | null
필수
고유 클릭 수를 노출 수로 나눈 값으로, 0과 1 사이입니다.
number
필수
Whop 픽셀이 보고한 클릭한 사람 수로, 사람당 한 번만 집계됩니다.
string
필수
광고 그룹이 마지막으로 업데이트된 시각(ISO 8601 타임스탬프)입니다.
number
필수
콘텐츠 조회 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.
number
필수
Whop 픽셀에 귀속된 콘텐츠 조회 이벤트 수(라스트 클릭 기준)입니다.
AdGroup