Campanhas

Campanha é a promoção que o marketplace monta — Black Friday, saldão, semana do cliente — e que a sua loja escolhe se quer entrar. Quem define nome, vigência e o tamanho do desconto é a plataforma. Você decide quais anúncios entram.

Este guia cobre o ciclo do lado do vendedor: descobrir as campanhas abertas, ver quais anúncios podem participar, inscrever e retirar.

Consultar exige o escopo store_products_read; entrar e sair de campanha exigem store_products_write.

Conceitos

Adesão é por anúncio, não por loja. Você inscreve item_id por item_id. Anúncio que não foi inscrito segue com o preço normal durante a campanha.

O desconto vem pronto. A campanha carrega a configuração em rules.coupon_config: discount_type (percentage ou fixed) e value. Você não negocia o valor pela API — só decide se entra.

Prazo de adesão (opt_in_deadline). É diferente da vigência. Normalmente a inscrição fecha antes de a campanha começar. Passou do prazo, o opt-in devolve 422. Campanha com opt_in_deadline: null não tem prazo.

Tipos (type).standard é desconto comum. collective_buying é compra coletiva: o pedido nasce represado e só segue quando a campanha encerra — o ciclo do pedido muda, e está em Pedidos: compra coletiva.

Status (status).draft (a plataforma ainda está montando), active (no ar), finished e cancelled. Adesão é recusada nas duas últimas.

O identificador é o id numérico. As rotas de campanha usam o id que vem no calendário. O uid também é devolvido, mas não é aceito no lugar dele.

Calendário

O calendário lista as campanhas que ainda não terminaram (ends_at no futuro), da mais próxima para a mais distante, sem as canceladas. É a porta de entrada: é dele que sai o id usado em todo o resto.

{
  "id": 128,                     // use este valor em {id}
  "uid": "01KS3PRG…",            // não é aceito nas rotas
  "name": "Black Friday 2026",
  "slug": "black-friday-2026",
  "type": "standard",            // standard | collective_buying
  "status": "active",            // draft | active | finished | cancelled
  "starts_at": "2026-11-27T00:00:00.000000Z",
  "ends_at": "2026-11-30T23:59:59.000000Z",
  "opt_in_deadline": "2026-11-20T23:59:59.000000Z",  // null = sem prazo
  "rules": {
    "coupon_config": { "discount_type": "percentage", "value": 15 }
  },
  "primary_color": "#111111",
  "has_landing_page": true,
  "show_in_menu": true
}

A listagem é paginada no envelope padrão (data.data[] + data.meta.pagination), com per_page de 15 por padrão.

Campanhas em draft aparecem no calendário. São as que a plataforma ainda está montando: a vigência e o desconto podem mudar antes de entrar no ar.

Anúncios elegíveis

Lista paginada dos anúncios da loja que ainda não estão na campanha: ofertas ativas, já descontando o que foi inscrito. Aceita search (por título ou item_id), page e per_page.

Cada item já vem com a simulação do preço promocional:

{
  "item_id": "US-0000000001234",   // é este valor que vai no opt-in
  "title": "Camiseta algodão 30.1 branca",
  "image": "https://cdn.example.com/thumb.jpg",
  "price": 59.90,                   // menor preço unitário que você oferta hoje
  "discount_preview": 50.92         // como ficaria com o desconto da campanha
}

discount_preview vem null quando a campanha não tem desconto configurado ou o anúncio não tem preço. É simulação: o valor gravado é calculado de novo na adesão.

Entrar na campanha

{
  "publication_ids": ["US-0000000001234", "US-0000000005678"]
}

O publication_ids é obrigatório e cada valor segue o formato XX-0000000000000 (2 a 5 letras maiúsculas, hífen, 13 dígitos) — é o item_id que veio de eligible-products. Formato fora disso devolve 422 sem inscrever nada.

A chamada é idempotente por anúncio: reenviar um item_id já inscrito atualiza a inscrição, não duplica.

A resposta é enxuta; o resultado real você confere em my-products:

{
  "success": true,
  "message_code": "SUCCESS",
  "data": { "message": "OPT_IN_SUCCESSFUL" }
}

Sair da campanha

Mesmo endereço do opt-in, com DELETE. Com publication_ids no corpo, sai só o que você listou. Sem corpo, sai tudo: todos os anúncios que a loja tinha inscrito naquela campanha.

{
  "publication_ids": ["US-0000000001234"]
}

Responde 204 sem corpo, inclusive quando não havia nada para remover. Aqui não há checagem de prazo: dá para sair depois do opt_in_deadline.

Anúncios inscritos

O que a loja já colocou na campanha, com o preço promocional que foi autorizado:

{
  "publication_id": "US-0000000001234",
  "title": "Camiseta algodão 30.1 branca",
  "image": "https://cdn.example.com/thumb.jpg",
  "authorized_discount_price": "50.92",  // congelado na adesão
  "status": "ACCEPTED"
}

Resumo da loja

Números agregados para um painel, mais os prazos que vencem primeiro:

{
  "active_campaigns": 4,       // campanhas em aberto no marketplace
  "joined_campaigns": 2,       // em quantas a loja entrou
  "enrolled_products": 37,     // anúncios inscritos somando todas
  "upcoming_deadlines": [      // até 5, do prazo mais próximo ao mais distante
    { "id": 128, "name": "Black Friday 2026", "opt_in_deadline": "2026-11-20T23:59:59.000000Z" }
  ]
}

active_campaigns conta o mesmo conjunto do calendário (não canceladas, com ends_at no futuro), e não só as de status: "active".

Fluxo: entrar numa campanha

Cuidados

O preço promocional é congelado na adesão. O authorized_discount_price é calculado com o preço que o anúncio tinha na hora do opt-in. Se você mudar o preço depois, ele não é recalculado. Mexeu no preço de um anúncio inscrito? Refaça o opt-in dele.

DELETE sem corpo tira todos os anúncios. Se a intenção é remover um só, mande o publication_ids. Não existe confirmação.

A inscrição não valida vigência. Você pode inscrever anúncio numa campanha que ainda vai começar — é justamente para isso que existe o opt_in_deadline antes do starts_at. O que a API recusa é campanha finished/cancelled e prazo vencido.

Campanha pode ter teto de anúncios por loja. Quando existe, o opt-in que ultrapassaria o teto é recusado inteiro com CAMPAIGN_PRODUCT_LIMIT_REACHED. Nenhum anúncio da chamada entra.

Compra coletiva muda o pedido, não só o preço. Se o type for collective_buying, os pedidos daqueles anúncios ficam represados até a campanha encerrar. Leia Pedidos: compra coletiva antes de aderir.

Erros

Para onde ir agora