Change an ad campaign
const url = 'https://open-api.live.gobots.com.br/v1/ads/meli/campaigns/example';const options = { method: 'PATCH', headers: { 'Idempotency-Key': '2489E9AD-2EE2-8E00-8EC9-32D5F69181C0', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"name":"example","status":"active","budget":{"amount":"example"},"strategy":{"roas_target":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://open-api.live.gobots.com.br/v1/ads/meli/campaigns/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \ --data '{ "name": "example", "status": "active", "budget": { "amount": "example" }, "strategy": { "roas_target": "example" } }'Changes the name, the status (active or paused, never ended), the daily budget or the ROAS
target of one campaign. A campaign that has ended cannot be reactivated. The write is one audited
action: meta.action_id identifies it, and a 202 is polled at getAdAction.
The responses are never cached.
Authorizations
Seção intitulada “Authorizations”Parameters
Seção intitulada “Parameters”Path Parameters
Seção intitulada “Path Parameters”Marketplace of the Ads account. Only meli has an adapter in v1; the others answer 501.
The marketplace’s own campaign id. An id outside the charset answers 404.
Header Parameters
Seção intitulada “Header Parameters”One UUID per intent, reused on every retry of that intent. Kept for 24 hours per merchant and
route: the same key with the same body answers the original response again (marked
Idempotent-Replayed: true), and with a different body answers 409 idempotency_conflict.
A request that is not valid never uses up its key.
Request Bodyrequired
Seção intitulada “Request Bodyrequired”object
Never ended. An ended campaign cannot be reactivated.
object
Daily budget, a positive decimal with at most 2 decimal places, at most 1000000000.
object
Between 1.0 and 35.0, inclusive.
Responses
Seção intitulada “Responses”The write reached a terminal state; the refreshed campaign is present when the marketplace echoed it.
object
object
The marketplace’s own campaign id.
Opaque store id.
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
object
Decimal string.
ISO 4217, uppercase.
object
Decimal string.
ISO 4217, uppercase.
object
Decimal string.
ISO 4217, uppercase.
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
object
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
object
object
The state of an action. applied, partially_applied, failed and dismissed are terminal.
A closed code, never free text. outcome_unknown means the marketplace’s answer could not be read
and the change must be verified by hand.
Present when an opportunity that proposed removing an ad was applied as a pause.
One entry per requested target on a batch; the targets that failed on partially_applied.
object
A closed code, never free text. outcome_unknown means the marketplace’s answer could not be read
and the change must be verified by hand.
object
Example
{ "campaign": { "marketplace": "meli", "status": "active", "strategy": { "type": "profitability" }, "metrics": { "spend": { "amount": "250.0" }, "cpc": { "amount": "250.0" }, "attributed_sales": { "amount": "250.0" } } }, "result": { "status": "awaiting_confirmation", "reason": "budget_below_minimum", "applied_as": "pause", "details": [ { "target_type": "campaign", "status": "applied", "reason": "budget_below_minimum" } ] }}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
Present and true only when this response is a stored replay of an earlier identical request.
The write is still moving: result.status is pending, reconciling or unknown. Poll the
action named by Location until it is terminal. The response is never cached.
object
object
The state of an action. applied, partially_applied, failed and dismissed are terminal.
A closed code, never free text. outcome_unknown means the marketplace’s answer could not be read
and the change must be verified by hand.
Present when an opportunity that proposed removing an ad was applied as a pause.
One entry per requested target on a batch; the targets that failed on partially_applied.
object
A closed code, never free text. outcome_unknown means the marketplace’s answer could not be read
and the change must be verified by hand.
object
Example
{ "result": { "status": "awaiting_confirmation", "reason": "budget_below_minimum", "applied_as": "pause", "details": [ { "target_type": "campaign", "status": "applied", "reason": "budget_below_minimum" } ] }}Headers
Seção intitulada “Headers”The action to poll, /v1/ads/{marketplace}/actions/{action_id}.
The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
The request is not valid: invalid_request (a malformed header, path or body, with the field
named), idempotency_key_required, invalid_roas_target (outside 1.0 to 35.0) or
invalid_status_transition (an ended campaign cannot be reactivated).
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
The API key is missing, malformed, unknown, revoked or expired.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”Bearer challenge for the API realm.
The merchant does not have the Open API add-on active.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}The resource, or a requested store, is not this merchant’s or does not exist; the two are indistinguishable.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
idempotency_conflict when the key was used with another body; opportunity_not_applicable when
the opportunity was already applied, dismissed or expired; opportunity_locked while another
request with the same key, or another apply of the same opportunity, is still running.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
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).
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
Seconds to wait before retrying, per RFC 9110.
The route or marketplace is published but its adapter is not available yet.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
source_rejected: the marketplace refused the change. The message is one fixed sentence chosen by
the reason, never the marketplace’s own text.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”The policies that apply to this endpoint group, as
draft-ietf-httpapi-ratelimit-headers policy members: "<group>";q=<quota>;w=<window seconds>.
The state of the endpoint group’s window: "<group>";r=<remaining>;t=<seconds to reset>.
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.
object
Stable machine readable error code.
Human readable explanation. Never carries raw upstream text.
Seconds to wait before retrying.
Limit that was exceeded.
Remaining allowance in the current window.
Example generated
{ "code": "example", "message": "example", "retry_after": 1, "limit": 1, "remaining": 1}Headers
Seção intitulada “Headers”As the RateLimit-Policy response header; absent when entitlement could not be resolved.
As the RateLimit response header; absent when entitlement could not be resolved.