Crea Volume Pricing con le API

Crea una nuova regola Volume Pricing con la Public API, con il riferimento completo del corpo della richiesta.

Questo documento spiega come creare una nuova regola Volume Pricing con la Public API.

1. Endpoint

Per creare un nuovo record Volume Pricing, usa il seguente endpoint:

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

Questo endpoint permette di creare una nuova configurazione Volume Pricing.

2. Intestazioni della richiesta

Tutte le richieste API devono includere le seguenti intestazioni obbligatorie:

Header	Descrizione	Obbligatorio
`X-SAMITA-API-KEY`	Chiave API fornita nell’app Wholesale	Sì
`X-SAMITA-SHOP-URL`	Dominio del negozio Shopify nel formato xxx.myshopify.com	Sì
`CONTENT-TYPE`	Deve essere `application/json`	Sì

Se manca un’intestazione obbligatoria, la richiesta viene rifiutata.

3. Corpo della richiesta

a. Formato generale

I dati usati per creare Volume Pricing devono essere inviati in formato JSON.
Un esempio di struttura JSON è riportato alla fine di questo documento.

Esempio di JSON della richiesta:

{
  "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 (obbligatorio)

Il nome usato per identificare il record Volume Pricing
Deve essere una stringa
Lunghezza massima: 255 caratteri

c. status (obbligatorio)

Definisce se il record è attivo o meno
Accetta solo i seguenti valori:

Valore	Descrizione
`true`	La regola di prezzo è attiva
`false`	La regola di prezzo non è attiva

d. type (obbligatorio)

Definisce se il prezzo per volume viene calcolato in base alla quantità o all’importo.

Valori accettati:

quantity
amount

e. apply_customer (obbligatorio)

Definisce quali clienti sono idonei a questa regola di prezzo.

Struttura:

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

type

Valori accettati (solo uno dei seguenti):

all: si applica a tutta la clientela
logged: si applica solo a chi ha effettuato l’accesso
non-logged: si applica solo a chi naviga come ospite
customer-tags: si applica solo alla clientela con tag specifici

tags

Obbligatorio solo quando type == customer-tags
Deve essere un array separato da virgole
Esempio: ["wholesale","b2b"]

Se type non è customer-tags, questo campo può essere ignorato.

f. exclude_customer

Usato per escludere determinate persone dalla regola di prezzo.

Struttura:

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

type

Valore predefinito: none
Valori accettati:

Valore	Descrizione
`none`	Non escludere nessuna persona
`customer-tags`	Escludi la clientela per tag

tags

Obbligatorio solo quando type == customer-tags
Array separato da virgole
Esempio: ["vip","internal"]

g. apply_product (obbligatorio)

Definisce a quali prodotti si applica la regola di prezzo.

Struttura:

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

type

Valori accettati:

all
products
collections
product-tags

product_ids

Obbligatorio solo quando type == products
Elenco di ID prodotto separati da virgole
Esempio: [1,2,3]

product_tags

Obbligatorio solo quando type == product-tags
Esempio: ["tag1","tag2"]

collection_ids

Obbligatorio solo quando type == collections
Esempio: [1,2,3]

apply_for_variants

Determina se gli sconti possono essere configurati per singola variante
Valori accettati: true o false
Valore predefinito: false

h. exclude_product

Definisce i prodotti da escludere dalla regola.

Struttura:

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

type

Predefinito: none
Valori accettati:

Valore	Descrizione
`none`	Non escludere nessun prodotto
`products`	Escludi prodotti specifici
`collections`	Escludi collezioni specifiche

Gli altri campi sono obbligatori solo in base al type selezionato.

i. discount_for_variants

Definisce la configurazione degli sconti a livello di prodotto e/o variante.

Lascia vuoto questo campo se apply_product.apply_for_variants == false.
Se apply_product.apply_for_variants == true, questo campo è obbligatorio.
La struttura deve essere un array di configurazioni di prodotto.

Struttura:

"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 (obbligatorio)

ID del prodotto.
Deve corrispondere a un prodotto esistente.

i.2. duplicated

Indica se il prodotto ha più fasce di quantità/importo.

Valori accettati:

true
false

Regole:

Se true: il prodotto contiene più fasce di quantità/importo.
Se false: il prodotto ha una sola fascia di quantità/importo.

i.3. from_qty / from_amount

Quantità o importo iniziale della fascia.

Regole:

Il primo elemento può essere vuoto (il valore predefinito è 1).
Tutti gli elementi successivi sono obbligatori.

i.4. to_qty / to_amount

Quantità o importo finale della fascia.

Regole:

Può essere vuoto (viene calcolato automaticamente come valore from dell’elemento successivo meno 1).
Se indicato, deve essere inferiore al valore from dell’elemento successivo.

Esempi:

Elemento 1: from:0 – to:10 → Elemento 2: from:11 – to:20
Elemento 1: from:0 – to:vuoto → Elemento 2: from:10 – to:vuoto
Elemento 1: from:vuoto – to:10 → Elemento 2: from:11 – to:vuoto

i.5. discount_groups (Product Level)

Definisce la configurazione dello sconto per ogni fascia di quantità/importo a livello di prodotto.

Obbligatorio se variant_pricing == false.
Lascia vuoto se variant_pricing == true.
Deve essere un array di oggetti sconto corrispondenti a apply_customer.type configurato.

Struttura:

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

+ name

Valori accettati:

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

Se viene indicato un altro valore, sarà trattato come tag cliente e deve corrispondere a uno dei tag definiti in apply_customer.tags.

+ type

Definisce il tipo di sconto.

Valori accettati:

percent: sconto percentuale
amount: importo fisso detratto dal prezzo
fixed-amount: prezzo fisso finale

+ value

Deve essere un numero
Deve essere maggiore di 0
Se type == percent, il valore deve essere inferiore a 100

i.6. variant_pricing

Indica se lo sconto viene applicato a livello di variante.

Valori accettati:

true
false

i.7. variants

Definisce la configurazione dello sconto a livello di variante.

Obbligatorio se variant_pricing == true
Lascia vuoto se variant_pricing == false
Deve essere un array di configurazioni di variante

Struttura:

{
  "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 (obbligatorio)

ID della variante.

+ duplicate

Indica se la variante ha più fasce di quantità/importo.

Valori accettati:

true
false

Regole:

Se true: la variante contiene più fasce.
Se false: la variante ha una sola fascia.

+ from_qty / from_amount

Quantità o importo iniziale.

Regole:

Il primo elemento può essere vuoto (il valore predefinito è 1).
Tutti gli elementi successivi sono obbligatori.

+ to_qty / to_amount

Quantità o importo finale.

Regole:

Può essere vuoto (calcolato automaticamente come from dell’elemento successivo meno 1).
Se indicato, deve essere inferiore al valore from dell’elemento successivo.

Esempi:

Elemento 1: from:0 – to:10 → Elemento 2: from:11 – to:20
Elemento 1: from:0 – to:vuoto → Elemento 2: from:10 – to:vuoto
Elemento 1: from:vuoto – to:10 → Elemento 2: from:11 – to:vuoto

+ discount_groups (Variant Level)

Definisce la configurazione dello sconto per ogni fascia di quantità/importo a livello di variante.

Regole:

Se apply_customer.type è:
- all
- logged
- non-logged
  → l’array deve contenere un solo elemento.
If apply_customer.type == customer-tags
→ l’array deve contenere più elementi (uno per ogni tag cliente).

name

Valori accettati:

all
logged
non-logged

Se viene indicato un altro valore, sarà trattato come tag cliente e deve corrispondere a un tag definito in apply_customer.tags.

type

Valori accettati:

percent
amount
fixed-amount

value

Deve essere un numero
Deve essere maggiore di 0
Se type == percent, il valore deve essere inferiore a 100

j. apply_market (obbligatorio)

Definisce a quali mercati Shopify si applica la regola.

Struttura:

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

type

Valori accettati:

all
specific-market

handle

Obbligatorio solo quando type == specific-market
Elenco di handle dei mercati separati da virgole
Esempio: ["japan","us"]

Per ottenere l’handle del mercato, procedi così:

Nella pagina di amministrazione Shopify, vai alla sezione Mercati > fai clic su Altre azioni > scegli Modifica handle dei mercati > copia l’handle mostrato:

k. discount_methods (obbligatorio)

Valori accettati:

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

Corrispondono alle opzioni disponibili nell’app.

Esempio:

"discount_method": "variant",

l. discount_group (obbligatorio)

Definisce le fasce di quantità/importo e i valori di sconto.

from_qty / from_amount

to_qty / to_amount

Stesse regole di convalida descritte sopra.

Valori “type” accettati:

percent
amount
fixed-amount

value:

Deve essere > 0
Se percent → deve essere < 100

Struttura:

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

Le regole sono le stesse descritte sopra per i tipi e i valori di sconto.

m. active_date

Usato per configurare l’ora di inizio e di fine della regola di prezzo.

Struttura:

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

types

Facoltativo
Valori accettati: start_date, end_date
Può includerne uno o entrambi, separati da virgola
Esempio: ["start_date","end_date"]

start_at

Obbligatorio se types include start_date
Formato: YYYY-MM-DD HH:MM:SS

end_at

Obbligatorio se types include end_date
Formato: YYYY-MM-DD HH:MM:SS

4. Risposta dell’API

a. Risposte di errore

401 – Unauthorized

Possibili motivi:

URL del negozio mancante
Chiave API mancante
URL del negozio non valido
Chiave API non valida
La chiave API non corrisponde al negozio

403 – This action is unauthorized

La chiave API non ha l’autorizzazione Create
Ogni chiave API può avere le autorizzazioni View, Create, Update, Delete
Questa API richiede l’autorizzazione Create
Viene restituito anche quando un ID indicato non esiste

429 – Too Many Requests

Limite di frequenza superato
Massimo consentito:

Limite	Valore
Frequenza delle richieste	1 richiesta ogni 5 minuti
Limite giornaliero	50 richieste al giorno

b. Risposta di successo

200 – API Success

Record Volume Pricing creato correttamente
Risposta restituita in 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"
}

Questa pagina ti è stata utile?