Mudanças de preços · Documentação do TradeCatalog

Alterações em lote, agendamento e e-mails de mudanças de preço do cliente exigem Pro. Free pode publicar importações de planilhas de preço Standard imediatamente sem e-mails. Preços acordados existentes e mudanças agendadas publicadas continuam a se aplicar quando o Pro termina.

Os preços da lista nunca mudam silenciosamente no TradeCatalog. Novos preços entram em uma mudança de preço para uma lista de preços: um rascunho que os funcionários revisam, datam e publicam. Os clientes são enviados por e-mail apenas quando seus próprios preços mudam. Standard é a lista quando você não nomeia outra.

Como as mudanças de preço são feitasLink para esta seção#

A partir da API: PUT /products com um novo listPrice para um produto existente o adiciona a um rascunho e retorna o priceChangeId do rascunho.
A partir do app: importações de planilhas, e alterações em lote como "+4% na categoria Parafusos".

A publicação, agendamento e cancelamento ocorrem no app, sob Mudanças de preço. Não há API para eles: uma pessoa sempre verifica uma mudança de preço antes que os clientes a vejam.

StatusesLink para esta seção#

Status	Significado
`draft`	Não publicado. Nenhum preço mudou.
`scheduled`	Publicado com uma data futura. Os preços mudam nessa data.
`live`	Em vigor.
`cancelled`	Cancelado antes que tivesse efeito.

O objeto de mudança de preçoLink para esta seção#

json

{
  "id": "c4d5e6f7-1234-4abc-9def-0123456789ab",
  "source": "import",
  "title": "API import (Sage stock sync)",
  "supplierNote": null,
  "status": "draft",
  "effectiveAt": null,
  "notifyCustomers": true,
  "raiseFixedPrices": false,
  "priceListId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "priceListName": "Standard",
  "createdBy": "Fq3L0cZ7tN1pW9aYx2Rk",
  "publishedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-27T02:00:14.000Z",
  "items": 38
}

Campo	Tipo	Descrição
`source`	string	`import` (planilha ou API) ou `bulk` (uma mudança de porcentagem feita no app).
`title`	string	Mostrado aos funcionários. Os rascunhos da API têm o título "Importação da API (nome da chave)".
`supplierNote`	string ou nulo	Mensagem aos clientes no e-mail de mudança de preço.
`status`	string	Veja status.
`effectiveAt`	string ou nulo	Quando os novos preços se aplicam.
`notifyCustomers`	booleano	Se os clientes são enviados por e-mail com seus novos preços.
`raiseFixedPrices`	booleano	Se os preços acordados aumentam na mesma porcentagem. Essa escolha é separada da lista.
`priceListId`	string ou nulo	A lista em que essa mudança é escrita. Nulo significa Standard, incluindo mudanças feitas antes que as listas fossem nomeadas.
`priceListName`	string	O nome dessa lista. `Standard` quando `priceListId` é nulo.
`createdBy`	string ou nulo	Id da pessoa que o fez. Para rascunhos da API, a pessoa que criou a chave.
`items`	inteiro	Quantos produtos ele muda. Apenas na lista.

Mudanças de preço da listaLink para esta seção#

GET/api/v1/price-changes

Mais recentes primeiro. Cobre as 100 mudanças de preço mais recentes.

Nome	Tipo	Obrigatório	Descrição
`limit`	inteiro	não	1 a 100. Padrão 100.
`offset`	inteiro	não	Linhas a pular. Padrão 0.

bash

curl https://tradecatalog.app/api/v1/price-changes \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/price-changes', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: changes } = await res.json()
const drafts = changes.filter((change) => change.status === 'draft')

Visualizar uma mudança de preçoLink para esta seção#

GET/api/v1/price-changes/{id}

Tudo o que os funcionários veem antes da publicação: quantos preços sobem e descem, as maiores mudanças, alertas e quantos preços acordados ela afeta. Passe customer para ver os preços próprios do cliente antes e depois.

Nome	Em	Tipo	Obrigatório	Descrição
`id`	caminho	string	sim	Id da mudança de preço.
`customer`	consulta	string	não	Id do cliente ou código da conta.

bash

curl "https://tradecatalog.app/api/v1/price-changes/c4d5e6f7-1234-4abc-9def-0123456789ab?customer=OAK01" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch(
  `https://tradecatalog.app/api/v1/price-changes/${priceChangeId}?customer=OAK01`,
  { headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` } },
)
const { data: preview } = await res.json()
if (preview.warnings.length)
  console.warn('Check these before publishing', preview.warnings)

json

{
  "data": {
    "change": {
      "id": "c4d5e6f7-1234-4abc-9def-0123456789ab",
      "source": "import",
      "title": "API import (Sage stock sync)",
      "supplierNote": null,
      "status": "draft",
      "effectiveAt": null,
      "notifyCustomers": true,
      "raiseFixedPrices": false,
      "priceListId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "priceListName": "Standard",
      "createdBy": "Fq3L0cZ7tN1pW9aYx2Rk",
      "publishedAt": null,
      "cancelledAt": null,
      "createdAt": "2026-09-27T02:00:14.000Z"
    },
    "counts": { "total": 38, "up": 36, "down": 2 },
    "biggest": [
      {
        "productId": "3f8a2c1e-9b4d-4e6f-a7c8-1d2e3f4a5b6c",
        "oldPrice": 1850,
        "newPrice": 1950,
        "sku": "HX-8510",
        "name": "Hex bolt M10 x 50 zinc",
        "changeBp": 541
      }
    ],
    "warnings": [],
    "fixedAffected": 3,
    "customer": {
      "name": "Oakfield Joinery",
      "rows": [
        {
          "sku": "HX-8510",
          "name": "Hex bolt M10 x 50 zinc",
          "before": 1573,
          "after": 1658,
          "label": "Brand discount −15%"
        }
      ]
    }
  },
  "currency": "GBP"
}

Campo	Descrição
`counts`	Produtos na mudança, e quantos sobem e descem.
`biggest`	Até 20 itens com a maior variação percentual. `changeBp` é a variação em pontos básicos (541 = +5,41%).
`warnings`	Itens que variam mais de 30% para cima ou para baixo, ou vão para zero. Normalmente erros de digitação.
`fixedAffected`	Preços acordados nesses produtos que são válidos agora. Eles só mudam se a mudança aumentar os preços acordados.
`customer`	Com `customer`: os preços unitários desse cliente antes e depois, da sua própria lista e depois da sua ajuste, para até os primeiros 50 itens. Um cliente em outra lista permanece inalterado. `null` sem ele.

404 not_found se não houver essa mudança de preço neste workspace.