Contents
On this page
Exchange Items - Plugixa POS for WooCommerce
POST /plugixa-pos/v1/orders/{id}/exchange
Return items and sell others in one transaction. The returned value pays the new sale as Exchange credit; any credit left over is paid back with pay_back, and any balance due is paid with the new sale’s payments.
Needs a user with the plugixa_pos_sell capability (signed in with an Application Password, or the login cookie with an X-WP-Nonce header). Administrators hold it; other roles only when you grant it. It also needs plugixa_pos_refund. The user must also be allowed to use the register (register access).
Request
POST https://your-site.example/wp-json/plugixa-pos/v1/orders/4460/exchange
Path parameters
| Name | Type | Description |
|---|---|---|
id |
integer |
The order’s id |
Request body
Content type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
register_id |
integer |
Yes | The register, with an open session. |
lines |
object[] |
Yes | 1 to 500 rows: item_id (the order line, from Get Refundable Items) and qty. |
restock |
boolean |
No | Put returned items back in stock. Defaults to true. |
pay_back |
string |
No | Payment method for credit left over. Defaults to cash. Not a foreign cash method. |
sale |
object |
Yes | The new sale: client_uuid, lines (product_id, variation_id, qty, discount, options), payments for any balance, expected_total (send the new sale’s total: the credit applied is worked out from it), customer_id, cart_discount, note. |
{
"register_id": 1,
"lines": [
{
"item_id": 8989,
"qty": 1
}
],
"pay_back": "cash",
"sale": {
"client_uuid": "9d8c7b6a-5f4e-4d3c-2b1a-0f9e8d7c6b5a",
"lines": [
{
"product_id": 3800,
"variation_id": 3801,
"qty": 1
}
],
"expected_total": "25.00",
"payments": []
}
}
Responses
201 Created, or 200 with meta.replayed: true for a resent client_uuid.
{
"success": true,
"data": {
"order_id": 4464,
"order_number": "4464",
"ticket": 319,
"date": "November 19, 2026 3:12 pm",
"store": {
"name": "Maison Plugixa Marais",
"address": {
"address_1": "12 rue des Archives",
"city": "Paris",
"postcode": "75004",
"country": "FR",
"address_2": ""
},
"phone": "",
"tax_id": "FR 40 123 456 789"
},
"register": "R1",
"cashier": "Emma Laurent",
"customer": "Camille Martin",
"currency": "EUR",
"lines": [
{
"name": "Canvas tote - Natural",
"options": [],
"qty": 1,
"subtotal": "25.00",
"total": "25.00"
},
{
"name": "Greeting card",
"options": [],
"qty": 1,
"subtotal": "4.00",
"total": "4.00"
}
],
"discount": "0.00",
"coupons": [],
"taxes": [
{
"label": "TVA",
"rate": "20%",
"amount": "4.83"
}
],
"tax_total": "4.83",
"total": "29.00",
"payments": [
{
"method": "cash",
"label": "Cash",
"amount": "30.00"
}
],
"tendered": "30.00",
"change": "1.00",
"fiscal": {
"hash_short": "EC60-5CEF",
"software": "Plugixa POS 1.0.0"
},
"header": "Maison Plugixa\n12 rue des Archives, 75004 Paris",
"footer": "Exchanges within 30 days with this receipt.\nThank you and see you soon!",
"refunded": "0.00",
"status": "completed",
"exchange": {
"of": 4460,
"credit": "27.00",
"applied": "25.00",
"paid_back": "2.00",
"refund_ticket": 323
}
},
"meta": {
"replayed": false
}
}
| Field | Type | Meaning |
|---|---|---|
data.exchange.of |
integer |
The original sale |
data.exchange.credit |
string |
Value of the returned items |
data.exchange.applied |
string |
Credit used on the new sale |
data.exchange.paid_back |
string |
Credit paid back |
data.exchange.refund_ticket |
integer |
Ticket of the refund |
Errors
| Status | Code | When |
|---|---|---|
404 |
plugixa_pos_not_found |
Not a register order. |
403 |
plugixa_pos_register_forbidden |
The register is missing or archived, or the user may not use it. |
422 |
plugixa_pos_invalid_sale |
The new sale has no client_uuid or no valid lines. |
422 |
plugixa_pos_invalid_payment |
A payment is not valid, or pay_back is not allowed. |
403 |
plugixa_pos_discount_forbidden |
A discount without plugixa_pos_discount. |
409 |
plugixa_pos_total_changed |
expected_total differs from the new sale’s total. |
Plus the errors every endpoint can return.
Examples
curl -s -X POST "https://your-site.example/wp-json/plugixa-pos/v1/orders/4460/exchange" \
-u "$WP_USER:$WP_APP_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"register_id":1,"lines":[{"item_id":8989,"qty":1}],"pay_back":"cash","sale":{"client_uuid":"9d8c7b6a-5f4e-4d3c-2b1a-0f9e8d7c6b5a","lines":[{"product_id":3800,"variation_id":3801,"qty":1}],"expected_total":"25.00","payments":[]}}'
<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-pos/v1/orders/4460/exchange');
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([
'register_id' => 1,
'lines' => [
[
'item_id' => 8989,
'qty' => 1,
],
],
'pay_back' => 'cash',
'sale' => [
'client_uuid' => '9d8c7b6a-5f4e-4d3c-2b1a-0f9e8d7c6b5a',
'lines' => [
[
'product_id' => 3800,
'variation_id' => 3801,
'qty' => 1,
],
],
'expected_total' => '25.00',
'payments' => [],
],
]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
const response = await fetch('https://your-site.example/wp-json/plugixa-pos/v1/orders/4460/exchange', {
method: 'POST',
headers: {
'Authorization': `Basic ${btoa(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`)}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ register_id: 1, lines: [{ item_id: 8989, qty: 1 }], pay_back: 'cash', sale: { client_uuid: '9d8c7b6a-5f4e-4d3c-2b1a-0f9e8d7c6b5a', lines: [{ product_id: 3800, variation_id: 3801, qty: 1 }], expected_total: '25.00', payments: [] } }),
});
const { data } = await response.json();
Quick Links
Share