List the ad campaigns of the merchant

GET

/v1/ads/{marketplace}/campaigns

const url = 'https://open-api.live.gobots.com.br/v1/ads/meli/campaigns?stores=st_0Q7pXmT2bK9wLf3ZrN1cVd&status=active';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://open-api.live.gobots.com.br/v1/ads/meli/campaigns?stores=st_0Q7pXmT2bK9wLf3ZrN1cVd&status=active' \
  --header 'Authorization: Bearer <token>'

Authorizations

ApiKey

Parameters

Path Parameters

marketplace

required

string

Allowed values: meli amazon magalu shopee viavarejo b2w whatsapp qa tiktok

Marketplace of the Ads account. Only meli has an adapter in v1; the others answer 501.

Header Parameters

If-None-Match

string

The ETag of a previously fetched representation; a match answers 304 with no body.

Query Parameters

stores

Array<string>

<= 50 items

Opaque store ids to restrict the answer to, at most 50. An id that matches no store of this merchant answers 404. Defaults to every store of the merchant.

Example

?stores=st_0Q7pXmT2bK9wLf3ZrN1cVd

status

Array<string>

Allowed values: active paused ended

Campaign statuses to keep. Defaults to every status.

Example

?status=active

limit

integer

>= 1 <= 500

Rows per page, 1 to 500. Defaults to 50.

cursor

string

Opaque page marker from meta.next_cursor, bound to the exact query that issued it. Changing any parameter other than limit, or waiting too long, answers 400 invalid_cursor.

Responses

200

The campaigns, ordered by status, name and id.

application/json

object

campaigns

required

Array<object>

object

required

The marketplace’s own campaign id.

string

marketplace

required

string

Allowed values: meli amazon magalu shopee viavarejo b2w whatsapp qa tiktok

store_id

required

Opaque store id.

string

advertiser_id

required

string | null

name

required

string

status

required

string

Allowed values: active paused ended

budget

required

One of:

object
null

object

amount

required

Decimal string, null when the marketplace sets it automatically.

string | null

currency

required

string

automatic

required

boolean | null

strategy

required

One of:

object
null

object

type

required

One of:

string
null

string

Allowed values: profitability increase visibility

acos_target

required

Decimal string, a ratio in [0,1].

string | null

roas_target

required

string | null

gobots

required

object

managed

required

Whether GoBots automation manages this campaign.

boolean

automation

required

One of:

object
null

object

roas_target

required

string | null

metrics

required

One of:

object
null

A campaign’s current metric snapshot, or one bucket of a metric series. Ratios are decimal strings. A metric the origin did not send is absent, never zero. In a series every ratio is re-derived from the bucket’s sums (4 decimals, money 2) and is absent when its denominator is zero; share_of_voice is present on day buckets only.

object

spend

object

amount

required

Decimal string.

string

currency

required

ISO 4217, uppercase.

string

impressions

integer format: int64

clicks

integer format: int64

ctr

string

cpc

object

amount

required

Decimal string.

string

currency

required

ISO 4217, uppercase.

string

attributed_sales

object

amount

required

Decimal string.

string

currency

required

ISO 4217, uppercase.

string

acos

string

roas

string

remote_data

required

Marketplace-specific fields, keyed by marketplace and then by a documented key. Campaign: channel. Campaign metrics: share_of_voice (decimal string, a ratio in [0,1]). Ad group: status (the marketplace’s own), ad_group_type. Opportunity: action (an action outside the published set).

object

key

additional properties

object

key

additional properties

string

created_at

required

string | null format: date-time

updated_at

required

string | null format: date-time

remote_data

required

object

key

additional properties

object

key

additional properties

string

meta

required

object

next_cursor

required

Cursor of the next page, or null when the collection ends here.

string | null

status

string

Allowed values: partial

warnings

Array<string>

Example

{
  "campaigns": [
    {
      "marketplace": "meli",
      "status": "active",
      "strategy": {
        "type": "profitability"
      },
      "metrics": {
        "spend": {
          "amount": "250.0"
        },
        "cpc": {
          "amount": "250.0"
        },
        "attributed_sales": {
          "amount": "250.0"
        }
      }
    }
  ],
  "meta": {
    "status": "partial"
  }
}

Headers

RateLimit-Policy

required

string

The policies that apply to this endpoint group, as draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.

RateLimit

required

string

The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.

ETag

required

string

Strong validator of the representation.

304

The representation is unchanged. The request still counts as one request.

Headers

ETag

required

string

Strong validator of the representation.

RateLimit-Policy

required

string

The policies that apply to this endpoint group, as draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.

RateLimit

required

string

The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.

400

The marketplace or a query parameter carries a value the contract does not accept (invalid_request), the period exceeds the maximum (period_too_long), or the cursor is expired or was not issued for this query (invalid_cursor).

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

Headers

RateLimit-Policy

required

string

The policies that apply to this endpoint group, as draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.

RateLimit

required

string

The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.

401

The API key is missing, malformed, unknown, revoked or expired.

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

Headers

WWW-Authenticate

string

Bearer challenge for the API realm.

403

The merchant does not have the Open API add-on active.

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

404

The resource, or a requested store, is not this merchant’s or does not exist; the two are indistinguishable.

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

Headers

RateLimit-Policy

required

string

The policies that apply to this endpoint group, as draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.

RateLimit

required

string

The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.

429

The requests-per-minute limit of the endpoint group was exceeded (rate_limited), or the monthly request quota of the merchant is exhausted (quota_exceeded).

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

Headers

RateLimit-Policy

required

string

The policies that apply to this endpoint group, as draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.

RateLimit

required

string

The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.

Retry-After

required

integer

Seconds to wait before retrying, per RFC 9110.

501

The route or marketplace is published but its adapter is not available yet.

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

Headers

RateLimit-Policy

required

string

The policies that apply to this endpoint group, as draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.

RateLimit

required

string

The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.

503

The upstream source is unavailable. When the merchant’s entitlement could not be resolved the request is refused before rate limiting, so the RateLimit headers are absent.

application/json

object

code

required

Stable machine readable error code.

string

message

required

Human readable explanation. Never carries raw upstream text.

string

retry_after

Seconds to wait before retrying.

integer

limit

Limit that was exceeded.

integer

remaining

Remaining allowance in the current window.

integer

Example ^generated

{
  "code": "example",
  "message": "example",
  "retry_after": 1,
  "limit": 1,
  "remaining": 1
}

Headers

RateLimit-Policy

string

As the RateLimit-Policy response header; absent when entitlement could not be resolved.

RateLimit

string

As the RateLimit response header; absent when entitlement could not be resolved.

List the ad campaigns of the merchant

Authorizations

Parameters

Path Parameters

Header Parameters

Query Parameters

Example

Example

Responses

200

Example

Headers

304

Headers

400

Example generated

Headers

401

Example generated

Headers

403

Example generated

404

Example generated

Headers

429

Example generated

Headers

501

Example generated

Headers

503

Example generated

Headers

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated