Contents
On this page

Create Sale - Plugixa POS for WooCommerce

POST /plugixa-pos/v1/orders

Sell: the cart becomes a paid WooCommerce order (created via plugixa-pos), stock goes down, a ticket number is given and the sale is written to the register’s fiscal journal. The answer is the receipt.

Needs a user with the plugixa_pos_sell 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. The user must also be allowed to use the register (register access). Custom items, a cart discount or a line discount also need plugixa_pos_discount.

Note. Send a fresh client_uuid per sale and keep it until you have an answer. If the request is sent twice (a network retry, an offline queue), the second one returns the first sale with meta.replayed: true and status 200 instead of selling twice.

Request

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

Request body

Content type: application/json

Field Type Required Description
client_uuid string Yes Your id for this sale: 16 to 64 hex digits and dashes, such as a UUID.
register_id integer Yes The register. It needs an open cash session.
customer_id integer No The customer. Defaults to 0 (walk-in).
note string No Order note.
expected_total string No The total the register showed. If the server’s total differs, the sale is refused with plugixa_pos_total_changed.
cart_discount object|null No Discount on the whole cart: type percent or fixed, and value (whole percent, or minor units).
coupons string[] No WooCommerce coupon codes, up to 10.
payments object[] Yes 1 to 20 payments: method (an id from the bootstrap’s payment_methods), amount (decimal string), reference (optional, up to 64 characters).
context object|null No Up to 10 extra values (text, numbers or booleans), handed with the sale to checkout filters such as plugixa_pos_checkout_policy.
offline object|null No A sale made offline PRO: sold_at (ISO 8601) and fiscal.
lines object[] Yes 1 to 500 lines. Each line:
lines[].product_id integer Yes The product. 0 with custom for a custom item.
lines[].variation_id integer No The variation of a variable product.
lines[].qty integer Yes 1 to 100000.
lines[].discount object|null No Line discount: type percent (whole percent) or fixed (minor units for the whole line, 500 is 5.00), and value.
lines[].custom object|null No A custom item: name (1 to 120 characters), price (decimal string), tax_class (slug, optional). Needs plugixa_pos_discount.
lines[].note string No Line note, up to 200 characters.
lines[].options string[] No Modifier option keys PRO, up to 50.
lines[].serials string[] No Serial numbers sold PRO.
lines[].label_code string No A scale label code, 8 to 14 digits PRO.
lines[].ref string No A reference set by Pro features, such as a quote line (quote:12:0).
{
  "client_uuid": "6f1c2b7e-3a7d-4c39-9f0e-2d5b8c4a1e90",
  "register_id": 1,
  "customer_id": 88,
  "expected_total": "29.00",
  "lines": [
    {
      "product_id": 3800,
      "variation_id": 3801,
      "qty": 1
    },
    {
      "product_id": 3835,
      "qty": 1
    }
  ],
  "payments": [
    {
      "method": "cash",
      "amount": "30.00"
    }
  ]
}

Responses

201 Created. data is the receipt.

{
  "success": true,
  "data": {
    "order_id": 4464,
    "order_number": "4464",
    "ticket": 319,
    "date": "November 19, 2026 3:12 pm",
    "store": {
      "name": "Maison Plugixa Marais",
      "address": {
        "address_1": "12 rue des Archives",
        "city": "Paris",
        "postcode": "75004",
        "country": "FR",
        "address_2": ""
      },
      "phone": "",
      "tax_id": "FR 40 123 456 789"
    },
    "register": "R1",
    "cashier": "Emma Laurent",
    "customer": "Camille Martin",
    "currency": "EUR",
    "lines": [
      {
        "name": "Canvas tote - Natural",
        "options": [],
        "qty": 1,
        "subtotal": "25.00",
        "total": "25.00"
      },
      {
        "name": "Greeting card",
        "options": [],
        "qty": 1,
        "subtotal": "4.00",
        "total": "4.00"
      }
    ],
    "discount": "0.00",
    "coupons": [],
    "taxes": [
      {
        "label": "TVA",
        "rate": "20%",
        "amount": "4.83"
      }
    ],
    "tax_total": "4.83",
    "total": "29.00",
    "payments": [
      {
        "method": "cash",
        "label": "Cash",
        "amount": "30.00"
      }
    ],
    "tendered": "30.00",
    "change": "1.00",
    "fiscal": {
      "hash_short": "EC60-5CEF",
      "software": "Plugixa POS 1.0.0"
    },
    "header": "Maison Plugixa\n12 rue des Archives, 75004 Paris",
    "footer": "Exchanges within 30 days with this receipt.\nThank you and see you soon!",
    "refunded": "0.00",
    "status": "completed"
  },
  "meta": {
    "replayed": false
  }
}
Field Type Meaning
data.order_id integer The WooCommerce order id
data.order_number string The order number
data.ticket integer The register’s ticket number
data.date string Sale date in the site’s date and time format
data.store object Store name, address, phone, tax_id
data.register string Register code
data.cashier string Who sold
data.customer string Customer name, empty for a walk-in sale
data.lines object[] name, options, qty, subtotal and total per line
data.discount string Discount on the sale
data.coupons object[] Coupons used
data.taxes object[] label, rate, amount per tax rate
data.tax_total string Tax
data.total string Total
data.payments object[] method, label, amount per payment
data.tendered string Money handed over
data.change string Change given
data.fiscal object hash_short (short form of the fiscal journal hash) and software
data.header string Receipt header from the settings
data.footer string Receipt footer from the settings
data.refunded string Amount refunded so far
data.status string WooCommerce order status

200 OK. The same client_uuid was already sold.

data is the receipt of the first sale and meta.replayed is true. Nothing new is recorded.

Errors

Status Code When
404 plugixa_pos_no_register No register with that id.
403 plugixa_pos_register_forbidden The register is missing or archived, or the user may not use it.
409 plugixa_pos_session_closed The register has no open cash session.
403 plugixa_pos_discount_forbidden A discount without plugixa_pos_discount.
403 plugixa_pos_custom_forbidden A custom item without plugixa_pos_discount.
409 plugixa_pos_total_changed expected_total differs from the server’s total. data.total is the server’s.
409 plugixa_pos_out_of_stock Not enough stock for a line. data.line is its index.
409 plugixa_pos_line_invalid A line cannot be sold. data.line is its index.
409 plugixa_pos_in_progress The same client_uuid is being processed right now. Try again in a moment.
422 plugixa_pos_underpaid The payments do not cover the total.
422 plugixa_pos_invalid_payment Unknown payment method, or an amount of zero.
422 plugixa_pos_overpaid_card A card payment is more than the amount due.
422 plugixa_pos_coupon_and_discount A coupon is combined with a register discount.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-pos/v1/orders" \
  -u "$WP_USER:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"client_uuid":"6f1c2b7e-3a7d-4c39-9f0e-2d5b8c4a1e90","register_id":1,"customer_id":88,"expected_total":"29.00","lines":[{"product_id":3800,"variation_id":3801,"qty":1},{"product_id":3835,"qty":1}],"payments":[{"method":"cash","amount":"30.00"}]}'
<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-pos/v1/orders');
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([
        'client_uuid'    => '6f1c2b7e-3a7d-4c39-9f0e-2d5b8c4a1e90',
        'register_id'    => 1,
        'customer_id'    => 88,
        'expected_total' => '29.00',
        'lines'          => [
            [
                'product_id'   => 3800,
                'variation_id' => 3801,
                'qty'          => 1,
            ],
            [
                'product_id' => 3835,
                'qty'        => 1,
            ],
        ],
        'payments'       => [
            [
                'method' => 'cash',
                'amount' => '30.00',
            ],
        ],
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
const response = await fetch('https://your-site.example/wp-json/plugixa-pos/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${btoa(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`)}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ client_uuid: '6f1c2b7e-3a7d-4c39-9f0e-2d5b8c4a1e90', register_id: 1, customer_id: 88, expected_total: '29.00', lines: [{ product_id: 3800, variation_id: 3801, qty: 1 }, { product_id: 3835, qty: 1 }], payments: [{ method: 'cash', amount: '30.00' }] }),
});
const { data } = await response.json();

Quick Links

Share