Contents
On this page

Redeem Voucher - Plugixa PDF Vouchers for WooCommerce

POST /plugixa-pdf-vouchers/v1/vouchers/{id}/redeem

Spend part or all of a voucher in your shop, like Redeem on the voucher page. Writes a redeem line to its history. A product voucher with a limited number of uses closes as redeemed after its last use. A till that may send the same request twice should use Till Redeem PRO, which takes a reference and never charges twice.

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.

Request

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

Path parameters

Name Type Description
id integer The voucher’s id

Request body

Content type: application/json

Field Type Required Description
amount number Yes More than 0, at most the balance, in the voucher’s currency.
location string No Which shop or till, for the history.
note string No A note for the history.
source string No scan marks the line as made from the Pro scan screen. Anything else is admin.
{
  "amount": 12.5,
  "location": "Maison Willow, tea room"
}

Responses

200 OK. data is the voucher with its history, as in Get Voucher.

{
  "success": true,
  "data": {
    "id": 26,
    "code": "PX-GHMR-PKT5",
    "code_norm": "PXGHMRPKT5",
    "kind": "mpv",
    "status": "active",
    "currency": "EUR",
    "initial_amount": 150,
    "balance": 43.5,
    "uses_allowed": 0,
    "uses_count": 4,
    "product_id": 534,
    "variation_id": 0,
    "order_id": 563,
    "order_item_id": 459,
    "allowed_product_ids": [],
    "allowed_category_ids": [],
    "buyer_user_id": 65,
    "buyer_email": "lea.fontaine@example.com",
    "recipient_name": "Nadia Benali",
    "recipient_email": "nadia.benali@example.net",
    "from_name": "Léa",
    "message": "For the best mum in the world. Bonne fête des mères !",
    "template_id": 3,
    "locale": "en_US",
    "vendor_id": 0,
    "source": "order",
    "deliver_at": null,
    "delivered_at": "2026-10-21 12:39:57",
    "expires_at": "2027-10-21 12:39:17",
    "created_by": 0,
    "created_at": "2026-10-21 12:39:17",
    "updated_at": "2026-11-20 10:31:05",
    "version": 7,
    "batch": "",
    "recipient_phone": "",
    "meta": [],
    "is_expired": false,
    "order_url": "https://your-store.example/wp-admin/post.php?post=563&action=edit",
    "service": null,
    "transactions": [
      {
        "id": 26,
        "voucher_id": 26,
        "type": "issue",
        "amount": 100,
        "balance_after": 100,
        "order_id": 563,
        "ref_id": 0,
        "actor_user_id": 1,
        "source": "order",
        "location": "",
        "note": "",
        "meta": null,
        "created_at": "2026-10-21 12:39:17"
      },
      {
        "id": 95,
        "voucher_id": 26,
        "type": "redeem",
        "amount": -46,
        "balance_after": 54,
        "order_id": 611,
        "ref_id": 0,
        "actor_user_id": 0,
        "source": "order",
        "location": "",
        "note": "",
        "meta": null,
        "created_at": "2026-10-27 12:39:17"
      },
      {
        "id": 96,
        "voucher_id": 26,
        "type": "redeem",
        "amount": -16,
        "balance_after": 38,
        "order_id": 0,
        "ref_id": 0,
        "actor_user_id": 1,
        "source": "scan",
        "location": "Paris · Le Marais",
        "note": "",
        "meta": null,
        "created_at": "2026-10-30 12:39:17"
      },
      {
        "id": 97,
        "voucher_id": 26,
        "type": "redeem",
        "amount": -32,
        "balance_after": 6,
        "order_id": 612,
        "ref_id": 0,
        "actor_user_id": 0,
        "source": "order",
        "location": "",
        "note": "",
        "meta": null,
        "created_at": "2026-11-17 12:39:17"
      },
      {
        "id": 146,
        "voucher_id": 26,
        "type": "topup",
        "amount": 50,
        "balance_after": 56,
        "order_id": 0,
        "ref_id": 0,
        "actor_user_id": 1,
        "source": "topup",
        "location": "",
        "note": "Topped up by the buyer.",
        "meta": null,
        "created_at": "2026-11-18 16:11:43"
      },
      {
        "id": 189,
        "voucher_id": 26,
        "type": "redeem",
        "amount": -12.5,
        "balance_after": 43.5,
        "order_id": 0,
        "ref_id": 0,
        "actor_user_id": 7,
        "source": "admin",
        "location": "Maison Willow, tea room",
        "note": "",
        "meta": null,
        "created_at": "2026-11-20 10:31:05"
      }
    ],
    "deliveries": [
      {
        "id": "26",
        "channel": "email",
        "recipient": "nadia.benali@example.net",
        "status": "sent",
        "last_error": "",
        "sent_at": "2026-10-21 12:39:22",
        "created_at": "2026-10-21 12:39:22"
      }
    ],
    "pdf_url": "https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/pdf/26?expires=1795179133&sig=3526abd1d39101d6e51be3adadd7b17d97daea63af778a5b598a41f3000b8152&inline=1"
  }
}

Errors

Status Code When
401 / 403 plugixa_pdfv_forbidden The caller lacks the capability.
422 plugixa_pdfv_unknown No voucher with that id: 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.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/vouchers/26/redeem" \
  -u "$WP_USER:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"amount":12.5,"location":"Maison Willow, tea room"}'
<?php
$ch = curl_init('https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/vouchers/26/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([
        'amount'   => 12.5,
        'location' => 'Maison Willow, tea room',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
const response = await fetch('https://your-store.example/wp-json/plugixa-pdf-vouchers/v1/vouchers/26/redeem', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${btoa(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`)}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 12.5, location: 'Maison Willow, tea room' }),
});
const { data } = await response.json();

Quick Links

Share