API Admin › Recursos

Estoque e preço

O que o ERP manda a cada sincronização: o estoque e os preços de muitas variantes de uma vez. Pede o escopo write_products.

• Cada item aponta a variante pelo variant_id ou pelo sku (um dos dois).
• O lote tem até 100 itens e é tudo ou nada: com um item recusado, nada muda, e a resposta diz qual em fields, pela posição (items.3.delta).
• A mesma variante não aparece duas vezes no lote (400 duplicate_item), nem pelo id e pelo SKU.
• A resposta traz as variantes como ficaram, na ordem dos itens: { "variants": [variante...] } (o objeto variante está em Produtos).
• Com o Idempotency-Key, o lote mandado de novo (a rede caiu antes da resposta) não soma duas vezes. Ver Escrita repetível.

POST /inventory/adjust

Soma o delta ao estoque de agora (negativo, subtrai), sem ler antes. É o jeito seguro com pedidos acontecendo: o checkout e o ajuste esperam um pelo outro, e nenhuma unidade se perde. Use para entradas de mercadoria, devoluções e acertos.

{
  "items": [
    { "sku": "CB-P", "delta": 10 },
    { "variant_id": "5e2a...", "delta": -2 }
  ]
}

O estoque não fica negativo: se algum item ficaria abaixo de zero, o lote inteiro é recusado.

{
  "error": {
    "type": "conflict",
    "code": "insufficient_inventory",
    "message": "O ajuste deixaria o estoque abaixo de zero. Nada mudou: confira os itens em fields.",
    "fields": [
      {
        "field": "items.1.delta",
        "message": "A variante 5e2a... tem 1 em estoque; o ajuste de -2 deixaria -1"
      }
    ],
    "request_id": "..."
  }
}

POST /inventory/set

O estoque de cada item passa a ser o número mandado.

{ "items": [{ "sku": "CB-P", "inventory_quantity": 25 }] }

O número é o que está à venda, depois dos pedidos já feitos: o checkout desconta o estoque quando o pedido nasce, e devolve quando o pedido é cancelado. Um ERP que conta o estoque físico e grava o número absoluto pode vender a mesma unidade duas vezes se um pedido chegar entre a contagem e a gravação. Com pedidos acontecendo, prefira o adjust.

POST /prices/set

O preço (price), o "de" (compare_at_price; null tira a promoção) e o custo (cost; null apaga) de cada item, só os que vierem. Em centavos.

{
  "items": [
    { "sku": "CB-P", "price": 3990, "compare_at_price": 4990 },
    { "sku": "CB-M", "price": 4490, "compare_at_price": null },
    { "variant_id": "5e2a...", "cost": 1900 }
  ]
}

O "de" precisa ser maior que o preço, contando o que já está gravado: baixar o price acima de um "de" que ficou é recusado (422 invalid_compare_at_price). As promoções da loja continuam valendo sobre o preço novo, e a ordem por preço da vitrine passa a usar o novo.

Códigos

Para sincronizar nos dois sentidos

O estoque também muda pela loja: cada pedido desconta, cada cancelamento devolve, e o lojista pode mudar pelo painel. Para trazer essas mudanças ao ERP, leia GET /variants?updated_at_min=<a última leitura> (ver Produtos). Para saber na hora, assine o evento inventory.updated num webhook.