/bff/voucher/restore-usage

BIZKIT-19 — reverses a single voucher usage: removes the (voucher, order) row from shop__order_voucher, decrements the voucher counter (floor 0), reverses any free-credit top-up this voucher produced on that order, and records the operator identity + reason in the activity log. Idempotent for already-restored attachments.

VoucherpostBffVoucherRestore-usage

Parameters

JSON body

Request body

application/json

codestringRequired

Voucher code to restore. Must belong to the authenticated organisation.

ExamplePRVNI20

orderIdnumberRequired

Internal id of the order whose voucher attachment should be removed.

reasonstringOptional

Free-form reason recorded verbatim in the audit activity entry. Strongly recommended so the ledger explains why the usage was undone. The admin UI MUST force a confirm dialog before calling this endpoint.

Response schema

1 status code documented

200SuccessRestore result.

successbooleanRequired

Always true when no exception was raised.

codestringRequired

Canonical voucher code.

orderIdnumberRequired

Order id the restore ran against.

wasAttachedbooleanRequired

True when a (voucher, order) row existed and was removed. False means the restore was idempotent (nothing to undo).

usedCountBeforenumberRequired

Voucher used_count before the restore.

usedCountAfternumberRequired

Voucher used_count after the restore.

creditReversalobjectRequired

Outcome of the free-credit reversal step.

reversedbooleanRequired

True when a negative credit record was inserted.

creditAmountnumberOptional

Original positive credit amount (now reversed).

creditAmountMoneynumberOptional

Original positive credit money value (now reversed).

reasonSkippedstringOptional

Explanation why no reversal happened (only present when reversed=false). Values: attachment-not-found | voucher-type-does-not-generate-credit | no-credit-record-found.

Response example

application/json

{
  "success": false,
  "code": "example_code",
  "orderId": 0,
  "wasAttached": false,
  "usedCountBefore": 0,
  "usedCountAfter": 0,
  "creditReversal": {
    "reversed": false,
    "creditAmount": 0,
    "creditAmountMoney": 0,
    "reasonSkipped": "example_reasonSkipped"
  }
}

Request example

POST /bff/voucher/restore-usage

post

curl -X POST "https://api.bizkithub.com/bff/voucher/restore-usage" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "code": "PRVNI20",
  "orderId": 0,
  "reason": "example_reason"
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key