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.

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

Resource Endpoints
Register setup Get Register Bootstrap, Save Favourites
Catalogue List Products, List Categories, Look Up Barcode, List Catalogue Changes
Customers Search Customers, Create Customer
Sales Price Cart, Create Sale, List Sales, Get Receipt, Print Duplicate, Email Receipt, Refund Sale
Held sales List Held Sales, Hold Sale, Resume Held Sale
Cash sessions Get Current Session, Open Session, Add Cash Movement, Get Session Report, Close Session, List Sessions
Invoices PRO Issue Invoice, List Sale Invoices, List Invoices, Download Invoice PDF
Fiscal journal Read Journal, Verify Journal, List Closings, Read Audit Log
Stores and registers Get Store, Update Store, List Registers, Create Register PRO, Update Register, List Stores PRO, Create Store PRO, Archive or Restore Store PRO, List Store Staff PRO, Set Store Staff PRO
Dashboard Get Dashboard
Settings Get Settings, Update Settings, Get App Bootstrap, List POS Users
Gift cards PRO Look Up Gift Card, List Gift Cards, Get Gift Card, Adjust Gift Card, Set Gift Card Expiry, Enable or Disable Gift Card
Store credit PRO List Store Credit, Get Store Credit Balance, Get Store Credit History, Adjust Store Credit
Loyalty PRO List Loyalty Members, Get Loyalty Balance, Get Loyalty History, Adjust Loyalty Points
Promotions PRO List Promotions, Create Promotion, Get Promotion Options, Update Promotion, Delete Promotion
Modifiers PRO List Modifier Groups, Create Modifier Group, Update Modifier Group, Delete Modifier Group
Bundles PRO List Bundles, Create Bundle, Update Bundle, Remove Bundle
Layaways PRO List Layaways, Start Layaway, Get Layaway, Pay Layaway, Cancel Layaway
Quotes PRO List Quotes, Create Quote, Get Quote, Cancel Quote, Download Quote PDF
Returns and exchanges PRO Get Refundable Items, Price Return, Return Items, Exchange Items
Receipt templates PRO List Receipt Templates, Create Receipt Template, Update Receipt Template, Delete Receipt Template, Assign Receipt Template
Invoice designer PRO Get Invoice Layout, Save Invoice Layout, Preview Invoice Layout
Store stock PRO List Store Stock, Update Store Stock
Stock adjustments PRO List Stock Adjustments, Adjust Stock
Transfers PRO List Transfers, Create Transfer, Send Transfer, Cancel Transfer, Receive Transfer
Suppliers PRO List Suppliers, Create Supplier, Update Supplier, List Supplier Products, Set Supplier Product, Remove Supplier Product
Purchase orders PRO List Purchase Orders, Create Purchase Order, Get Purchase Order, Update Purchase Order, Place Purchase Order, Receive Purchase Order, Close Purchase Order, Cancel Purchase Order
Supplier returns PRO List Supplier Returns, Create Supplier Return, Get Supplier Return, Send Supplier Return, Cancel Supplier Return
Purchasing tools PRO Get Reorder Suggestions, List Product Costs, Set Product Cost
Serial numbers PRO List Serial Numbers, Receive Serial Numbers, Update Serial Number, Delete Serial Number, List Serial-Tracked Products, Track Serial Numbers, Check Serial Number
Lots PRO List Lots, Receive Lot, Write Off Lot, Trace Lot, List Lot-Tracked Products, Track Lots
Staff PRO List Cashiers, List Staff, Set PIN, Clear PIN, Switch Cashier, Lock Register, Unlock Register, Approve Override
Reports PRO Get Sales Report, Get Staff Report, Set Commission Rates
Webhooks PRO List Webhooks, Create Webhook, Update Webhook, Delete Webhook, Rotate Webhook Secret, Test Webhook, List Webhook Deliveries, Retry Failed Deliveries, Retry Delivery
Stripe Terminal PRO Get Stripe Terminal Setup, Save Stripe Keys, Add Stripe Reader, Assign Stripe Reader, Get Register Reader, Start Card Payment, Get Card Payment Status, Cancel Card Payment, Simulate Card Tap, List Unmatched Card Payments, Refund Unmatched Card Payment, Stripe Webhook
Adyen Terminal PRO Get Adyen Terminal Setup, Save Adyen Account, List Adyen Terminals, Assign Adyen Terminal, Get Register Terminal, Start Adyen Payment, Get Adyen Payment Status, Cancel Adyen Payment, Simulate Adyen Payment
Pay by link PRO Get Pay by Link Setup, Save Pay by Link Provider, Create Payment Link, Get Payment Link Status, Cancel Payment Link, Adyen Pay by Link Webhook
Customer display PRO Pair Customer Display, Push Display State, Read Display State
Offline sales PRO List Sales Needing Attention, Resolve Attention
French fiscal PRO Get French Fiscal Status, Save Business Identity, List Fiscal Archives, Create Fiscal Archive, Enroll Fiscal Device, Get Fiscal Device

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.completed or register.closed to your URL, signed with X-Plugixa-Signature. Manage them with the Webhooks routes above; see Webhooks.
  • Incoming PRO: Stripe posts to /stripe-terminal/webhook and 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