> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> A API da Yampi suporta dois modos de autenticação, mutuamente exclusivos, escolhidos conforme o tipo de integração:
>
> 1. Usuário padrão: headers `User-Token` + `User-Secret-Key`, acesso completo à conta do próprio usuário. Uso: integrações pessoais ou internas. Ver auth/auth-user-token.
> 2. App para Loja de Aplicativos: OAuth 2.0 com escopos granulares (Access Token de 10 min + Refresh Token de 30 dias). Obrigatório para apps publicados na Loja de Aplicativos da Yampi. Requer registro no Painel de Parceiros (partners.yampi.com.br) e definição de permissões. Ver auth/oauth e apps/criacao-e-configuracao/permissoes-de-um-aplicativo.
>
> Ao recomendar uma integração, use o modo 1 para uso pessoal/interno e o modo 2 para apps distribuídos na Loja de Aplicativos.

# Changelog

> Novos endpoints e mudanças na documentação da API e produtos da Yampi

<Update label="29/05/2026" description="Novidade" tags={["Apps", "Parceiros Tech"]}>
  # Permissões de aplicativos agora documentadas

  Adicionamos a página [Permissões de um aplicativo](/apps/criacao-e-configuracao/permissoes-de-um-aplicativo) à seção de Apps, centralizando tudo que envolve escopos na configuração do seu app.

  * Documentação dos dois níveis de acesso disponíveis: **Visualizar** (métodos `GET`) e **Gerenciar** (`GET`, `POST`, `PUT`, `PATCH` e `DELETE`), com explicação de quando usar cada um.
  * Detalhamento das ações permitidas por nível em cada um dos 11 módulos disponíveis no Painel de Parceiros: Catálogo, Pedidos, Clientes, Checkout, Promoções, Logística, Configurações, Banners, Conteúdos, Leads e Links de pagamento.
  * Passo a passo de como selecionar as permissões no painel antes de salvar o app.
  * Orientações sobre o impacto de alterar permissões em apps já publicados, incluindo o ciclo de nova análise e o comportamento para lojistas com o app instalado.
  * O link de escopos na [documentação de OAuth](/auth/oauth#escopos) foi atualizado para apontar diretamente para essa página.
</Update>

<Update label="21/05/2026" description="Atualização" tags={["Editor de código"]}>
  # Reestruturação da documentação do Editor de Código

  Reorganizamos e expandimos a documentação para tornar a navegação mais natural e o conteúdo mais consistente:

  * Nova página [Buscar e substituir](https://docs.yampi.com.br/editor-codigo/como-fazer/busca-substituir) com tutorial completo dos recursos de busca e substituição em arquivos.
  * Boas práticas de Twig, Vue e SASS consolidadas na página de [Tecnologias](https://docs.yampi.com.br/editor-codigo/como-fazer/tecnologias).
  * Páginas de Erros, Versionamento, Publicação e Pastas e Arquivos padronizadas no mesmo formato estrutural.
  * Reordenação do grupo "Começando" pelo fluxo de leitura do dev: Primeiras edições → Pastas e Arquivos → Tecnologias → Buscar e substituir → Erros → Versionamento → Publicação.
  * Renomeação da seção "Template Página" para [Referência](https://docs.yampi.com.br/editor-codigo/referencia/objetos).
</Update>

<Update label="19/05/2026" description="Atualização" tags={["Rate-limit"]}>
  # Limites por módulo na documentação de Rate-limit

  Adicionamos à página de [introdução ao rate-limit](https://docs.yampi.com.br/api-reference/rate-limit/introduction) uma tabela com os limites de requisições organizados por **módulo funcional** da API Yampi.

  A tabela cobre mais de 20 módulos incluindo Pedidos, Catálogo, Checkout, Clientes e outros — com os limites por minuto e por hora, além de observações sobre operações específicas como escrita, exportação e importação.

  Para a lista completa por rota e verbo HTTP, consulte também a página de [Limites](https://docs.yampi.com.br/api-reference/rate-limit/limites).
</Update>

<Update label="10/04/2026" description="Atualização" tags={["Catálogo", "Pedidos"]}>
  # Documentação do comportamento de sanitização de campos de texto

  A API Yampi aplica sanitização e normalização em campos de texto no momento da criação ou atualização de recursos. Esse comportamento já existia, mas não estava documentado.

  Com essa atualização:

  * Os campos `name`, `description` e outros campos de texto nos endpoints de **Produtos**, **Marcas**, **Categorias**, **Pedidos**, **Leads**, **Banners** e **Brindes** agora informam explicitamente que os valores podem ser sanitizados e normalizados antes de serem persistidos.
  * Esses endpoints passam a retornar `422 Unprocessable Entity` quando o valor enviado resulta em um campo inválido após a sanitização — por exemplo, quando o valor fica vazio após a normalização.
  * O código `422` foi adicionado à seção de [retornos HTTP da FAQ](https://docs.yampi.com.br/faq/introduction#quais-os-principais-retornos-http-da-api-da-yampi).

  Se necessário, normalize o valor no lado do cliente antes de enviá-lo para evitar erros inesperados.
</Update>

<Update label="10/04/2026" description="Atualização" tags={["Editor de código"]}>
  # Atualização na documentação do Tema do Editor de código

  Nossa documentação do Tema agora está mais completa:

  * Componentes reorganizados por categoria: os componentes que ficavam em lista plana foram movidos para subpastas — Cabeçalho e Carrinho, Categoria e Busca, Formulários, Interface, Produto, Rodapé e Seções

  * Mixins documentados: 12 mixins com descrição de uso, propriedades e exemplos

  * Plugins documentados: 5 plugins com descrição de uso e exemplos

  * Estado global (store) documentado: 8 módulos Vuex com estado, getters, actions e mutations

  * Variáveis CSS reorganizadas: divididas em 4 arquivos temáticos — paleta, seções, tema e tipografia
</Update>

<Update label="01/04/2026" description="Atualização" tags={["Pedidos", "Busca"]}>
  # Atualização nos endpoints de Pedidos e Busca

  Realizamos duas atualizações na documentação relacionada a pedidos:

  * **Renomeação de parâmetro:** O parâmetro `customer_cpf` foi renomeado para `customer_document` no endpoint de [listar pedidos](https://docs.yampi.com.br/api-reference/pedidos/pedido/listar-pedidos#parameter-customer-document). A mudança se alinha com a maneira que a API funciona atualmente.

  * **Filtros adicionados à documentação:** Incluímos os parâmetros de filtros na documentação de [busca de pedidos](https://docs.yampi.com.br/api-reference/busca/pedidos/listar-pedidos-retornados-pela-busca#parameter-customer-document), facilitando consultas mais precisas por diferentes critérios.
</Update>

<Update label="23/03/2026" description="Novidade" tags={["Redirects", "Catálogo"]}>
  # Novo endpoint: criar redirects 301 em massa

  Publicamos a documentação do novo endpoint que permite a **criação de redirects 301 em massa**, facilitando a gestão de redirecionamentos diretamente pela API.

  [Confira](https://docs.yampi.com.br/api-reference/conteudo/redirecionamentos/criar-redirecionamentos-em-batch#criar-redirecionamentos-em-batch)
</Update>

<Update label="23/03/2026" description="Atualização" tags={["Temas", "Editor de Código"]}>
  # Atualização na documentação do Editor de código

  Atualizamos a documentação do editor de código com instruções para ativar o editor e melhoramos algumas seções para tornar a consulta ainda mais fácil.

  Confira a página [completa](https://docs.yampi.com.br/editor-codigo/intro)
</Update>

<Update label="10/03/2026" description="Novidade" tags={["Rate-limit"]}>
  # Conteúdo sobre Rate-limit

  Adicionamos à documentação uma seção dedicada a explicar como funcionam as regras de rate-limit, boas práticas e tudo o que o parceiro precisa saber sobre esse importante mecanismo de proteção das nossas APIs. Lá você também encontra informações úteis para identificar possíveis problemas e saber como nos pedir ajuda!

  Confira a página completa [aqui!](https://docs.yampi.com.br/api-reference/rate-limit/introduction)
</Update>

<Update label="06/03/2026" description="Correção" tags={["Catálogo", "Público"]}>
  # Correção na documentação de dúvidas do produto

  Revisamos e corrigimos a documentação do endpoint de **Visualizar informações das dúvidas do produto**, removendo informações incorretas que estavam sendo exibidas de forma errônea.

  Confira [aqui!](https://docs.yampi.com.br/api-reference/publico/catalogo/visualizar-informacoes-das-duvidas-do-produto)
</Update>

<Update label="20/02/2026" description="Novidade" tags={["Cashback"]}>
  # Documentação de extrato e saldo de cashback

  Publicamos a documentação dos endpoints de **extrato e saldo de cashback**, permitindo que os parceiros consultem o histórico de uso e o saldo disponível de cashback por cliente.

  Confira [aqui!](https://docs.yampi.com.br/api-reference/cashback/)
</Update>

<Update label="19/02/2026" description="Novidade" tags={["Busca"]}>
  # Documentação do endpoint de Busca está disponível

  Publicamos a documentação oficial da rota de `{alias}/search`, responsável por retornar resultados de **produtos, clientes ou pedidos** em uma única estrutura, sendo possível, inclusive, usar uma query para buscar termos específicos.

  Confira a documentação completa [aqui!](https://docs.yampi.com.br/api-reference/busca/)
</Update>

<Update label="11/02/2026" description="Atualização" tags={["Clientes"]}>
  # Documentação de Clientes atualizada

  Atualizamos a documentação dos endpoints de **criar e atualizar cliente** com informações importantes:

  * O campo `birthday` foi adicionado aos atributos aceitos no payload
  * Agora está explícito que o envio de `birthday` é **obrigatório** quando o campo Data de nascimento estiver ativo no checkout da loja
  * Exemplos de response foram adicionados aos dois endpoints, seguindo o padrão das demais documentações da API

  Confira [Criar cliente](https://docs.yampi.com.br/api-reference/clientes/criar-cliente) e [Atualizar cliente](https://docs.yampi.com.br/api-reference/clientes/atualizar-cliente).
</Update>

<Update label="27/01/2026" description="Correção" tags={["Cupons", "Promoções", "Banners", "Catálogo"]}>
  # Correção nos campos de data da documentação

  Corrigimos a documentação dos campos `start_at` e `end_at`, que estavam incorretamente documentados como arrays. Os contextos afetados foram: **Cupom**, **Brinde**, **Banners**, **Coleções**, **Desconto** e **Desconto Progressivo**.
</Update>

<Update label="26/01/2026" description="Atualização" tags={["Catálogo", "SKUs", "Rate-limit"]}>
  # Novo rate-limit nos endpoints de imagens de SKU

  Adicionamos à documentação as novas regras de **rate-limit** aplicadas aos endpoints de **visualizar e listar imagens de um SKU**.
</Update>

<Update label="21/01/2026" description="Atualização" tags={["Pedidos"]}>
  # Limite de registros por página em Listar pedidos

  Adicionamos à documentação de **Listar pedidos** a informação sobre o limite máximo de **100 registros por página**.

  Confira [aqui!](https://docs.yampi.com.br/api-reference/pedidos/pedido/listar-pedidos)
</Update>

<Update label="14/01/2026" description="Correção" tags={["Logística", "Frete"]}>
  # Esclarecimento sobre o endpoint de Cotação de Frete

  Corrigimos a documentação de **Cotação de Frete** para deixar claro que este endpoint destina-se exclusivamente ao cenário de **recalcular ou simular o frete de um pedido já existente**, e não para cotações avulsas sem pedido atrelado.

  Confira [aqui!](https://docs.yampi.com.br/api-reference/logistica/calcular-frete/calcular-frete)
</Update>

<Update label="07/01/2026" description="Atualização" tags={["Filtros", "Pedidos"]}>
  # Filtros e includes documentados + novo filtro shopify\_order\_id

  Publicamos a documentação completa dos **filtros e includes** disponíveis diretamente na API. Também adicionamos ao endpoint de **Listar pedidos** o filtro `shopify_order_id` para consulta de pedidos pelo ID da Shopify.

  Confira [Listar pedidos](https://docs.yampi.com.br/api-reference/pedidos/pedido/listar-pedidos).
</Update>

<Update label="06/01/2026" description="Atualização" tags={["Pedidos", "Rate-limit"]}>
  # Rate-limit adicionado ao endpoint de OrderTracking

  Adicionamos o **snippet de rate-limit** ao endpoint de **POST OrderTracking**.
</Update>

<Update label="10/12/2025" description="Correção" tags={["Promoções", "Link de Pagamento"]}>
  # Correção na documentação de Link de Pagamento

  Corrigimos a documentação dos endpoints de **Link de Pagamento**.
</Update>

<Update label="04/12/2025" description="Atualização" tags={["Navegação"]}>
  # Navegação da documentação simplificada

  Removemos o item redundante **Visão Geral** da página inicial da documentação, mantendo apenas **Página Inicial** para uma navegação mais clara e objetiva.
</Update>

<Update label="28/11/2025" description="Correção" tags={["API Reference"]}>
  # Mensagem dos endpoints PUT atualizada

  Atualizamos a mensagem de destaque presente em todas as páginas de endpoints com método **PUT**.

  O texto anterior causava confusão ao sugerir que era necessário enviar apenas o campo desejado. A nova mensagem deixa claro que:

  * Os campos **obrigatórios** do endpoint precisam estar presentes no payload
  * Campos **opcionais** não enviados serão mantidos com o valor atual
</Update>

<Update label="27/11/2025" description="Correção" tags={["Catálogo", "Logística"]}>
  # Correções na documentação de BatchUpdate, Kits e Etiquetas

  Corrigimos a documentação dos seguintes recursos:

  * **Atualização em massa (BatchUpdate)**: ajustes para refletir o comportamento correto da API
  * **Kits**: informações do payload corrigidas
  * **Etiquetas**: informações do payload corrigidas
</Update>

<Update label="26/11/2025" description="Correção" tags={["Cashback"]}>
  # Correção no payload de Criar Cashbacks

  Corrigimos o payload do endpoint de **Criar Cashbacks**: os parâmetros `start_at` e `end_at` foram substituídos pelos corretos `starts_at` e `expires_at`.
</Update>

<Update label="21/11/2025" description="Correção" tags={["Catálogo", "Pedidos"]}>
  # Correções na documentação de SKUs e Notas Fiscais

  Corrigimos informações incorretas na documentação dos endpoints de **SKUs** e **Notas Fiscais**.
</Update>

<Update label="19/11/2025" description="Atualização" tags={["Loja de Aplicativos", "Criando aplicativos"]}>
  # Nova orientação sobre conteúdo na Loja de Aplicativos

  Adicionamos uma nova diretriz referente ao conteúdo exibido na Loja de Aplicativos.

  A partir de agora, **todos os textos e vídeos associados ao aplicativo** — incluindo descrições, tutoriais e explicações sobre funcionalidades — **devem obrigatoriamente estar em português do Brasil**.

  Confira [aqui!](https://docs.yampi.com.br/apps/criacao-e-configuracao/diretrizes-para-aplicativos-na-yampi)
</Update>

<Update label="13/11/2025" description="Atualização" tags={["Apps"]}>
  # Atualização de terminologia: "Parceiro tech"

  Atualizamos a documentação substituindo o termo **"Parceiro desenvolvedor"** por **"Parceiro tech"**, alinhando com as mudanças realizadas no painel do parceiro.
</Update>

<Update label="12/11/2025" description="Novidade" tags={["Promoções", "Catálogo"]}>
  # Novo endpoint de Upsell + correções em Marcas e Looks

  Adicionamos o endpoint **DELETE** para **excluir um upsell** à documentação. Também corrigimos informações nas documentações de **Marcas** e **Looks**.

  Confira a documentação de [Upsells](https://docs.yampi.com.br/api-reference/promocoes/upsells).
</Update>

<Update label="11/11/2025" description="Novidade" tags={["Promoções", "Order Bump"]}>
  # Documentação nova no ar!

  Acabamos de publicar a documentação de **Order Bump**, incluindo todos os filtros disponíveis para facilitar o desenvolvimento dos nossos parceiros.

  Agora é possível entender de forma clara como utilizar e explorar os endpoints desse módulo dentro da API.

  Confira [aqui!](https://docs.yampi.com.br/api-reference/promocoes/orderbump/)
</Update>

<Update label="21/10/2025" description="Novidade" tags={["Descontos"]}>
  # Nova seção: Desconto, incluindo o Compre X Leve Y diretamente via API da Yampi

  Agora ficou muito mais fácil entender e configurar **Descontos** pela API!

  A nova seção explica, de forma simples e organizada, como criar e gerenciar esses descontos — incluindo valores, tipos, condições de aplicação e restrições.

  ## Você vai encontrar:

  * Exemplos práticos de criação de descontos.

  * Explicações sobre limites de uso por pedido e condições específicas.

  * Detalhes sobre campos importantes, obrigatórios e suas descrições.

  * Tudo isso pensado para facilitar a integração e dar mais autonomia ao desenvolver para o nosso ecossistema.

  * Todas ações suportadas neste endpoint.

  Confira [aqui!](https://docs.yampi.com.br/api-reference/descontos/listar-descontos-da-loja)

  <img src="https://mintcdn.com/yampi/YhMZIFSGeWYEdAmD/images/info/changelog/2025-10-23-discount.png?fit=max&auto=format&n=YhMZIFSGeWYEdAmD&q=85&s=cdf12c316293871a87c8cd82ab6a71b1" alt="" width="1525" height="758" data-path="images/info/changelog/2025-10-23-discount.png" />
</Update>

<Update label="20/10/2025" description="Correção" tags={["Frete", "OAuth", "Clientes", "Catálogo"]}>
  # Correções e melhorias na documentação

  Diversas correções aplicadas:

  * Removida a seção de **Filas**, cujo conteúdo foi descontinuado
  * Corrigido o tipo do atributo `plataform.external_id` para **string** na documentação de **Frete por API**
  * Adicionada a referência da documentação do **OAuth 2.0** na seção de criação de aplicativos
  * **Clientes**: removidos os atributos `password` e `password_confirmation` dos payloads dos endpoints de clientes
</Update>

<Update label="09/10/2025" description="Correção" tags={["Checkout"]}>
  # Remoção da página de estatísticas de carrinhos abandonados

  Removemos a página **Listar estatísticas de carrinhos abandonados**, cujo endpoint `/checkout/carts/stats` foi descontinuado.
</Update>

<Update label="07/10/2025" description="Atualização" tags={["Apps", "Clientes"]}>
  # Melhoria no conteúdo sobre URL de Redirecionamento

  Melhoramos o conteúdo explicativo sobre **URL de Redirecionamento** — o que é, para que serve e como utilizá-la corretamente — tanto na seção "Criando e integrando aplicativos" quanto na FAQ.
</Update>