Contents
On this page
REST API - Plugixa PDF Vouchers for WooCommerce
The plugin’s admin screens, the balance check on your shop and the Pro scan screen all work
through one REST namespace, plugixa-pdf-vouchers/v1. You can call the same routes yourself: to
sell vouchers from another system, redeem them from a till, or read the figures into your
accounting. Every permission the screens enforce is checked again at the endpoint.
This reference lists 47 endpoints. Routes marked PRO exist only when Pro is
installed; on the free plugin they answer 404 rest_no_route.
Base URL
https://your-store.example/wp-json/plugixa-pdf-vouchers/v1
On a site with plain permalinks, pass the route as a parameter instead:
https://your-store.example/?rest_route=/plugixa-pdf-vouchers/v1/vouchers
Every voucher sold online comes from a real WooCommerce order. The routes below add what WooCommerce does not know: the vouchers, their history, their designs 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, a till 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 |
| A visitor | Nothing | The public routes: Check Balance, Resend My Vouchers and the signed links |
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-store.example/wp-json/plugixa-pdf-vouchers/v1/vouchers?per_page=5" \
-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.
For a till, create a user that can do nothing else: with Pro, give it the Voucher staff role, which can look vouchers up and redeem them. To cut a till off, revoke its password; other tills keep working. See Plugixa POS and tills.
Cookie and nonce
The admin app uses the visitor’s login cookie and sends 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.
Signed links
The PDF link in a voucher email, and the Pro Add to Apple Wallet and Save to Google Wallet
links, need no sign-in. They carry two query values the plugin adds when it makes the link:
expires, a Unix time, and sig, a signature of the voucher and that time made with your site’s
secret keys. A link that is changed, expired, or made for a code that has since changed stops
working. Links in emails last 180 days; links shown in My Account are made fresh on each visit and
last one day.
Get a fresh PDF link from pdf_url in Get Voucher.
Public routes
Check Balance and
Resend My Vouchers are
open to anyone, so they protect themselves: a limit per visitor, a lock after too many wrong codes,
and for the resend a hidden field that must stay empty. The visitor’s address is stored only as a
hash. The plugixa_pdfv_public_request_captcha filter lets you add a CAPTCHA check to both. See
Hooks.
Capabilities
Each route checks one capability. They are ordinary WordPress capabilities: the plugin gives them
to administrators and WooCommerce shop managers when it is activated, and any role editor can
grant them to other roles. A user with manage_options always holds every one. See
Staff access.
| Capability | Allows |
|---|---|
plugixa_pdfv_view |
Reading vouchers, the dashboard, designs, settings and batches PRO |
plugixa_pdfv_redeem |
Looking a voucher up by code and redeeming it, service sessions PRO, the till routes PRO |
plugixa_pdfv_create |
Creating vouchers and designs, bulk codes PRO. With edit_shop_orders, refunds as store credit PRO |
plugixa_pdfv_edit |
Changing vouchers and designs, balance adjustments, resending, service bookings PRO |
plugixa_pdfv_delete |
Voiding vouchers, archiving designs |
plugixa_pdfv_export |
Reports and exports PRO |
plugixa_pdfv_manage_settings |
Saving settings, and with Pro the activity log, fonts, text message and wallet settings |
Changing delete_data_on_uninstall with
Update Settings also needs
manage_options. Each endpoint page names the capability it needs.
Responses
Most successful responses are wrapped the same way:
{
"success": true,
"data": { "id": 26, "code": "PX-GHMR-PKT5", "balance": 56 },
"meta": { "total": 95 }
}
meta is only present when it has something in it. Some routes answer otherwise, and their pages
say so: the public routes put their fields next to success, the Pro bulk routes return a plain
object or list, and the PDF, CSV and wallet routes send a file.
Money is a number in the voucher’s own currency (56, 12.5), never in cents. Every voucher
keeps the currency it was sold in, given in its currency field.
Dates of the plugin’s records are UTC, written 2026-11-20 10:31:05. Dates you send as a day
(2027-06-30) mean the end of that day. The report routes take and return your store’s calendar
days.
Lists and pagination
List Vouchers and
List Activity PRO take
page (from 1) and per_page, and give the number of matches in meta.total. Other lists return
everything at once.
Version checks
A voucher carries a version that goes up on every change. Send it back with
Update Voucher: if somebody
changed the voucher since you read it, the save is refused with 409 plugixa_pdfv_conflict
instead of overwriting their change.
Money moves never need it: a redemption or an adjustment is checked against the balance at the moment it is written, inside a database transaction, so two tills can never spend the same euro twice.
Retries from a till
Till Redeem PRO and
Till Refund PRO take your
own reference. Sending the same request again after a timeout returns the first result with
replayed: true and charges nothing more. While the first request is still running, a second one
with the same reference answers 409 plugixa_pdfv_busy: wait a moment and send it again.
Errors
An error answers with an HTTP status and a body like this:
{
"code": "plugixa_pdfv_insufficient",
"message": "The voucher does not have enough balance for that.",
"data": { "status": 422 }
}
message is written for a person and is translated with the plugin. Test code in your code.
Every endpoint can also return:
| Status | Code | When |
|---|---|---|
401 |
plugixa_pdfv_forbidden |
Not signed in |
401 |
incorrect_password |
WordPress refused the Application Password |
403 |
plugixa_pdfv_forbidden |
Signed in without the capability: You are not allowed to do that. |
400 |
rest_invalid_param |
A parameter has the wrong type or form |
400 |
rest_missing_callback_param |
A required parameter is missing |
404 |
rest_no_route |
The route does not exist, for example a Pro route on the free plugin |
500 |
internal_server_error |
A PHP error. Check the site’s error log |
Endpoints
Not covered here
The plugin registers a few more routes for its own screens: the admin app’s start data
(/bootstrap, /meta/entities, /users), the setup wizard (/setup), and with Pro the scan
screen’s app files (/pwa/...), the buyer’s photo and preview on the product page (/photo,
/buyer-preview) and the voucher form block’s product list (/voucher-products). They may change
between versions without notice: do not build on them.
Related
Quick Links
Share