Use Client Package Credit [Alpha]

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.

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.