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.

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.

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

Resource Endpoints
Vouchers List Vouchers, Create Voucher, Get Voucher, Update Voucher, Look Up Voucher by Code, Redeem Voucher, Adjust Voucher Balance, Void Voucher, Resend Voucher Email
Dashboard Get Dashboard
PDF designs List PDF Designs, Get PDF Design, Create PDF Design, Update PDF Design, Archive PDF Design, Preview PDF Design
PDF download Download Voucher PDF
Settings Get Settings, Update Settings
Storefront Check Balance, Resend My Vouchers
Service vouchers PRO Use Service Session, Note Service Booking
Till PRO Till Balance, Till Redeem, Till Refund
Reports PRO Get Report, Export Report, Get Vendor Settlement
Bulk codes PRO Generate Codes, Import Codes, List Batches, Export Batch
Store credit PRO Refund as Store Credit
Activity log PRO List Activity
Fonts PRO List Fonts, Upload Font, Delete Font
Text messages PRO Get Text Message Settings, Save Text Message Settings, Send Test Message
Wallet passes PRO Download Apple Wallet Pass, Open Google Wallet Card, Get Wallet Settings, Save Wallet Settings, Upload Wallet Key, Forget Wallet Keys

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.

  • Hooks: run your own PHP code inside WordPress when something happens to a voucher.
  • Webhooks PRO: have voucher events sent to another system instead of asking for them.

Quick Links

Share