Criar Volume Pricing usando APIs

Crie uma nova regra de Volume Pricing pela API pública, com a referência completa do corpo da requisição.

Este documento explica como criar uma nova regra de Volume Pricing usando a API pública.

1. Endpoint

Para criar um novo registro de Volume Pricing, use o seguinte endpoint:

POST - https://wholesale.samita.io/api/v1/volume-pricings

Este endpoint permite criar uma nova configuração de Volume Pricing.

2. Cabeçalhos da requisição

Todas as requisições à API devem incluir os seguintes cabeçalhos obrigatórios:

Cabeçalho	Descrição	Obrigatório
`X-SAMITA-API-KEY`	Chave de API fornecida no app Wholesale	Sim
`X-SAMITA-SHOP-URL`	Domínio da loja Shopify no formato xxx.myshopify.com	Sim
`CONTENT-TYPE`	Deve ser `application/json`	Sim

Se algum cabeçalho obrigatório estiver ausente, a requisição será rejeitada.

3. Corpo da requisição

a. Formato geral

Os dados usados para criar o Volume Pricing devem ser enviados em formato JSON.
Um exemplo de estrutura JSON é apresentado no final deste documento.

Exemplo de JSON da requisição:

{
  "title": "New Volume Pricing",
  "status": true,
  "type": "quantity",
  "apply_customer": {
    "type": "all",
    "tags": []
  },
  "exclude_customer": {
    "type": "none",
    "tags": []
  },
  "apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
  },
  "exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
  },
  "discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_method": "variant",
  "discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],
  "active_date": {
    "types": ["start date", "end date"],
    "start_at": "2026-01-15T10:00:00",
    "end_at": "2026-01-15T10:00:00"
  }
}

b. title (obrigatório)

O nome usado para identificar o registro de Volume Pricing
Deve ser uma string
Tamanho máximo: 255 caracteres

c. status (obrigatório)

Define se o registro está ativo ou não
Aceita apenas os seguintes valores:

Valor	Descrição
`true`	A regra de preço está ativa
`false`	A regra de preço está inativa

d. type (obrigatório)

Define se o preço por volume é calculado por quantidade ou por valor.

Valores aceitos:

quantity
amount

e. apply_customer (obrigatório)

Define quais clientes são elegíveis para esta regra de preço.

Estrutura:

"apply_customer": {
    "type": "all",
    "tags": []
}

type

Valores aceitos (apenas um dos seguintes):

all – Aplica a todos os clientes
logged – Aplica somente a clientes conectados
non-logged – Aplica somente a clientes visitantes
customer-tags – Aplica somente a clientes com tags específicas

tags

Obrigatório somente quando type == customer-tags
Deve ser um array separado por vírgulas
Exemplo: ["wholesale","b2b"]

Se o type não for customer-tags, este campo pode ser ignorado.

f. exclude_customer

Usado para excluir clientes específicos da regra de preço.

Estrutura:

"exclude_customer": {
    "type": "none",
    "tags": []
}

type

Valor padrão: none
Valores aceitos:

Valor	Descrição
`none`	Não exclui nenhum cliente
`customer-tags`	Exclui clientes por tags

tags

Obrigatório somente quando type == customer-tags
Array separado por vírgulas
Exemplo: ["vip","internal"]

g. apply_product (obrigatório)

Define a quais produtos a regra de preço será aplicada.

Estrutura:

"apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
}

type

Valores aceitos:

all
products
collections
product-tags

product_ids

Obrigatório somente quando type == products
Lista de IDs de produtos separados por vírgulas
Exemplo: [1,2,3]

product_tags

Obrigatório somente quando type == product-tags
Exemplo: ["tag1","tag2"]

collection_ids

Obrigatório somente quando type == collections
Exemplo: [1,2,3]

apply_for_variants

Determina se os descontos podem ser configurados por variante
Valores aceitos: true ou false
Valor padrão: false

h. exclude_product

Define os produtos a serem excluídos da regra.

Estrutura:

"exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
}

type

Padrão: none
Valores aceitos:

Valor	Descrição
`none`	Não exclui nenhum produto
`products`	Exclui produtos específicos
`collections`	Exclui coleções específicas

Os demais campos são obrigatórios apenas conforme o type selecionado.

i. discount_for_variants

Define a configuração de desconto no nível de produto e/ou de variante.

Deixe este campo vazio se apply_product.apply_for_variants == false.
Se apply_product.apply_for_variants == true, este campo é obrigatório.
A estrutura deve ser um array de configurações de produto.

Estrutura:

"discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variant_pricing": true,
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
]

i.1. id (obrigatório)

ID do produto.
Deve corresponder a um produto existente.

i.2. duplicated

Indica se o produto tem várias faixas de quantidade/valor.

Valores aceitos:

true
false

Regras:

Se true: o produto contém várias faixas de quantidade/valor.
Se false: o produto tem apenas uma faixa de quantidade/valor.

i.3. from_qty / from_amount

Quantidade ou valor inicial da faixa.

Regras:

O primeiro item pode ficar vazio (o padrão é 1).
Todos os itens seguintes são obrigatórios.

i.4. to_qty / to_amount

Quantidade ou valor final da faixa.

Regras:

Pode ficar vazio (será calculado automaticamente como o valor de from do próximo item menos 1).
Se informado, deve ser menor que o valor de from do próximo item.

Exemplos:

Item 1: from:0 – to:10 → Item 2: from:11 – to:20
Item 1: from:0 – to:em branco → Item 2: from:10 – to:em branco
Item 1: from:em branco – to:10 → Item 2: from:11 – to:em branco

i.5. discount_groups (nível de produto)

Define a configuração de desconto de cada faixa de quantidade/valor no nível de produto.

Obrigatório se variant_pricing == false.
Deixe vazio se variant_pricing == true.
Deve ser um array de objetos de desconto correspondente ao apply_customer.type configurado.

Estrutura:

{
    "name": "all",
    "type": "percent",
    "value": "10"
}

+ name

Valores aceitos:

all (se apply_customer.type == all)
logged (se apply_customer.type == logged)
non-logged (se apply_customer.type == non-logged)

Se outro valor for informado, ele será tratado como uma tag de cliente e deve corresponder a uma das tags definidas em apply_customer.tags.

+ type

Define o tipo de desconto.

Valores aceitos:

percent – Desconto percentual
amount – Valor fixo deduzido do preço
fixed-amount – Preço final fixo

+ value

Deve ser um número
Deve ser maior que 0
Se type == percent, o valor deve ser menor que 100

i.6. variant_pricing

Indica se o desconto é aplicado no nível de variante.

Valores aceitos:

true
false

i.7. variants

Define a configuração de desconto no nível de variante.

Obrigatório se variant_pricing == true
Deixe vazio se variant_pricing == false
Deve ser um array de configurações de variante

Estrutura:

{
  "id": 46747346763943,
  "duplicated": false,
  "from_qty": "0",
  "from_amount": "0",
  "to_qty": "10",
  "to_amount": "0",
  "discount_groups": [
    {
      "name": "all",
      "type": "percent",
      "value": "10"
    }
  ]
}

+ id (obrigatório)

ID da variante.

+ duplicate

Indica se a variante tem várias faixas de quantidade/valor.

Valores aceitos:

true
false

Regras:

Se true: a variante contém várias faixas.
Se false: a variante tem apenas uma faixa.

+ from_qty / from_amount

Quantidade ou valor inicial.

Regras:

O primeiro item pode ficar vazio (o padrão é 1).
Todos os itens seguintes são obrigatórios.

+ to_qty / to_amount

Quantidade ou valor final.

Regras:

Pode ficar vazio (calculado automaticamente como o from do próximo item menos 1).
Se informado, deve ser menor que o valor de from do próximo item.

Exemplos:

Item 1: from:0 – to:10 → Item 2: from:11 – to:20
Item 1: from:0 – to:em branco → Item 2: from:10 – to:em branco
Item 1: from:em branco – to:10 → Item 2: from:11 – to:em branco

+ discount_groups (nível de variante)

Define a configuração de desconto por faixa de quantidade/valor no nível de variante.

Regras:

Se apply_customer.type for:
- all
- logged
- non-logged
  → O array deve conter apenas um item.
Se apply_customer.type == customer-tags
→ O array deve conter vários itens (um por tag de cliente).

name

Valores aceitos:

all
logged
non-logged

Se outro valor for informado, ele será tratado como uma tag de cliente e deve corresponder a uma tag definida em apply_customer.tags.

type

Valores aceitos:

percent
amount
fixed-amount

value

Deve ser um número
Deve ser maior que 0
Se type == percent, o valor deve ser menor que 100

j. apply_market (obrigatório)

Define a quais mercados da Shopify a regra se aplica.

Estrutura:

"apply_market": {
    "type": "all",
    "handle": []
}

type

Valores aceitos:

all
specific-market

handle

Obrigatório somente quando type == specific-market
Lista de handles de mercados separados por vírgulas
Exemplo: ["japan","us"]

Para obter o handle do mercado, faça o seguinte:

No admin da Shopify, acesse a seção Mercados > clique em Mais ações > escolha Editar handles de mercado > copie o handle exibido ali:

k. discount_methods (obrigatório)

Valores aceitos:

variant → Same Variant
across_group → Mix Variants
within_each_group → Mix Products

Eles correspondem às opções disponíveis no app.

Exemplo:

"discount_method": "variant",

l. discount_group (obrigatório)

Define as faixas de quantidade/valor e os valores de desconto.

from_qty / from_amount

to_qty / to_amount

Mesmas regras de validação descritas acima.

Valores de “type” aceitos:

percent
amount
fixed-amount

value:

Deve ser > 0
Se percent → deve ser < 100

Estrutura:

"discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],

As regras são as mesmas descritas acima para os tipos e valores de desconto.

m. active_date

Usado para configurar o início e o fim da regra de preço.

Estrutura:

"active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10:00:00"
}

types

Opcional
Valores aceitos: start_date, end_date
Pode incluir um ou ambos, separados por vírgula
Exemplo: ["start_date","end_date"]

start_at

Obrigatório se types incluir start_date
Formato: YYYY-MM-DD HH:MM:SS

end_at

Obrigatório se types incluir end_date
Formato: YYYY-MM-DD HH:MM:SS

4. Resposta da API

a. Respostas de erro

401 – Unauthorized

Possíveis motivos:

URL da loja ausente
Chave de API ausente
URL da loja inválida
Chave de API inválida
A chave de API não corresponde à loja

403 – This action is unauthorized

A chave de API não tem a permissão Create
Cada chave de API pode ter as permissões: View, Create, Update, Delete
Esta API exige a permissão Create
Também é retornado quando um ID informado não existe

429 – Too Many Requests

Limite de requisições excedido
Máximo permitido:

Limite	Valor
Frequência de requisições	1 requisição a cada 5 minutos
Limite diário	50 requisições por dia

b. Resposta de sucesso

200 – API Success

Registro de Volume Pricing criado com sucesso
Resposta retornada em formato JSON

{
  "id": 1,
  "title": "New Volume Pricing",
  "status": true,
  "type": "quantity",
  "apply_customer": {
    "type": "all",
    "tags": []
  },
  "exclude_customer": {
    "type": "none",
    "tags": []
  },
  "apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
  },
  "exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
  },
  "discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_method": "variant",
  "discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],
  "active_date": {
    "types": [],
    "start_at": "",
    "end_at": ""
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

Isso foi útil?