Overview

Reverse a previous package credit redemption, restoring the consumed credit back to the client's package. This is the undo operation for POST /platform/v1/payment/client_packages/update_usage.

Feature Requirement

Requires the booking_packages feature on the business. It belongs to the Payments module but is not part of every subscription, and is disabled by default on newly provisioned businesses — treat it as unavailable unless you have confirmed it is on for the specific business.

When the feature is off, the request is rejected with 403 Forbidden and this body:

{"message": "403 Forbidden", "status": "module_permission_missing"}

This is an entitlement check, not an authentication or permission failure. It is evaluated before the request body is validated and it fails identically for Staff, Directory and App tokens, so retrying, refreshing the token, or setting X-On-Behalf-Of will not change the outcome. The feature must be enabled for the business first. Related endpoints under /platform/v1/payment/packages and /platform/v1/payment/client_packages share the same gate.

Authentication

Available for Staff tokens. Directory and App tokens are supported with the X-On-Behalf-Of header set to the target business UID. Also available for Internal tokens.

How It Works

1. The system finds the PaymentStatus by the provided ID and locates the associated BookingCreditRedemption.
2. The bookings_usage counter on the relevant BookingCredit is decremented by one, making the credit available again.
3. The BookingCreditRedemption record is marked as inactive.
4. The PaymentStatus is reset to pending with the original price restored (no longer marked as paid-by-package).

Required Parameters

• payment_status_id (string) — The ID of the payment status whose package credit redemption should be reversed. Must reference a payment status that was previously paid via package credit.

Notes

• Returns 422 if the payment status was not paid via a package credit.
• This endpoint is in Alpha and may change.
• Use this when an appointment is cancelled or rescheduled and the client's package credit should be returned.