Aggiorna/Modifica Volume Pricing con le API

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

Questo documento spiega come aggiornare una regola Volume Pricing esistente con la Public API.

1. Endpoint

Per aggiornare un record Volume Pricing esistente, usa il seguente endpoint:

PUT https://wholesale.samita.io/api/v1/volume-pricings/{id}

{id} è l’ID del record Volume Pricing
L’ID si ottiene dall’interfaccia dell’app (senza il simbolo «#»)
Esempio di riferimento:

Esempio:

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

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

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

_ Nella richiesta servono solo i campi da aggiornare. Non è obbligatorio inviare tutti i campi come nel metodo API Create.

_ I campi non specificati rimangono invariati

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

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

c. status

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

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

Valori accettati:

quantity
amount

e. apply_customer

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

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,
      "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"
            }
          ]
        }
      ]
    }
  ],

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: 0–10 → Elemento 2: 11–20
Elemento 1: 0–vuoto → Elemento 2: 10–vuoto
Elemento 1: vuoto–10 → Elemento 2: 11–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: 0–10 → Elemento 2: 11–20
Elemento 1: 0–vuoto → Elemento 2: 10–vuoto
Elemento 1: vuoto–10 → Elemento 2: 11–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

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"]

k. discount_methods

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

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 Update
Ogni chiave API può avere le autorizzazioni View, Create, Update, Delete
Questa API richiede l’autorizzazione Update
Viene restituito anche quando l’ID indicato non esiste

429 – Too Many Requests

Limite di frequenza superato:

Massimo 1 richiesta ogni 5 minuti
Massimo 50 richieste al giorno

b. Risposta di successo

200 – API Success

Record Volume Pricing aggiornato correttamente
Response returned in JSON format

Esempio di JSON della risposta:

{
  "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?