Contents
On this page

Create Promotion - Plugixa POS for WooCommerce

POST /plugixa-pos/v1/promotions

Add a promotion. The register applies it by itself to matching sales.

Needs a user with the plugixa_pos_manage_settings capability (signed in with an Application Password, or the login cookie with an X-WP-Nonce header). Administrators hold it; other roles only when you grant it.

Request

POST https://your-site.example/wp-json/plugixa-pos/v1/promotions

Request body

Content type: application/json

Field Type Required Description
name string Yes Printed on the receipt.
type string Yes item_discount, quantity_break, buy_x_get_y or cart_threshold.
active boolean No On or off.
priority integer No Priority, a whole number. Defaults to 0.
all boolean No Every product. Otherwise give products or categories (not needed for cart_threshold).
products integer[] No Product ids.
categories integer[] No Category ids.
value_type string No percent (default) or fixed. buy_x_get_y takes percent only (100 = free).
value number|string Yes A whole percent from 1 to 100, or for fixed a decimal amount such as "5.00".
min_qty integer No quantity_break: from this many, 2 or more.
buy integer No buy_x_get_y: how many to buy.
get integer No buy_x_get_y: how many get the discount.
min_total string No cart_threshold: the amount the sale must reach, decimal.
roles string[] No Only customers with these WordPress roles.
starts_at string|null No YYYY-MM-DD HH:MM, shop time.
ends_at string|null No YYYY-MM-DD HH:MM, after starts_at.
days integer[] No Week days, 1 (Monday) to 7 (Sunday).
time_from string|null No HH:MM, start of the daily window.
time_to string|null No HH:MM, end of the daily window.
{
  "name": "Candles 2+1 free",
  "type": "buy_x_get_y",
  "active": true,
  "categories": [123],
  "value_type": "percent",
  "value": 100,
  "buy": 2,
  "get": 1
}

Responses

201 Created. data is the promotion.

{
  "success": true,
  "data": {
    "id": 4,
    "name": "Candles 2+1 free",
    "type": "buy_x_get_y",
    "active": true,
    "priority": 0,
    "all": false,
    "products": [],
    "categories": [123],
    "value_type": "percent",
    "value": 100,
    "min_qty": 0,
    "buy": 2,
    "get": 1,
    "min_total": 0,
    "roles": [],
    "starts_at": null,
    "ends_at": null,
    "days": [],
    "time_from": null,
    "time_to": null,
    "product_names": {}
  }
}

Errors

Status Code When
422 plugixa_pos_promotion_invalid A rule is broken: no name, unknown type, a percent outside 1 to 100, no products or categories, a quantity break below 2, an end before the start. The message says which.
500 plugixa_pos_promotion_save The promotion could not be saved.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-pos/v1/promotions" \
  -u "$WP_USER:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name":"Candles 2+1 free","type":"buy_x_get_y","active":true,"categories":[123],"value_type":"percent","value":100,"buy":2,"get":1}'
<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-pos/v1/promotions');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => getenv('WP_USER') . ':' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'name'       => 'Candles 2+1 free',
        'type'       => 'buy_x_get_y',
        'active'     => true,
        'categories' => [123],
        'value_type' => 'percent',
        'value'      => 100,
        'buy'        => 2,
        'get'        => 1,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
const response = await fetch('https://your-site.example/wp-json/plugixa-pos/v1/promotions', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${btoa(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`)}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Candles 2+1 free', type: 'buy_x_get_y', active: true, categories: [123], value_type: 'percent', value: 100, buy: 2, get: 1 }),
});
const { data } = await response.json();

Quick Links

Share