Criar preços de atacado usando APIs

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

Este documento explica como criar uma nova regra de preços de atacado usando a API pública.

1. Endpoint

Para criar um novo registro de preços de atacado, use o seguinte endpoint:

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

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 os preços de atacado devem ser enviados em formato JSON.
Um exemplo de estrutura JSON está no final deste documento.

Exemplo de JSON da requisição:

{
  "title": "New Wholesale Pricing",
  "status": true,
  "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,
      "variant_pricing": true,
      "variants": [
        {
          "id": 46747346763943,
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_group": {
    "type": "percent",
    "value": "10"
  },
  "active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10:00:00"
  }
}

b. title (obrigatório)

O nome usado para identificar o registro de preços de atacado
Deve ser uma string
Comprimento 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. 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 – Aplicar a todos os clientes
logged – Aplicar apenas a clientes com login
non-logged – Aplicar apenas a clientes visitantes
customer-tags – Aplicar apenas a clientes com tags específicas

tags

Obrigatório apenas 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.

e. 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 excluir nenhum cliente
`customer-tags`	Excluir clientes por tags

tags

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

f. 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 apenas quando type == products
Lista de IDs de produtos separados por vírgulas
Exemplo: [1,2,3]

product_tags

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

collection_ids

Obrigatório apenas 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

g. exclude_product

Define os produtos que serão 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 excluir nenhum produto
`products`	Excluir produtos específicos
`collections`	Excluir coleções específicas

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

h. discount_for_variants

Usado ao aplicar descontos por variante.

Deve estar vazio se apply_product.apply_for_variants == false
Obrigatório quando apply_product.apply_for_variants == true

Exemplo de estrutura:

"discount_for_variants": [
  {
    "id": 8516448190631,
    "variant_pricing": true,
    "variants": [
      {
        "id": 46747346763943,
        "discount_groups": [
          {
            "name": "all",
            "type": "percent",
            "value": "10"
          }
        ]
      }
    ]
  }
]

Estrutura:

Array de produtos
Cada produto contém:
- id – ID do produto
- variant_pricing – Deve ser true
- variants – Array de variantes

Cada variante inclui:

id – ID da variante
discount_groups – Array de configurações de desconto

Regras de discount_groups

Se apply_customer.type for all, logged ou non-logged:
→ Só é permitido um item no array
Se apply_customer.type == customer-tags:
→ É possível informar vários grupos de desconto

Campos dentro de discount_groups:

Campo	Descrição
`name`	Deve corresponder ao tipo de cliente ou à tag de cliente
`type`	Tipo de desconto
`value`	Valor do desconto

Tipos de desconto aceitos:

percent
amount
fixed-amount

Regras do valor:

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

i. 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 apenas quando type == specific-market
Lista de handles de mercado separados por vírgulas
Exemplo: ["japan","us"]

Para obter o handle do mercado, siga estes passos:

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

j. discount_group

Usado quando o desconto não é configurado por variante.

Obrigatório quando:

apply_product.type não for products, OU
apply_product.type == products E as variantes não forem aplicadas

Estrutura:

"discount_group": {
    "type": "percent",
    "value": "10"
}

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

k. active_date

Usado para configurar o horário de início e de término 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 – Não autorizado

Motivos possíveis:

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 – Esta ação não é autorizada

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

429 – Excesso de requisições

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 – Sucesso da API

Registro de preços de atacado criado com sucesso
Resposta retornada em formato JSON

{
  "id": 1,
  "title": "New Wholesale Pricing",
  "status": true,
  "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,
      "variant_pricing": true,
      "variants": [
        {
          "id": 46747346763943,
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_group": {
    "type": "percent",
    "value": "10"
  },
  "active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10:00:00"
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

Isso foi útil?