Contents
On this page
REST API - Plugixa POS for WooCommerce
The register at /pos and the back-office app both work through one REST namespace,
plugixa-pos/v1. You can call the same routes yourself: to read sales into another system,
manage stock from a script, or build your own front end. Every permission the screens enforce is
checked again at the endpoint, not only in the page.
This reference lists 198 endpoints. Routes that come from Pro PRO (multi-store,
stock, purchasing, gift cards, loyalty, card terminals, French fiscal rules and the rest) exist only
when Pro is installed. On the free plugin they answer 404 rest_no_route.
Base URL
https://your-site.example/wp-json/plugixa-pos/v1
On a site with plain permalinks, pass the route as a parameter instead:
https://your-site.example/?rest_route=/plugixa-pos/v1/products
Every sale is a real WooCommerce order. You can also read register orders with the WooCommerce REST API; the routes below add what WooCommerce does not know: registers, cash sessions, tickets, the fiscal journal and the Pro features.
Authentication
The plugin has no API keys of its own. A request runs as a WordPress user.
| Caller | How it signs in | What it reaches |
|---|---|---|
| A script or another server | An Application Password, with HTTP Basic authentication | What the user’s capabilities allow |
| A page on the same site | The login cookie plus an X-WP-Nonce header |
The same |
| Nobody | Nothing | Only the public routes: the customer display PRO and the Stripe and Adyen webhook receivers PRO |
Application Passwords
Create one under Users > Profile > Application Passwords for the WordPress user the script should act as, then send it with HTTP Basic authentication:
curl -s "https://your-site.example/wp-json/plugixa-pos/v1/sessions/current?register_id=1" \
-u "$WP_USER:$WP_APP_PASSWORD"
Application Passwords are a WordPress feature, not the plugin’s: WordPress offers them on sites served over HTTPS, and a security plugin or host can switch them off.
Cookie and nonce
The register and the admin app use the visitor’s login cookie and send the REST nonce in an
X-WP-Nonce header; WordPress checks the nonce before the route runs. Without the header, a
cookie request is treated as signed out.
Two Pro routes only make sense with a browser login session: Switch Cashier refuses a request signed with an Application Password, and the till lock of Lock Register belongs to the login session.
Public routes
Three Pro routes need no sign-in and check their own credential instead: the customer display reads
its state with its pairing code, and the Stripe and Adyen receivers check the provider’s signature.
They are rate limited per IP address: 240 calls a minute for the display, 600 for each receiver.
Over the limit they answer 429 plugixa_pos_rate_limited. The address is stored only as a hash.
Capabilities
Each route checks one capability. They are ordinary WordPress capabilities: the plugin gives them to administrators when it is activated, and any role editor can grant them to other roles. See Staff access.
| Capability | Allows |
|---|---|
plugixa_pos_sell |
The register: catalogue, customers, sales, held sales, receipts, invoices of a sale PRO, and the selling side of Pro features |
plugixa_pos_discount |
Discounts and custom items in a sale or a quote |
plugixa_pos_refund |
Refunds, returns PRO, cancelling a layaway PRO |
plugixa_pos_manage_sessions |
Opening and closing cash sessions, cash in and out, offline sales to check PRO |
plugixa_pos_view_reports |
The dashboard, the list of sessions, reports PRO |
plugixa_pos_fiscal_audit |
The fiscal journal, closings, verification, audit log, fiscal archives PRO |
plugixa_pos_manage_settings |
Stores, registers, settings, and the back-office side of Pro features: stock, gift cards, promotions, terminals, webhooks |
plugixa_pos_view |
The admin app’s start data, the settings, the user list and the invoice list PRO |
plugixa_pos_purchase PRO |
Suppliers, purchase orders, supplier returns, costs. Pro gives it to administrators and to the WooCommerce Shop manager role |
plugixa_pos_create, plugixa_pos_edit, plugixa_pos_delete and plugixa_pos_export also exist
but no route of version 1.0.0 asks for them. A user with WordPress’s manage_options holds every
capability above. Each endpoint page names the capability it needs.
A few routes ask for more:
| Route | Also needs |
|---|---|
| Create Sale with a discount or a custom item | plugixa_pos_discount |
Update Settings when it changes delete_data_on_uninstall |
manage_options |
| Exchange Items PRO | plugixa_pos_sell and plugixa_pos_refund |
| Refund Unmatched Card Payment PRO | plugixa_pos_manage_settings and plugixa_pos_refund |
Manager approval
With Pro, a cashier who lacks plugixa_pos_discount or plugixa_pos_refund can get a manager’s
approval for one request: Approve Override
returns a one-time token, valid 5 minutes, that you send in an X-Plugixa-Override header with
the request it unlocks.
Register access
Routes that act on a register (selling, sessions, terminals) also check that the user may use that register:
- The register must exist and be
active. An archived register cannot be used. - With Pro multi-store, a user assigned to one or more stores may only use those stores’
registers. A user assigned to no store may use every register, and so may anyone with
plugixa_pos_manage_settings. See Multi-store.
A refusal answers 403 plugixa_pos_register_forbidden. The Pro terminal, pay-link and quote
routes answer the same refusal as 403 plugixa_pos_forbidden.
Many register routes also need an open cash session on the register, and answer 409
plugixa_pos_session_closed without one. See Cash sessions.
Responses
Every successful JSON response is wrapped the same way:
{
"success": true,
"data": { "id": 85, "register_id": 1, "status": "open" },
"meta": { "total": 85, "pages": 43 }
}
meta is only present when it has something in it. A few routes answer otherwise:
Download Invoice PDF PRO and
Download Quote PDF PRO send the PDF
itself, a 304 with no body can come back from the catalogue routes, and the Adyen pay-by-link
receiver PRO answers the text [accepted].
Amounts are decimal strings in the shop’s currency ("29.00"), as WooCommerce writes them. Some
fields are integers in minor units (cents) instead, and each endpoint page says so: a cash
session’s opening_float and difference, discount value of type fixed in a sale, and the
value and min_total of a fixed promotion PRO.
Dates are not all in one form; each endpoint page shows which it uses:
| Form | Used by |
|---|---|
UTC, 2026-11-19 14:20:11 |
Records of the plugin’s own tables: sessions, held sales, journal, transfers, purchase orders |
ISO 8601 with offset, 2026-11-19T14:01:52+01:00 |
WooCommerce orders and products |
The site’s date format, November 19, 2026 3:12 pm |
The date printed on a receipt |
The audit log and the closings return some numbers as strings, the way the database stores them.
Lists and pagination
Paged lists take page (from 1) and per_page. The default and the maximum differ from one list to
another, and each endpoint page gives them. Totals are in meta.total and meta.pages, not in
headers. A per_page above the maximum is refused with 400 rest_invalid_param.
Some lists are not paged and say so: the fiscal journal pages with after_seq instead, and lists
such as stores, promotions or webhooks return everything at once.
Catalogue caching
List Products and
List Categories send an ETag. Send it
back in If-None-Match and an unchanged answer is a 304 with no body. To keep a copy of the
catalogue current, poll List Catalogue Changes
with the cursor you were given, and reload only the products it names.
Retries and concurrency
A till must survive a network that drops a request after the server has done the work. The routes that take money are safe to send again:
| Route | Your id | A second send |
|---|---|---|
| Create Sale | client_uuid |
Returns the first sale, 200, meta.replayed: true |
| Pay Layaway PRO | client_uuid |
Same |
| Exchange Items PRO | sale.client_uuid |
Same |
| Card terminal and pay-link starts PRO | attempt_id |
Does not start a second charge |
While the first request is still running, a second one with the same id answers 409
plugixa_pos_in_progress: wait a moment and send it again. Two registers paying the same layaway
at once get the same answer.
Prices can change between the cart and the payment. Send expected_total with a sale: if the
server’s total differs, the sale is refused with 409 plugixa_pos_total_changed, and
data.total holds the new total.
The plugin also contains a check that refuses a save made from a stale copy of a record (409
plugixa_pos_conflict, comparing the modified_at you send). No route of version 1.0.0 uses it.
Locked register
With Pro, a cashier can lock the till with Lock Register.
Until it is unlocked with a PIN, every route of the namespace answers 423
plugixa_pos_register_locked for that login session, except
Unlock Register,
Switch Cashier and
List Cashiers. Five wrong PINs lock PIN
checks for that user, or from that address, for 15 minutes.
Endpoints
Registers and the details of a store are edited in the free plugin; the list of stores, new stores and staff assignments come with Pro multi-store.
Webhooks
Two kinds, not to be confused:
- Outgoing PRO: the Webhooks module posts events such as
sale.completedorregister.closedto your URL, signed withX-Plugixa-Signature. Manage them with the Webhooks routes above; see Webhooks. - Incoming PRO: Stripe posts to
/stripe-terminal/webhookand Adyen to/pay-links/adyen/webhook. Each delivery is checked against the provider’s signature.
To react to the plugin’s events in PHP instead, use its hooks.
Errors
Errors use the standard WordPress shape:
{
"code": "plugixa_pos_session_closed",
"message": "Open a cash session before selling.",
"data": { "status": 409 }
}
Some errors add fields to data: line (the index of the cart line at fault), total, field
or min. Each endpoint page lists its own errors. These can come back from any endpoint:
| Status | Code | When |
|---|---|---|
401 |
plugixa_pos_forbidden |
Signed out. |
403 |
plugixa_pos_forbidden |
Signed in, but the user lacks the capability. |
403 |
plugixa_pos_register_forbidden |
The user may not use this register. See Register access. |
404 |
plugixa_pos_not_found |
No such record, or one the user may not reach. |
409 |
plugixa_pos_session_closed |
The register has no open cash session. |
423 |
plugixa_pos_register_locked |
The till is locked PRO. See Locked register. |
429 |
plugixa_pos_rate_limited |
Too many calls to a public route from one address. |
401 |
incorrect_password |
WordPress refused the Application Password. Other WordPress sign-in codes are possible. |
403 |
rest_cookie_invalid_nonce |
Cookie sign-in with a stale nonce. |
404 |
rest_no_route |
No such route or method, or a Pro route on the free plugin. |
400 |
rest_invalid_param |
A declared parameter failed validation, for example per_page above the maximum. |
400 |
rest_missing_callback_param |
A required parameter is missing. |
Extending the API
| Hook | Use |
|---|---|
plugixa_pos_register_rest_routes (action) |
Add your own routes beside the plugin’s. It passes the namespace and the plugin’s service container |
plugixa_pos_filter_output (filter) |
Change any successful payload, with the kind of record it holds |
plugixa_pos_user_can_use_register (filter) |
Decide who may use which register |
plugixa_pos_register_bootstrap (filter) |
Add data to Get Register Bootstrap |
plugixa_pos_sync_interval (filter) |
Seconds between catalogue polls, 30 by default, 5 at least |
plugixa_pos_public_request_captcha (filter) |
Add an anti-bot check to the public routes |
plugixa_pos_client_ip (filter) |
The address public routes are limited by, for a site behind a proxy |
add_action( 'plugixa_pos_register_rest_routes', function ( string $namespace ) {
register_rest_route( $namespace, '/my-shop/open-registers', array(
'methods' => 'GET',
'callback' => 'my_shop_open_registers',
'permission_callback' => function () {
return current_user_can( 'plugixa_pos_view_reports' );
},
) );
} );
Version 1.0.0 also registers three routes for extensions, which have nothing to serve until a
plugin declares record types: GET /meta/entities (an empty list), GET /filters/{entity_type}
(404 plugixa_pos_unknown_entity) and POST /mass-action/{entity_type} (403). They are not
documented further here. See Hooks for the full set.
Troubleshooting
| Symptom | Usual cause |
|---|---|
401 from a script |
No Application Password sent, a wrong one, or the site is not on HTTPS. Some hosts strip the Authorization header before WordPress sees it. |
401 or 403 from the browser |
The nonce is missing or stale. Reload the page. |
403 plugixa_pos_forbidden for a cashier |
The role lacks the capability the route names, for example plugixa_pos_manage_sessions to open the register. |
403 plugixa_pos_register_forbidden |
The register is archived, or with Pro multi-store the user is assigned to another store. |
409 plugixa_pos_session_closed |
Open a cash session on the register first. |
409 plugixa_pos_total_changed |
A price changed while the cart was open. Show the new total and take payment again. |
404 on a route that should exist |
It is a Pro route and Pro is not installed. |
423 on every call |
The till was locked with Pro Staff. Unlock it with the PIN. |
See also
- How a sale works at the counter: Register.
- Opening, cash in and out, and the Z report: Cash sessions.
- What the journal records and how it is checked: Fiscal journal.
- Change behaviour in PHP instead: Hooks.
Quick Links
Share