Créer une tarification par volume avec les API

Créez une règle de tarification par volume via l'API publique, avec la référence complète du corps de la requête.

Ce document explique comment créer une règle de tarification par volume avec l’API publique.

1. Point de terminaison

Pour créer un enregistrement de tarification par volume, utilisez le point de terminaison suivant :

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

Ce point de terminaison permet de créer une nouvelle configuration de tarification par volume.

2. En-têtes de la requête

Toutes les requêtes API doivent inclure les en-têtes obligatoires suivants :

En-tête	Description	Obligatoire
`X-SAMITA-API-KEY`	Clé API fournie dans l’application Wholesale	Oui
`X-SAMITA-SHOP-URL`	Domaine de la boutique Shopify au format xxx.myshopify.com	Oui
`CONTENT-TYPE`	Doit être `application/json`	Oui

Si un en-tête obligatoire est manquant, la requête est rejetée.

3. Corps de la requête

a. Format général

Les données utilisées pour créer une tarification par volume doivent être envoyées au format JSON.
Un exemple de structure JSON figure à la fin de ce document.

Exemple de JSON de requête :

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

Le nom qui identifie l’enregistrement de tarification par volume
Doit être une chaîne de caractères
Longueur maximale : 255 caractères

c. status (obligatoire)

Indique si l’enregistrement est actif ou non
Accepte uniquement les valeurs suivantes :

Valeur	Description
`true`	La règle de tarification est active
`false`	La règle de tarification est inactive

d. type (obligatoire)

Indique si la tarification par volume est calculée selon la quantité ou le montant.

Valeurs acceptées :

quantity
amount

e. apply_customer (obligatoire)

Définit les clients concernés par cette règle de tarification.

Structure :

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

type

Valeurs acceptées (une seule parmi les suivantes) :

all – S’applique à tous les clients
logged – S’applique uniquement aux clients connectés
non-logged – S’applique uniquement aux clients non connectés
customer-tags – S’applique uniquement aux clients ayant des tags spécifiques

tags

Obligatoire uniquement lorsque type == customer-tags
Doit être un tableau dont les éléments sont séparés par des virgules
Exemple : ["wholesale","b2b"]

Si type n’est pas customer-tags, ce champ peut être ignoré.

f. exclude_customer

Permet d’exclure certains clients de la règle de tarification.

Structure :

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

type

Valeur par défaut : none
Valeurs acceptées :

Valeur	Description
`none`	N’exclut aucun client
`customer-tags`	Exclut les clients par tags

tags

Obligatoire uniquement lorsque type == customer-tags
Tableau dont les éléments sont séparés par des virgules
Exemple : ["vip","internal"]

g. apply_product (obligatoire)

Définit les produits auxquels la règle de tarification s’applique.

Structure :

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

type

Valeurs acceptées :

all
products
collections
product-tags

product_ids

Obligatoire uniquement lorsque type == products
Liste d’ID de produits séparés par des virgules
Exemple : [1,2,3]

product_tags

Obligatoire uniquement lorsque type == product-tags
Exemple : ["tag1","tag2"]

collection_ids

Obligatoire uniquement lorsque type == collections
Exemple : [1,2,3]

apply_for_variants

Détermine si les réductions peuvent être configurées par variante
Valeurs acceptées : true ou false
Valeur par défaut : false

h. exclude_product

Définit les produits exclus de la règle.

Structure :

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

type

Par défaut : none
Valeurs acceptées :

Valeur	Description
`none`	N’exclut aucun produit
`products`	Exclut des produits spécifiques
`collections`	Exclut des collections spécifiques

Les autres champs ne sont obligatoires que selon le type sélectionné.

i. discount_for_variants

Définit la configuration des réductions au niveau du produit et/ou de la variante.

Laissez ce champ vide si apply_product.apply_for_variants == false.
Si apply_product.apply_for_variants == true, ce champ est obligatoire.
La structure doit être un tableau de configurations de produits.

Structure :

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

ID du produit.
Doit correspondre à un produit existant.

i.2. duplicated

Indique si le produit comporte plusieurs tranches de quantité ou de montant.

Valeurs acceptées :

true
false

Règles :

Si true : le produit comporte plusieurs tranches de quantité ou de montant.
Si false : le produit ne comporte qu’une seule tranche de quantité ou de montant.

i.3. from_qty / from_amount

Quantité ou montant de début de la tranche.

Règles :

Le premier élément peut être vide (1 par défaut).
Tous les éléments suivants sont obligatoires.

i.4. to_qty / to_amount

Quantité ou montant de fin de la tranche.

Règles :

Peut être vide (calculé automatiquement comme la valeur from de l’élément suivant moins 1).
S’il est indiqué, il doit être inférieur à la valeur from de l’élément suivant.

Exemples :

Élément 1 : from:0 – to:10 → Élément 2 : from:11 – to:20
Élément 1 : from:0 – to:vide → Élément 2 : from:10 – to:vide
Élément 1 : from:vide – to:10 → Élément 2 : from:11 – to:vide

i.5. discount_groups (niveau produit)

Définit la configuration des réductions pour chaque tranche de quantité ou de montant au niveau du produit.

Obligatoire si variant_pricing == false.
Laissez vide si variant_pricing == true.
Doit être un tableau d’objets de réduction correspondant à la valeur configurée de apply_customer.type.

Structure :

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

+ name

Valeurs acceptées :

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

Toute autre valeur est traitée comme un tag client et doit correspondre à l’un des tags définis dans apply_customer.tags.

+ type

Définit le type de réduction.

Valeurs acceptées :

percent – Réduction en pourcentage
amount – Montant fixe déduit du prix
fixed-amount – Prix fixe final

+ value

Doit être un nombre
Doit être supérieur à 0
Si type == percent, la valeur doit être inférieure à 100

i.6. variant_pricing

Indique si la réduction s’applique au niveau de la variante.

Valeurs acceptées :

true
false

i.7. variants

Définit la configuration des réductions au niveau de la variante.

Obligatoire si variant_pricing == true
Laissez vide si variant_pricing == false
Doit être un tableau de configurations de variantes

Structure :

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

ID de la variante.

+ duplicate

Indique si la variante comporte plusieurs tranches de quantité ou de montant.

Valeurs acceptées :

true
false

Règles :

Si true : la variante comporte plusieurs tranches.
Si false : la variante ne comporte qu’une seule tranche.

+ from_qty / from_amount

Quantité ou montant de début.

Règles :

Le premier élément peut être vide (1 par défaut).
Tous les éléments suivants sont obligatoires.

+ to_qty / to_amount

Quantité ou montant de fin.

Règles :

Peut être vide (calculé automatiquement comme la valeur from de l’élément suivant moins 1).
S’il est indiqué, il doit être inférieur à la valeur from de l’élément suivant.

Exemples :

Élément 1 : from:0 – to:10 → Élément 2 : from:11 – to:20
Élément 1 : from:0 – to:vide → Élément 2 : from:10 – to:vide
Élément 1 : from:vide – to:10 → Élément 2 : from:11 – to:vide

+ discount_groups (niveau variante)

Définit la configuration des réductions pour chaque tranche de quantité ou de montant au niveau de la variante.

Règles :

Si apply_customer.type vaut :
- all
- logged
- non-logged
  → Le tableau doit contenir un seul élément.
Si apply_customer.type == customer-tags
→ Le tableau doit contenir plusieurs éléments (un par tag client).

name

Valeurs acceptées :

all
logged
non-logged

Toute autre valeur est traitée comme un tag client et doit correspondre à un tag défini dans apply_customer.tags.

type

Valeurs acceptées :

percent
amount
fixed-amount

value

Doit être un nombre
Doit être supérieur à 0
Si type == percent, la valeur doit être inférieure à 100

j. apply_market (obligatoire)

Définit les marchés Shopify auxquels la règle s’applique.

Structure :

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

type

Valeurs acceptées :

all
specific-market

handle

Obligatoire uniquement lorsque type == specific-market
Liste de identifiants de marché séparés par des virgules
Exemple : ["japan","us"]

Pour obtenir l’identifiant du marché, procédez comme suit :

Dans l’admin Shopify, accédez à la section Marchés > cliquez sur Plus d’actions > choisissez Modifier les identifiants du marché > copiez l’identifiant affiché :

k. discount_methods (obligatoire)

Valeurs acceptées :

variant → Même variante
across_group → Mélange de variantes
within_each_group → Mélange de produits

Ces valeurs correspondent aux options disponibles dans l’application.

Exemple :

"discount_method": "variant",

l. discount_group (obligatoire)

Définit les tranches de quantité ou de montant et les valeurs de réduction.

from_qty / from_amount

to_qty / to_amount

Mêmes règles de validation que celles décrites plus haut.

Valeurs « type » acceptées :

percent
amount
fixed-amount

value :

Doit être > 0
Si percent → doit être < 100

Structure :

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

Les règles sont les mêmes que celles décrites plus haut pour les types et les valeurs de réduction.

m. active_date

Permet de configurer la date et l’heure de début et de fin de la règle de tarification.

Structure :

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

types

Facultatif
Valeurs acceptées : start_date, end_date
Peut contenir l’une des deux valeurs ou les deux, séparées par une virgule
Exemple : ["start_date","end_date"]

start_at

Obligatoire si types inclut start_date
Format : YYYY-MM-DD HH:MM:SS

end_at

Obligatoire si types inclut end_date
Format : YYYY-MM-DD HH:MM:SS

4. Réponse de l’API

a. Réponses d’erreur

401 – Non autorisé

Causes possibles :

URL de la boutique manquante
Clé API manquante
URL de la boutique non valide
Clé API non valide
La clé API ne correspond pas à la boutique

403 – Cette action n’est pas autorisée

La clé API n’a pas l’autorisation Create
Chaque clé API peut avoir les autorisations View, Create, Update et Delete
Cette API nécessite l’autorisation Create
Également renvoyée lorsque l’ID indiqué n’existe pas

429 – Trop de requêtes

Limite de débit dépassée
Maximum autorisé :

Limite	Valeur
Fréquence des requêtes	1 requête toutes les 5 minutes
Limite quotidienne	50 requêtes par jour

b. Réponse de succès

200 – Succès de l’API

L’enregistrement de tarification par volume a bien été créé
La réponse est renvoyée au format 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"
}

Cette page vous a-t-elle été utile ?