--- updatedAt: 2026-05-12T21:33:18.000Z agentTools: projectIndex: https://developers.intandem.tech/llms.txt --- # 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. ## 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: ```json {"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`. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Sales", "description": "Unified OpenAPI specification for sales domain", "version": "3.0", "x-generated": { "sourceFiles": [ "payment_plans.json", "payments.json", "legacy_v1_sales.json", "payment_gateway.json", "legacy_v2_settings_services.json", "legacy_v2_settings_categories.json", "client_cards.json", "client_payment_cards.json", "sales_reports.json", "creditNote.json", "estimates.json", "coupons.json", "invoice.json", "coupon.json" ], "pathNormalizations": [ { "file": "payments.json", "basePath": "/business/payments", "transformations": [ { "original": "/v1/card_requests", "normalized": "/business/payments/v1/card_requests", "basePath": "/business/payments" }, { "original": "/v1/card_requests/{client_uid}", "normalized": "/business/payments/v1/card_requests/{client_uid}", "basePath": "/business/payments" }, { "original": "/v1/cards/{uid}", "normalized": "/business/payments/v1/cards/{uid}", "basePath": "/business/payments" }, { "original": "/v1/carts", "normalized": "/business/payments/v1/carts", "basePath": "/business/payments" }, { "original": "/v1/carts/{uid}", "normalized": "/business/payments/v1/carts/{uid}", "basePath": "/business/payments" }, { "original": "/v1/carts/{uid}/cancel", "normalized": "/business/payments/v1/carts/{uid}/cancel", "basePath": "/business/payments" }, { "original": "/v1/carts/{uid}/cart_completed", "normalized": "/business/payments/v1/carts/{uid}/cart_completed", "basePath": "/business/payments" }, { "original": "/v1/client_packages/{uid}", "normalized": "/business/payments/v1/client_packages/{uid}", "basePath": "/business/payments" }, { "original": "/v1/deposits", "normalized": "/business/payments/v1/deposits", "basePath": "/business/payments" }, { "original": "/v1/deposits/{uid}", "normalized": "/business/payments/v1/deposits/{uid}", "basePath": "/business/payments" }, { "original": "/v1/estimates", "normalized": "/business/payments/v1/estimates", "basePath": "/business/payments" }, { "original": "/v1/estimates/{estimate_uid}", "normalized": "/business/payments/v1/estimates/{estimate_uid}", "basePath": "/business/payments" }, { "original": "/v1/invoices", "normalized": "/business/payments/v1/invoices", "basePath": "/business/payments" }, { "original": "/v1/invoices/{invoice_uid}", "normalized": "/business/payments/v1/invoices/{invoice_uid}", "basePath": "/business/payments" }, { "original": "/v1/invoices/{invoice_uid}/cancel", "normalized": "/business/payments/v1/invoices/{invoice_uid}/cancel", "basePath": "/business/payments" }, { "original": "/v1/packages/reorder", "normalized": "/business/payments/v1/packages/reorder", "basePath": "/business/payments" }, { "original": "/v1/payment_requests", "normalized": "/business/payments/v1/payment_requests", "basePath": "/business/payments" }, { "original": "/v1/payment_requests/{payment_request_uid}/send_link", "normalized": "/business/payments/v1/payment_requests/{payment_request_uid}/send_link", "basePath": "/business/payments" }, { "original": "/v1/payment_requests/{payment_request_uid}", "normalized": "/business/payments/v1/payment_requests/{payment_request_uid}", "basePath": "/business/payments" }, { "original": "/v1/payments", "normalized": "/business/payments/v1/payments", "basePath": "/business/payments" }, { "original": "/v1/payments/{payment_uid}", "normalized": "/business/payments/v1/payments/{payment_uid}", "basePath": "/business/payments" }, { "original": "/v1/payouts", "normalized": "/business/payments/v1/payouts", "basePath": "/business/payments" }, { "original": "/v1/payouts/{provider_payout_id}", "normalized": "/business/payments/v1/payouts/{provider_payout_id}", "basePath": "/business/payments" }, { "original": "/v1/product_orders", "normalized": "/business/payments/v1/product_orders", "basePath": "/business/payments" }, { "original": "/v1/product_orders/{product_order_uid}", "normalized": "/business/payments/v1/product_orders/{product_order_uid}", "basePath": "/business/payments" }, { "original": "/v1/products", "normalized": "/business/payments/v1/products", "basePath": "/business/payments" }, { "original": "/v1/products/{product_uid}", "normalized": "/business/payments/v1/products/{product_uid}", "basePath": "/business/payments" }, { "original": "/v1/refunds", "normalized": "/business/payments/v1/refunds", "basePath": "/business/payments" }, { "original": "/v1/scheduled_payments_rules", "normalized": "/business/payments/v1/scheduled_payments_rules", "basePath": "/business/payments" }, { "original": "/v1/scheduled_payments_rules/{uid}/cancel", "normalized": "/business/payments/v1/scheduled_payments_rules/{uid}/cancel", "basePath": "/business/payments" }, { "original": "/v1/scheduled_payments_rules/{uid}", "normalized": "/business/payments/v1/scheduled_payments_rules/{uid}", "basePath": "/business/payments" }, { "original": "/v1/tax_bulk", "normalized": "/business/payments/v1/tax_bulk", "basePath": "/business/payments" }, { "original": "/v1/tax_bulk/apply_defaults", "normalized": "/business/payments/v1/tax_bulk/apply_defaults", "basePath": "/business/payments" }, { "original": "/v1/taxes", "normalized": "/business/payments/v1/taxes", "basePath": "/business/payments" }, { "original": "/v1/taxes/{tax_uid}", "normalized": "/business/payments/v1/taxes/{tax_uid}", "basePath": "/business/payments" }, { "original": "/v1/transactions", "normalized": "/business/payments/v1/transactions", "basePath": "/business/payments" }, { "original": "/v1/transactions/{provider_transaction_id}", "normalized": "/business/payments/v1/transactions/{provider_transaction_id}", "basePath": "/business/payments" } ] }, { "file": "legacy_v1_sales.json", "basePath": "/platform/v1", "transformations": [ { "original": "/leadgen", "normalized": "/platform/v1/leadgen", "basePath": "/platform/v1" }, { "original": "/payments", "normalized": "/platform/v1/payments", "basePath": "/platform/v1" }, { "original": "/payments/{payment_uid}", "normalized": "/platform/v1/payments/{payment_uid}", "basePath": "/platform/v1" }, { "original": "/payments/{payment_uid}/match", "normalized": "/platform/v1/payments/{payment_uid}/match", "basePath": "/platform/v1" }, { "original": "/invoices", "normalized": "/platform/v1/invoices", "basePath": "/platform/v1" }, { "original": "/invoices/{invoice_id}", "normalized": "/platform/v1/invoices/{invoice_id}", "basePath": "/platform/v1" }, { "original": "/payment/cards/sync_card", "normalized": "/platform/v1/payment/cards/sync_card", "basePath": "/platform/v1" }, { "original": "/payment/cards/{card_id}", "normalized": "/platform/v1/payment/cards/{card_id}", "basePath": "/platform/v1" }, { "original": "/payment/checkout/", "normalized": "/platform/v1/payment/checkout/", "basePath": "/platform/v1" }, { "original": "/payment/checkout/{url_key}", "normalized": "/platform/v1/payment/checkout/{url_key}", "basePath": "/platform/v1" }, { "original": "/payment/client_packages", "normalized": "/platform/v1/payment/client_packages", "basePath": "/platform/v1" }, { "original": "/payment/client_packages/cancel_redemption", "normalized": "/platform/v1/payment/client_packages/cancel_redemption", "basePath": "/platform/v1" }, { "original": "/payment/client_packages/update_usage", "normalized": "/platform/v1/payment/client_packages/update_usage", "basePath": "/platform/v1" }, { "original": "/payment/packages", "normalized": "/platform/v1/payment/packages", "basePath": "/platform/v1" }, { "original": "/payment/packages/{package_id}", "normalized": "/platform/v1/payment/packages/{package_id}", "basePath": "/platform/v1" }, { "original": "/payment/settings", "normalized": "/platform/v1/payment/settings", "basePath": "/platform/v1" }, { "original": "/payment/settings/update_default_currency", "normalized": "/platform/v1/payment/settings/update_default_currency", "basePath": "/platform/v1" }, { "original": "/payment_statuses/{id}/apply_coupon", "normalized": "/platform/v1/payment_statuses/{id}/apply_coupon", "basePath": "/platform/v1" }, { "original": "/payment_statuses/{id}/validate_coupon", "normalized": "/platform/v1/payment_statuses/{id}/validate_coupon", "basePath": "/platform/v1" }, { "original": "/services", "normalized": "/platform/v1/services", "basePath": "/platform/v1" }, { "original": "/services/availability", "normalized": "/platform/v1/services/availability", "basePath": "/platform/v1" }, { "original": "/services/{service_uid}", "normalized": "/platform/v1/services/{service_uid}", "basePath": "/platform/v1" }, { "original": "/services/{service_uid}/availability", "normalized": "/platform/v1/services/{service_uid}/availability", "basePath": "/platform/v1" } ] }, { "file": "estimates.json", "basePath": "/platform/v1", "transformations": [ { "original": "/estimates", "normalized": "/platform/v1/estimates", "basePath": "/platform/v1" } ] } ], "pathConflicts": [], "componentConflicts": [ { "type": "schema", "name": "ErrorResponse", "resolution": "Renamed to ErrorResponse_client_cards", "files": [ "merged", "client_cards.json" ] } ], "totalPaths": 86, "totalComponents": 11 } }, "servers": [ { "url": "https://api.vcita.biz", "description": "Unified API Gateway server" } ], "paths": { "/platform/v1/payment/client_packages/update_usage": { "post": { "parameters": [], "responses": { "200": { "description": "Client package credit updated using payment_status_id", "content": { "application/json": { "example": { "data": { "package_name": "Package Name" }, "status": "OK" } } } }, "403": { "description": "Forbidden - the business does not have the `booking_packages` feature enabled. Returns `{\"message\": \"403 Forbidden\", \"status\": \"module_permission_missing\"}`. Not an auth failure: no token type or retry will succeed until the feature is enabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "403 Forbidden" }, "status": { "type": "string", "example": "module_permission_missing" } } } } } }, "422": { "description": "Failure with payment_status_id", "content": { "application/json": { "example": { "error": "Error Message", "status": "Error" } } } } }, "summary": "Use Client Package Credit [Alpha]", "tags": [ "Client Packages" ], "x-amazon-apigateway-auth": { "type": "NONE" }, "x-amazon-apigateway-integration": { "httpMethod": "POST", "responses": { "default": { "statusCode": "200" } }, "type": "http_proxy", "uri": "https:///platform/v1/clients/payment/client_packages/update_usage" }, "x-auth-type": "Application & Application User", "description": "## Overview\nRedeem 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.\n\n## Feature Requirement\nRequires 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.\n\nWhen the feature is off, the request is rejected with **403 Forbidden** and this body:\n\n```json\n{\"message\": \"403 Forbidden\", \"status\": \"module_permission_missing\"}\n```\n\nThis 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.\n\n## Authentication\nAvailable for **Staff tokens**. **Directory and App tokens** are supported with the `X-On-Behalf-Of` header set to the target business UID.\n\n## How It Works\n1. The system finds the `PaymentStatus` referenced by `payment_status_uid`, which links to a specific appointment/event and its service.\n2. 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.\n3. If multiple packages qualify, the **soonest-expiring package** is used first (ordered by `valid_until ASC`).\n4. One credit is consumed: `bookings_usage` is incremented, a `BookingCreditRedemption` record is created, and the `PaymentStatus` is set to paid with a zero price.\n\n## Required Parameters\n- `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.\n\n## Optional Parameters\n- `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.\n\n## Notes\n- Returns 422 \"There is no package to use\" if no active client packages with available credits exist for the relevant service.\n- Returns 422 if the payment status is already paid.\n- This endpoint is in Alpha and may change.\n- To reverse a credit redemption, use `PUT /platform/v1/payment/client_packages/cancel_redemption`.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "matter_uid": { "description": "Matter/Conversation UID. If not provided, the system will attempt to find the default matter for the client.", "type": "string", "x-reference-to": "clients.matter" }, "payment_status_uid": { "description": "The UID of the payment status record to pay using a package credit. Must reference a pending/unpaid payment status linked to an appointment.", "type": "string", "x-reference-to": "sales.payment_status" } }, "required": [ "payment_status_uid" ], "type": "object" } } } }, "security": [ { "Bearer": [] } ] } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Provide a valid bearer token in the Authorization header. Example: 'Authorization: Bearer {app_token}'" } } } } ````