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_uuidper 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 withmeta.replayed: trueand status200instead 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