Contents
On this page

Till Redeem - Plugixa PDF Vouchers for WooCommerce

POST /plugixa-pdf-vouchers/v1/pos/redeem

Charge a voucher from a till. Every redemption carries your own reference. If the till loses the answer and sends the same request again, the first result comes back with replayed true and nothing is charged twice. Use a new reference for every new payment.

Needs a user with the plugixa_pdfv_redeem capability (signed in with an Application Password, or the login cookie with an X-WP-Nonce header). Administrators and shop managers get it when the plugin is activated; see Staff access. The Pro Voucher staff role has it.

Note. Pro only: on the free plugin this route answers 404 rest_no_route.

Request

POST https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/pos/redeem

Request body

Content type: application/json

Field Type Required Description
code string Yes The code as printed or scanned.
amount number Yes More than 0, at most the balance, in the voucher’s currency.
reference string Yes Your unique id for this payment: 4 to 64 characters, letters, digits, ., _, : and -.
location string No Which shop or till, for the voucher’s history.
{
  "code": "PX-GHMR-PKT5",
  "amount": 20,
  "reference": "till1-20261120-0042",
  "location": "Paris, till 1"
}

Responses

201 Created. The redemption was made.

{
  "success": true,
  "data": {
    "transaction_id": 812,
    "amount": 20,
    "replayed": false,
    "voucher": {
      "code": "PX-GHMR-PKT5",
      "kind": "mpv",
      "status": "active",
      "currency": "EUR",
      "balance": 36,
      "expires_at": "2027-10-21 12:39:17",
      "usable": true,
      "reason": ""
    }
  }
}
Field Type Meaning
data.transaction_id integer The history line written, source pos
data.amount number The amount taken off
data.replayed boolean true when this answers an earlier identical request
data.voucher object The voucher after the charge, fields as in Till Balance

200 OK. A repeat of a reference already charged: the first result, with replayed true.

Errors

Status Code When
401 / 403 plugixa_pdfv_forbidden The caller lacks the capability.
400 rest_invalid_param reference does not match the allowed form, or a required field is missing.
404 plugixa_pdfv_unknown Unknown code: This voucher code is not valid.
422 plugixa_pdfv_expired The voucher has expired: This voucher has expired.
422 plugixa_pdfv_empty Nothing is left on it: This voucher has no balance left. or This voucher has already been used.
422 plugixa_pdfv_pending It is not active yet, for example a physical card not shipped: This voucher is not active yet.
422 plugixa_pdfv_void It was voided: This voucher is no longer valid.
422 plugixa_pdfv_invalid_amount amount is not more than 0.
422 plugixa_pdfv_insufficient amount is more than the balance: The voucher does not have enough balance for that.
409 plugixa_pdfv_busy The same reference is being handled by another request right now: The same request is already being handled. Try again.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/pos/redeem" \
  -u "$WP_USER:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"code":"PX-GHMR-PKT5","amount":20,"reference":"till1-20261120-0042","location":"Paris, till 1"}'
<?php
$ch = curl_init('https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/pos/redeem');
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([
        'code'      => 'PX-GHMR-PKT5',
        'amount'    => 20,
        'reference' => 'till1-20261120-0042',
        'location'  => 'Paris, till 1',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
const response = await fetch('https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/pos/redeem', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${btoa(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`)}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ code: 'PX-GHMR-PKT5', amount: 20, reference: 'till1-20261120-0042', location: 'Paris, till 1' }),
});
const { data } = await response.json();

Quick Links

Share