Overview

Redeem a credit from a client's active package to pay for an appointment or service session. This marks the associated payment status as paid (price set to $0) and decrements one credit from the client's package.

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.

How It Works

1. The system finds the PaymentStatus referenced by payment_status_uid, which links to a specific appointment/event and its service.
2. It searches for active client packages belonging to that client that have available credits for the service in question. A package is eligible when: valid_from <= now <= valid_until, active = true, and total_bookings > bookings_usage for a credit matching the service.
3. If multiple packages qualify, the soonest-expiring package is used first (ordered by valid_until ASC).
4. One credit is consumed: bookings_usage is incremented, a BookingCreditRedemption record is created, and the PaymentStatus is set to paid with a zero price.

Required Parameters

• payment_status_uid (string) — The UID of the payment status record to pay using a package credit. Must reference a pending/unpaid payment status linked to an appointment. Already-paid statuses return a 422 error.

Optional Parameters

• matter_uid (string) — The matter/conversation UID that scopes which client packages to search. If omitted, the system attempts to find the default matter for the client associated with the payment status.

Notes

• Returns 422 "There is no package to use" if no active client packages with available credits exist for the relevant service.
• Returns 422 if the payment status is already paid.
• This endpoint is in Alpha and may change.
• To reverse a credit redemption, use PUT /platform/v1/payment/client_packages/cancel_redemption.