Billing & Notification Objects

Billing objects represent the Workspace’s subscription, usage, payment, billing details, and notification preferences.

Subscription Object

WorkspaceSubscription represents the current Workspace subscription state.

Fields

Field	Type	Required	Nullable	Default	Description
id	string	Yes	No	Generated	Subscription identifier.
workspaceId	string	Yes	No	—	Owning Workspace.
plan	SubscriptionPlan	Yes	No	FREE	Current plan.
status	SubscriptionStatus	Yes	No	active	Current subscription state.
billingCycle	BillingCycle	Yes	No	monthly	Billing interval.
provider	PaymentProvider	No	Yes	null	Payment provider.
maxSeats	number	Yes	No	1	Seat allowance.
maxConversations	number	Yes	No	100	Monthly conversation allowance.
addonSeats	number	Yes	No	0	Additional purchased seats.
currentPeriodStart	ISO-8601 timestamp	Yes	No	Generated	Current billing-period start.
currentPeriodEnd	ISO-8601 timestamp	Yes	No	Generated	Current billing-period end.
cancelAtPeriodEnd	boolean	Yes	No	false	Indicates whether cancellation occurs at period end.
trialEndsAt	ISO-8601 timestamp	No	Yes	null	Trial expiration timestamp.
gracePeriodEndsAt	ISO-8601 timestamp	No	Yes	null	End of the billing grace period.
refundStatus	RefundStatus	Yes	No	NONE	Current refund state.
refundDeadlineAt	ISO-8601 timestamp	No	Yes	null	Refund eligibility cutoff.

Subscription Plans

Plan	Base Limits / Capabilities
FREE	1 seat, 100 conversations per month, 10 Saved Replies.
STARTER	3 seats, 500 conversations per month, 50 Saved Replies, CSAT.
GROWTH	10 seats, 2,000 conversations per month, expanded Saved Reply capabilities, custom categories, audit-related capabilities.
ENTERPRISE	Custom or expanded limits, including API access and SSO capabilities.

Subscription Entitlement States

State	Description
active	Subscription is active.
pending	Subscription checkout or activation is pending.
trialing	Workspace is within an active trial period.
past_due	Payment is overdue and the Workspace is within the configured billing grace period.
cancelled	Subscription is cancelled, with applicable access retained through the current billing period.

A past_due subscription has a verified 7-day grace period. A cancelled subscription retains applicable paid access until the current billing period ends.

Metered Usage Object

WorkspaceUsage represents monthly Workspace conversation usage.

Field	Type	Description
id	string	Usage record identifier.
workspaceId	string	Workspace identifier.
month	number	Calendar month represented by the usage record.
year	number	Calendar year represented by the usage record.
conversationCount	number	Number of metered Conversations for that period.
updatedAt	ISO-8601 timestamp	Last usage update timestamp.

Payment Transaction Object

PaymentTransaction represents a payment transaction associated with a Workspace subscription.

Relevant fields include:

Field	Type	Description
id	string	Transaction identifier.
workspaceId	string	Workspace identifier.
provider	PaymentProvider	Payment gateway provider.
providerPaymentId	string	Provider payment identifier.
providerEventId	string	Provider event identifier.
plan	SubscriptionPlan	Plan associated with the transaction.
billingCycle	BillingCycle	Billing interval.
amount	number	Transaction amount.
currency	string	Transaction currency.
status	PaymentStatus	Payment state.
paidAt	ISO-8601 timestamp	Payment completion timestamp.

Provider raw payload dumps must not be exposed as Reference fields.

Billing Details Object

BillingDetails contains billing and tax-related contact information.

Field	Description
firstName	Billing contact first name.
lastName	Billing contact last name.
companyName	Business or company name.
country	Billing country.
streetAddress	Billing street address.
city	Billing city.
state	Billing state or region.
pinCode	Postal or PIN code.
phone	Billing contact phone number.
email	Billing contact email address.

Notification Preferences

Notification configuration supports:

Field	Description
notificationFrequency	General email notification frequency.
unreadMessageFrequency	Unread-message reminder frequency.
notificationStartTime	Preferred daily notification time.
enableDailyDigest	Daily digest setting.
notificationRecipientIds	Users receiving configured administrative notifications.
billingNotificationRecipientIds	Users receiving billing-related alerts.
enableGuestEmailNotifications	Controls applicable guest email notification behavior.

Internal recipient-management fields should only be exposed where supported by the corresponding public API.

Notification Frequencies

• IMMEDIATE
• SIX_HOURS
• TWELVE_HOURS
• TWENTY_FOUR_HOURS
• NONE

Need Help?

Email: support@ysdesk.com

Documentation: https://docs.ysplugins.com/ys-desk