@kelviq/mcp-server 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. package/package.json +88 -0
@@ -0,0 +1,156 @@
1
+ ---
2
+ title: "Offerings"
3
+ slug: "monetization/offerings"
4
+ section: "monetization"
5
+ ---
6
+ **Beta Feature:** Monetization features are currently in beta. Please contact us at [hi@kelviq.com](mailto:hi@kelviq.com) to enable this on your account.
7
+
8
+ ## What is an Offering?
9
+
10
+ In Kelviq, an **Offering** is the key that unlocks specific pricing and pricing table experiences for your different customer segments. It is a powerful entity that determines precisely what pricing table design and dynamic pricing adjustments a user or user segment is presented with. Offerings act as the crucial bridge connecting your Pricing table configurations and/or Targeting Rules to your live application.
11
+
12
+ An Offering "offers" a package that can include:
13
+ * A specific **Pricing table** design (how plans are visually presented).
14
+ * Dynamic pricing adjustments driven by **Targeting Rules** (e.g., for Purchasing Power Parity, specific countries, or other customer attributes).
15
+
16
+ Ultimately, Offerings enable you to remotely control, iterate on, and experiment with different pricing strategies and user experiences with agility.
17
+
18
+ <img height="200" src="/images/central-hub-offering-illustartion.png" />
19
+
20
+
21
+ ---
22
+
23
+ ## How Offerings Work
24
+
25
+ Offerings provide a robust way to remotely manage which Pricing table design and/or Targeting Rule (with its dynamic pricing logic) is delivered to your users. This is achieved by integrating a unique **Offering ID** into your application's code.
26
+
27
+ * **Centralized Control:** You create and configure Offerings within the Kelviq dashboard.
28
+ * **Decoupling for Agility:** The primary benefit is that once the `Offering ID` is implemented in your codebase, your product, marketing, or sales teams can change which Pricing table is displayed or which Targeting Rule is applied to that Offering directly from the Kelviq dashboard. **This requires no new code deployments for most updates.**
29
+ * **Flexible Configuration:** You can configure an Offering with:
30
+ * Just a Pricing table
31
+ * Just a Targeting Rule
32
+ * Both a Pricing table and a Targeting Rule (where the available Targeting Rules are filtered based on the selected Pricing table)
33
+
34
+ This system allows for rapid iteration, A/B testing, and strategic adjustments to your monetization approach without continuous engineering effort.
35
+
36
+ <img height="200" src="/images/offering-power-illustartion.png" />
37
+
38
+
39
+ ---
40
+
41
+ ## Creating an Offering
42
+
43
+ You create Offerings from the Kelviq dashboard.
44
+
45
+ ### Step 1: Navigate and Initiate
46
+ 1. From the main sidebar navigation, go to **Monetization > Offerings**.
47
+ 2. On the "Offerings" list page, click the **"+ Create offering"** button.
48
+
49
+
50
+ <img height="200" src="/images/create-offering-list.png" />
51
+
52
+
53
+ This action opens the "Create offering" modal.
54
+
55
+ ### Step 2: Configure the Offering in the Modal
56
+
57
+ Within the modal, you will define what this Offering will present to users.
58
+
59
+
60
+
61
+ <img height="200" src="/images/configure-offering-modal.png" />
62
+
63
+
64
+
65
+ #### A. Link a Pricing table (Optional)
66
+ * **Select Pricing table:** If this Offering is intended to display pricing table, select it from the "Select Pricing table" dropdown menu.
67
+
68
+
69
+ <img height="200" src="/images/select-pricing-table-offering.png" />
70
+
71
+
72
+ * **Skip Pricing table Linking:** You can skip the pricing table linking if you don't want to link a pricing table to this offering. This is useful if the Offering's purpose is solely to apply Targeting Rule-based price adjustments.
73
+
74
+ #### B. Offer Via Targeting Rule (Optional)
75
+
76
+ * **Offer via Targeting Rule:**
77
+ 1. Select this option if you want the Offering to apply dynamic pricing based on customer attributes defined in a Targeting Rule.
78
+ 2. From the **"Select Targeting Rule"** dropdown, choose the rule you want to link to this Offering.
79
+
80
+
81
+ <img height="200" src="/images/choose-how-to-offer.png" />
82
+
83
+
84
+ 3. If you do not have a suitable Targeting Rule, click the **"+ Create rule"** link or button (often found within or near the dropdown). This action will take you to the Targeting Rule creation flow (as detailed in the [Targeting Rules documentation](/monetization/targeting-rules#creating-and-defining-targeting-rules)).
85
+
86
+
87
+ <img height="200" src="/images/create-rule-offering.png" />
88
+
89
+
90
+
91
+ **Targeting Rule Filtering:** If you've selected a Pricing table, the available Targeting Rules in the dropdown will be filtered to only show rules that are associated with that specific Pricing table. This ensures consistency in your pricing strategy.
92
+
93
+ <img height="200" src="/images/pricing-table-and-targeting-rule.png" />
94
+
95
+
96
+
97
+ #### C. Create the Offering
98
+ 1. Once you have configured the Pricing table (if any) and selected a Targeting Rule, click the **"Create"** button on the modal.
99
+
100
+
101
+ <img height="200" src="/images/create-the-offering.png" />
102
+
103
+
104
+
105
+ ### Step 3: Integrate with Your Application
106
+ Upon successful creation, a confirmation or success modal will appear, prominently displaying the unique **Offering ID**.
107
+
108
+ * **Copy the Offering ID:** This ID is essential for using the Offering in your application.
109
+
110
+
111
+ <img height="200" src="/images/copy-offering-id.png" />
112
+
113
+
114
+ * **Implement in Your Code:** Paste this `Offering ID` into your application's frontend codebase where you initialize the Kelviq SDK or when you render your pricing component. This ID instructs your application which specific Offering (and therefore which pricing table, plans, and dynamic pricing logic) to fetch from Kelviq and display to the end-user.
115
+
116
+ Your Offering is now active and ready to be served to users based on your integration.
117
+
118
+ ---
119
+
120
+ ## Managing Offerings
121
+
122
+ You can view, edit, and manage your Offerings from the Kelviq dashboard.
123
+
124
+ ### Viewing Your Offerings
125
+ Navigate to **Monetization > Offerings**. The listing page displays all your Offerings, along with their statuses (e.g., "Active," "Archived," "Draft/Pending Changes").
126
+
127
+
128
+
129
+ <img height="200" src="/images/view-offering.png" />
130
+
131
+
132
+
133
+ ### Editing an Offering
134
+ You can modify an Offering at any time to change the Pricing table it displays or the Targeting Rule it uses. This is a powerful way to iterate on your strategy.
135
+
136
+ 1. On the Offerings list page, locate the Offering you wish to edit.
137
+ 2. Click the **edit icon** on that Offering's row.
138
+
139
+
140
+ <img height="200" src="/images/edit-offering.png" />
141
+
142
+
143
+ 3. The "Edit Offering" modal will appear, which is similar to the creation modal. Here you can:
144
+ * Change the linked **Pricing table**.
145
+ * Change the linked **Targeting Rule** (filtered based on the selected Pricing table).
146
+
147
+
148
+ <img height="200" src="/images/offerings-edit-offerings.png" />
149
+
150
+
151
+ 4. Click **"Update"** to apply your modifications.
152
+
153
+ **No Codebase Updates Needed for Most Changes!**
154
+ The Offering ID embedded in your application code remains the same. By editing the Offering in the Kelviq dashboard (e.g., switching its linked Pricing table or Targeting Rule), you can instantly change the pricing and presentation your users see without requiring your engineering team to deploy new code. This empowers Product Managers, Go-To-Market teams, and Sales teams to iterate rapidly.
155
+
156
+ **Active Offering Resolution:** For any given user and product context, Kelviq resolves a single Offering to present. This resolution is based on the priority of matching Targeting Rules. Careful planning of your Targeting Rules and default Offering configurations is recommended to ensure predictable outcomes.
@@ -0,0 +1,226 @@
1
+ ---
2
+ title: "Pricing table"
3
+ slug: "monetization/pricing-tables"
4
+ section: "monetization"
5
+ ---
6
+ **Beta Feature:** Monetization features are currently in beta. Please contact us at [hi@kelviq.com](mailto:hi@kelviq.com) to enable this on your account.
7
+
8
+ ## What are Kelviq Pricing tables?
9
+
10
+ Kelviq' Pricing tables are dynamic, remotely configurable interfaces that present your pricing plans and features to your customers. They are the crucial touchpoint where users make subscription decisions. Our Pricing tables empower you to design, build, and deploy your entire pricing presentation—from simple pricing tables to complex, interactive subscription flows—directly from the Kelviq dashboard, minimizing the need for code changes or app updates for most modifications.
11
+
12
+ Key benefits include:
13
+ * **Remote Configuration:** Update your pricing table's appearance, content, and even the plans displayed, directly from the Kelviq dashboard.
14
+ * **No-Code for Most Changes:** Iterate on your pricing display rapidly. Most visual and content changes are reflected instantly without engineering intervention.
15
+ * **Dynamic Pricing Display:** Any modifications to your underlying pricing models (plans, features, prices) are automatically reflected in your pricing tables, ensuring consistency.
16
+ * **Experimentation Ready:** Easily A/B test different pricing table designs, plan presentations, and promotional content to optimize conversion.
17
+
18
+ <img height="200" src="/images/conceptual-diagram.png" />
19
+
20
+
21
+
22
+ ---
23
+
24
+ ## Getting Started with Pricing tables
25
+
26
+ You build and manage your pricing tables within the Kelviq Dashboard.
27
+
28
+ 1. From the main sidebar, navigate to **Monetization > Pricing tables**.
29
+ 2. On the Pricing tables page, you can see a list of your existing pricing tables or create a new one by clicking the **"+ Create Pricing Table"** button. You can start from one of our pre-built templates or design a completely custom experience from scratch.
30
+
31
+
32
+
33
+ <img height="200" src="/images/pricing-tables-list.png" />
34
+
35
+
36
+
37
+ Our pricing tables can be integrated into your application using native SDKs (React, Vue.js, etc.) to deliver smooth, performant, and intuitive experiences to your customers when they are ready to view an Offering.
38
+
39
+ ---
40
+
41
+ ## The Pricing table Editor
42
+
43
+ The Pricing table editor is your central hub for designing and configuring every aspect of your pricing table. It is organized into three main tabs: Configuration, Content, and Appearance.
44
+
45
+ <img height="200" src="/images/pricing-table-editor.png" />
46
+
47
+
48
+
49
+
50
+
51
+ This tab focuses on the foundational settings, linking your pricing table to your product catalog and defining core display and localization rules.
52
+
53
+ #### Connecting Your Product
54
+ First, you must associate your pricing table with the product whose plans and features it will display.
55
+ * **Product Connection:** From the dropdown menu, select the relevant product from your catalog. This action dynamically links the pricing table to that product's specific set of plans and features.
56
+
57
+
58
+
59
+ <img height="200" src="/images/configuration-tab.png" />
60
+
61
+
62
+
63
+ #### Price & Feature Display Settings
64
+ Control how detailed information about pricing and features is presented to the user.
65
+ * **Display Prices & Features:** This toggle (enabled by default) determines if the detailed pricing information (e.g., price per month) and the lists of features associated with each plan are shown on the pricing table.
66
+ * **Show Feature Description Tooltip:** When enabled, an info icon (ⓘ) will appear next to features in the plan list. Hovering over this icon will display a tooltip containing the feature's description (as defined in your Product Catalog).
67
+
68
+ #### Localization & Formatting
69
+ Configure how pricing information is adapted for different locales and user preferences.
70
+ * **Localize Pricing:** This toggle (disabled by default) enables Kelviq to attempt displaying prices in the user's local currency, based on their region.
71
+ * **Decimal Places:** Choose the number of decimal places to display for prices (e.g., `0` for `$10`, `1` for `$10.0`, `2` for `$10.00`).
72
+ * **Decimal Separator:** Select the character used as the decimal separator (e.g., Dot `.` for `$10.00` or Comma `,` for `$10,00`).
73
+ * **Price Rounding:** Define how prices are rounded if they result in fractions after currency conversion or specific calculations:
74
+ * `Ceiling`: Always rounds up to the next whole number (e.g., `4.2` becomes `5`).
75
+ * `Floor`: Always rounds down to the previous whole number (e.g., `4.2` becomes `4`).
76
+ * `Round to nearest`: Rounds to the closest whole number (e.g., `4.2` ≈ `4`, `4.6` ≈ `5`).
77
+
78
+
79
+
80
+ <img height="200" src="/images/configuration-localization.png" />
81
+
82
+
83
+
84
+
85
+
86
+
87
+ This tab empowers you to customize all visible text, manage the order and visibility of plans and features, and add promotional elements to drive conversions.
88
+
89
+ #### General Pricing table Content
90
+ Update the main textual elements such as titles, subtitles, or descriptive paragraphs. You can also inject marketing labels or badges to highlight specific deals or plans.
91
+ * **Example:** Add a "Save 20% with Annual Billing ✨" badge next to your annual plan toggle, or include a "Most Popular!" banner on your recommended plan.
92
+
93
+
94
+
95
+ <img height="200" src="/images/content-editor.png" />
96
+
97
+
98
+ #### Managing Plans in the Pricing table
99
+ The plans linked from your selected product are automatically listed. You have full control over their presentation:
100
+ * **Ordering:** Simply drag and drop plans to change their sequence in the pricing table. This allows you to prioritize the plans you want users to see first.
101
+
102
+
103
+ <img height="200" src="/images/managing-plans-ordering.png" />
104
+
105
+
106
+ * **Visibility:** Click the three-dot menu on any plan card and select **"Hide"** to remove it from this specific pricing table. The plan remains active in your product catalog but will not be visible in this pricing table instance.
107
+
108
+
109
+ <img height="200" src="/images/managing-plans-visibility.png" />
110
+
111
+
112
+ * **Editing Display Properties:** Click the three-dot menu and select **"Edit"** to modify how the plan is presented:
113
+ * **Plan Name & Description:** Override the default name and description (sourced from the Product Catalog) specifically for this pricing table.
114
+ * **Highlight Plan:** Toggle this option to visually emphasize a plan, perhaps with a distinct border, background color, or a "Recommended" badge. This is effective for guiding users towards your preferred or best-value option.
115
+
116
+
117
+
118
+ <img height="200" src="/images/managing-plans-editing.png" />
119
+
120
+
121
+ #### Managing Features within Plans
122
+ Within each plan's edit mode (accessed as described above), you can also customize how its included features are displayed:
123
+ * **Ordering:** Drag and drop features within a plan's list to change their sequence for that plan, as displayed on this pricing table.
124
+
125
+
126
+ <img height="200" src="/images/reordering-features.png" />
127
+
128
+
129
+ * **Editing Display Text:** Click the three-dot menu next to any feature in the list and select **"Edit"** to customize its presentation:
130
+ * **Customer Display Text:** Modify the primary label for the feature. For example, change an internal feature ID like `api_calls_v2_monthly` to a user-friendly "Monthly API Requests".
131
+ * **Tooltip Description:** Add or edit the detailed text that appears in a tooltip when a user hovers over the info icon next to the feature.
132
+
133
+ The original default text (from the feature's settings in the Product Catalog) for both these fields is shown at the bottom of the form. This allows you to easily reference or revert to the original copy if needed.
134
+
135
+
136
+
137
+ <img height="200" src="/images/managing-features-editing.png" />
138
+
139
+
140
+
141
+
142
+
143
+
144
+ This tab gives you comprehensive control over the visual styling of your pricing table, enabling you to perfectly align it with your brand identity and create an appealing user experience.
145
+
146
+ #### Branding & Styling
147
+ * **Colors:** Use color pickers or input hex codes to customize Background color, Primary color (often used for CTAs and highlights), Primary text color, Secondary text color, CTA text color, and Border colors.
148
+
149
+
150
+ <img height="200" src="/images/appearance-colors.png" />
151
+
152
+
153
+ * **Typography:** Define the Font family for your pricing table (e.g., Inter, Roboto, Open Sans, or custom fonts). Set specific styles (font size, weight, line height) for different text elements like H1, H2, H3, Paragraph 1 (P1), and Paragraph 2 (P2).
154
+
155
+
156
+ <img height="200" src="/images/appearance-typography.png" />
157
+
158
+
159
+ * **Layout:** Adjust general layout properties like overall Alignment (left, center, right), maximum Width of the pricing table, and Margin and Padding for various components to control spacing.
160
+
161
+
162
+ <img height="200" src="/images/appearance-layout.png" />
163
+
164
+
165
+ #### Custom CSS
166
+ For highly specific styling needs that go beyond the built-in options, you can add your own custom CSS rules. This allows for virtually unlimited styling flexibility.
167
+
168
+
169
+ <img height="200" src="/images/appearance-css.png" />
170
+
171
+
172
+
173
+
174
+ ---
175
+
176
+ ## Connecting Pricing tables to Offerings
177
+
178
+ Once your pricing table is designed and saved, it doesn't automatically appear to users. You need to link it to an **Offering** to control who sees it and under what conditions.
179
+
180
+ ### What is an Offering?
181
+
182
+ An **Offering** in Kelviq is a powerful entity that determines precisely what pricing table (and therefore which set of plans and pricing) a specific user or user segment is presented with. Offerings are the bridge between your pricing table designs and your live application. They enable you to:
183
+ * Remotely control the entire pricing table experience without deploying new code.
184
+ * Define a specific set of packages (plans) and associated metadata that are shown on a pricing table.
185
+ * Implement dynamic pricing strategies by linking pricing tables to **Targeting Rules**. This allows you to show different pricing tables and pricing to different users based on attributes like their geographic location (for PPP pricing), device type, or other custom criteria.
186
+ * Link pricing tables directly to specific products for simpler, non-targeted scenarios.
187
+
188
+ Targeting Rules will be discussed in detail in their own documentation section. Here, we'll focus on creating a basic Offering to link your pricing table directly to a product.
189
+
190
+ ### Creating an Offering for Your Pricing table
191
+
192
+ 1. From the main sidebar, navigate to **Monetization > Offerings**.
193
+ 2. Click the **"+ Create offering"** button.
194
+
195
+
196
+ <img height="200" src="/images/create-offering.png" />
197
+
198
+
199
+ 3. In the "Create offering" modal that appears:
200
+ * **Select a Pricing Table:** From the "Select Pricing Table" dropdown menu, choose the pricing table design you want this Offering to display. Selecting a Pricing Table is the primary step, as it contains the product and plans to be shown.
201
+ * **Select a Targeting Rule (Optional):** If you want to apply dynamic pricing adjustments (like PPP or country-specific discounts) to the selected pricing table, choose a rule from the "Select Targeting Rule" dropdown.
202
+ If this field is left empty, the pricing table will be displayed with its default pricing to all users.
203
+ If you select a rule, its logic will be applied to the prices shown on the pricing table for any user who matches the rule's conditions.
204
+
205
+
206
+
207
+
208
+
209
+
210
+ <img height="200" src="/images/create-offering-select-pricing-table.png" />
211
+
212
+
213
+
214
+ 4. Click **"Create"**.
215
+
216
+ ### Using the Offering ID
217
+ The most crucial piece of information for integration is the **Offering ID**.
218
+ Once you hit **Create**, the modal will display the **Offering ID** — this is the key you'll need to copy and paste directly into your codebase to complete the integration.
219
+ You can always retrieve the Offering ID later from the **Offering list** page.
220
+
221
+
222
+
223
+ <img height="200" src="/images/offering-id-application.png" />
224
+
225
+
226
+ * This `Offering ID` must be pasted into your application's code where you initialize the Kelviq SDK or when you render the pricing table component. The ID tells your application which specific Offering (and therefore which pricing table configuration, plans, and pricing) to fetch and display to the end-user.
@@ -0,0 +1,278 @@
1
+ ---
2
+ title: "Targeting Rules"
3
+ slug: "monetization/targeting-rules"
4
+ section: "monetization"
5
+ ---
6
+ **Beta Feature:** Monetization features are currently in beta. Please contact us at [hi@kelviq.com](mailto:hi@kelviq.com) to enable this on your account.
7
+
8
+ ## What are Targeting Rules?
9
+
10
+ Targeting Rules in Kelviq are a sophisticated feature designed to empower you to present **specific Offerings (which include unique dynamic pricing based on PPP groups, country) to distinct customer segments.** By defining rules based on customer attributes, you can tailor your pricing and product presentation dynamically, ensuring the right customers see the most relevant and effective offers.
11
+
12
+ This powerful capability allows you to:
13
+ * **Implement Granular Pricing Strategies:** Based on customer behavior, demographics, or geographic location.
14
+ * **Maximize Customer Lifetime Value (LTV):** By optimizing pricing for different segments.
15
+ * **Enhance Pricing Table Effectiveness:** By showing more relevant plans and pricing, increasing conversion rates.
16
+
17
+ Supported attributes for creating these rules include:
18
+ * **Any audience:** A default or catch-all segment.
19
+ * **Country:** Target users based on their geographical location.
20
+ * **PPP group:** Group countries by Purchasing Power Parity to offer regionally appropriate pricing.
21
+ * **Platform / OS:** Target based on the operating system (e.g., iOS, Android, Windows, macOS). (`Coming soon`)
22
+ * **Browser:** Target based on the web browser being used (e.g., Chrome, Safari, Firefox). (`Coming soon`)
23
+
24
+ <img height="200" src="/images/trageting-rule-illustartion.png" />
25
+
26
+
27
+ ---
28
+
29
+ ## Creating and Defining Targeting Rules
30
+
31
+ You create, view, and manage your Targeting Rules directly from the Kelviq dashboard.
32
+
33
+ 1. From the main sidebar navigation, go to **Monetization > Targeting Rules**.
34
+ 2. On the "Targeting Rules" page, click the **"+ Create rule"** button, located in the top-left corner.
35
+
36
+
37
+ <img height="200" src="/images/create-rule.png" />
38
+
39
+
40
+
41
+ This action opens a dedicated page where you will define all aspects of your new rule.
42
+
43
+ ### Step 1: Rule Information
44
+
45
+ Begin by providing the basic identifying information for your rule. This helps you organize and manage your rules effectively.
46
+
47
+ * **Rule Name:** Click into the rule name field and enter a clear, descriptive name. This name is for your internal reference.
48
+ * **Example:** "PPP Discount - Tier 3 Countries," "EU Early Adopter Offer," "USA - Standard Pricing."
49
+
50
+
51
+ <img height="200" src="/images/rule-information.png" />
52
+
53
+
54
+ * **Select Product(s):** Click the dropdown field to choose one or more products from your catalog to which this rule's pricing adjustments will apply. You can search by product name or ID.
55
+
56
+
57
+ <img height="200" src="/images/select-product.png" />
58
+
59
+
60
+
61
+ A Targeting Rule only becomes active and influences customer experiences once it is connected to an **Offering**.
62
+
63
+ ### Step 2: Setting Conditions
64
+
65
+ This is the core of your Targeting Rule. Here, you define the specific customer attributes that must be met for the rule (and its associated pricing adjustments) to apply.
66
+
67
+ #### Condition Logic: "If the customer matches..."
68
+ 1. Click on the "If the customer matches *" to begin defining your first condition.
69
+ 2. **Select Condition Type:** Choose an attribute from the dropdown menu.
70
+ * **Any audience:** A broad condition for setting a default rule that applies if no other more specific rule matches a user.
71
+ * **Country:** Target users based on their geographic location, detected via IP address.
72
+ * **PPP group:** Target users based on the Purchasing Power Parity of their country.
73
+ * **Platform / OS:** (`Coming soon`)
74
+ * **Browser:** (`Coming soon`)
75
+
76
+
77
+ <img height="200" src="/images/setting-conditions.png" />
78
+
79
+
80
+ 3. **Select Operator:** Choose how the condition should evaluate the selected attribute:
81
+ * **`is any of`**: The rule applies if the customer's attribute matches *at least one* of the values you specify. For example, if "Country `is any of` [India, Brazil, Nigeria]," the rule applies if the user is in India OR Brazil OR Nigeria.
82
+ * **`is not any of`**: The rule applies if the customer's attribute does *not match any* of the values you specify. For example, if "Country `is not any of` [USA, Canada]," the rule applies if the user is in any country *except* the USA or Canada.
83
+
84
+
85
+ <img height="200" src="/images/select-operator.png" />
86
+
87
+
88
+ 4. **Select Value(s):** Based on the condition type and operator, select the specific values.
89
+ * If you selected "Country," a multi-select dropdown appears where you can search for and choose specific countries.
90
+
91
+
92
+ <img height="200" src="/images/select-country.png" />
93
+
94
+
95
+ * If you selected "PPP group," select from predefined PPP groups in the dropdown.
96
+
97
+
98
+ <img height="200" src="/images/select-ppp-group.png" />
99
+
100
+
101
+
102
+ #### PPP Groups
103
+ Purchasing Power Parity (PPP) targeting is a strategic way to offer your product at prices more aligned with local economic conditions, significantly boosting global accessibility and adoption.
104
+
105
+ * **What they are:** Countries are categorized into groups (tiers) based on their relative purchasing power compared to a benchmark (often the US Dollar). A lower PPP index signifies that the local currency has less purchasing power.
106
+ * **Example Groups (Illustrative - groups in Kelviq are predefined):**
107
+ * **High PPP (e.g., Index 0.7-1.0+):** Includes countries like the USA, Switzerland, Norway, Western European nations, Canada, Australia. (These countries usually receive standard/baseline pricing).
108
+ * **Mid PPP (e.g., Index 0.4-0.69):** May include countries in Southern/Eastern Europe, parts of Latin America, and some Southeast Asian nations. (These countries may receive a moderate discount).
109
+ * **Low PPP / Frontier Markets (e.g., Index 0.2-0.39):** Could include countries like India, Pakistan, Nigeria, Bangladesh, and many nations in Africa and other parts of LATAM/SE Asia. (These countries may receive a significant discount).
110
+ * **Benefits for SaaS Companies using PPP-based pricing:**
111
+ * **Increased Global Market Penetration:** Access and convert users in developing economies.
112
+ * **Improved Affordability & Higher Adoption Rates:** A lower price barrier leads to more sign-ups and usage.
113
+ * **Enhanced Competitive Advantage:** Offer fairer, more attractive pricing than competitors who use a single global price.
114
+ * **Ethical and Customer-Centric Pricing:** Align the value delivered with local economic realities.
115
+
116
+ #### Defining Price Adjustments
117
+ Once your conditions are set, specify how the pricing should change for customers who match this rule:
118
+ 1. From the "Then" section of the condition block, choose either **"Increase price by"** or **"Decrease price by"** from the dropdown menu.
119
+
120
+
121
+ <img height="200" src="/images/define-price-adjustment.png" />
122
+
123
+
124
+ 2. Enter the **percentage** value for the adjustment (e.g., `20` for a 20% change) in the adjacent input field.
125
+
126
+
127
+ <img height="200" src="/images/define-price-adjustment-value.png" />
128
+
129
+
130
+ * **When to use "Decrease price by":**
131
+ * **PPP Adjustments:** To make products more affordable in lower PPP regions.
132
+ * **Promotional Pricing:** To target specific new markets or regions with introductory discounts.
133
+ * **Segment-Specific Offers:** To provide discounts for defined user groups (e.g., educational, non-profit, based on custom attributes if supported).
134
+ * **Benefit:** Increases accessibility, drives adoption in price-sensitive markets, and can boost sales volume.
135
+ * **When to use "Increase price by":**
136
+ * **Premium Segments:** If you identify user segments with a higher willingness to pay.
137
+ * **Value-Based Pricing:** For regions where your product offers exceptionally high value or has few local competitors.
138
+ * **Cost Adjustments:** To account for higher operational costs or specific taxes in certain regions if not handled separately.
139
+ * **Benefit:** Optimizes revenue in markets where higher prices are sustainable.
140
+
141
+ #### Combining Multiple Conditions
142
+ You can create highly specific targeting rules by layering multiple conditions.
143
+
144
+ * **AND Logic:** To add more criteria that *must all be met* for the rule to apply, click the **"+ AND"** button within the same condition block. Each new condition added this way narrows the target segment.
145
+ * **Example:** "If customer is in `PPP Group: Low PPP` **AND** Country `is any of` [India]".
146
+
147
+
148
+ <img height="200" src="/images/and-logic.png" />
149
+
150
+
151
+ * **Precedence with AND:** When building complex rules with multiple AND conditions that might appear to overlap (e.g., a country is in a selected PPP group, AND that same country is also specifically targeted with a different adjustment), rules are evaluated based on their defined order or specificity. **It is highly recommended to test complex rule interactions thoroughly to confirm the exact behavior and ensure they produce the desired outcome before activating them for live offerings.**
152
+
153
+
154
+ <img height="200" src="/images/two-and-condition.png" />
155
+
156
+
157
+ * **OR Logic:** To apply the same price adjustment to several distinct customer segments, click the **"+ Add condition group (OR)"** button. This creates a new, independent block of conditions. The rule will apply if a customer matches *all* conditions in Group 1 **OR** *all* conditions in Group 2, etc.
158
+ * **Example:** "(If Country `is any of` [USA, Canada]) **OR** (If Country `is any of` [UK, Germany] **AND** Browser `is any of` [Chrome])".
159
+
160
+
161
+ <img height="200" src="/images/two-or-conditions.png" />
162
+
163
+
164
+ The evaluation of combined AND/OR conditions follows a structured logic. The diagram below illustrates a simplified flow where a rule applies if either "Condition Group 1" (which itself might contain multiple AND conditions) OR "Condition Group 2" is met:
165
+
166
+ ```mermaid
167
+ graph TD
168
+ A[User Request Processed] --> B{Match all AND conditions in Group 1?}
169
+ B -->|Yes| C[Rule Applies: Use Group 1 Adjustments]
170
+ B -->|No| D{Match all AND conditions in Group 2?}
171
+ D -->|Yes| E[Rule Applies: Use Group 2 Adjustments]
172
+ D -->|No| F[Evaluate Next OR Group if any...]
173
+ F -->|No further OR groups match| G[Rule Does Not Apply / Default Behavior]
174
+ C --> Z[End Evaluation]
175
+ E --> Z
176
+ G --> Z
177
+ ```
178
+
179
+ Support for targeting by **Platform / OS** and **Browser** is planned for a future release.
180
+
181
+ #### A/B Testing with Variants (`Coming soon`)
182
+ Kelviq will allow you to create multiple variants within a single Targeting Rule (e.g., Variant A with a 10% discount, Variant B with a 15% discount). This will enable you to A/B test different pricing adjustments for the same customer segment to determine which performs best. This feature is `Coming soon`.
183
+
184
+ <img height="200" src="/images/a-b-testing-with-variants.png" />
185
+
186
+
187
+ ### Step 3: Creating the Rule
188
+
189
+ **Crucial Note:** Once a Targeting Rule is created and saved, its **conditions and price adjustments cannot be altered**. This restriction is in place to maintain the integrity and consistency of your analytics and reporting based on these rules. You can, however, edit the rule's name later if needed. Therefore, please plan and review your conditions meticulously before creating the rule.
190
+
191
+ 1. After you have carefully defined your rule name, selected the product(s), and set all conditions and price adjustments, click the **"Create rule"** button, located at the bottom of the page.
192
+ *[Image: The bottom of the Targeting Rule creation page with the "Create rule" button clearly highlighted.]*
193
+
194
+
195
+ <img height="200" src="/images/creating-the-rule.png" />
196
+
197
+
198
+
199
+ ---
200
+
201
+ ## Linking Targeting Rules to Offerings
202
+
203
+ Creating a Targeting Rule defines the logic, but it doesn't activate it for your users. To make a rule live, you must link it to an **Offering**. An Offering is what connects your Targeting Rules (and/or Pricing tables) to your users. These entities work together in a sequence to deliver dynamic pricing:
204
+ ```mermaid
205
+ graph LR
206
+ A[User Request with Offering ID in App] --> B[Kelviq Fetches Offering Config]
207
+ B --> C[Targeting Rule Linked to Offering]
208
+ C --> D{Rule Conditions Met?}
209
+ D -->|Yes| E[Price Adjustments Applied]
210
+ D -->|No| F[No Adjustments from This Rule / Default]
211
+ E --> G[Pricing Table Prices]
212
+ F --> G
213
+ G --> H[Final Pricing Displayed to User]
214
+ ```
215
+
216
+ After successfully creating a Targeting Rule, you will be directed to the Offering creation page, with the "Create offering" modal appearing and your newly created rule pre-selected.
217
+
218
+ <img height="200" src="/images/create-offering.png" />
219
+
220
+
221
+ 1. **In the "Create offering" (or "Edit offering") modal:**
222
+ * **Pricing Table Linking (Optional):** An option exists to "Skip if you don't want to link a pricing table to this offering." If your Offering's purpose is *only* to apply rule-based price adjustments without using the pricing table, you can skip this.
223
+ * If you select a **pricing table** you will only be able to select a Targeting Rule that is associated with that pricing table.
224
+ * **Assign to Targeting Rule:** Ensure **"Targeting Rule"** is selected as the assignment type.
225
+ * **Select Targeting Rule:** The dropdown will automatically have your newly created rule selected. If you are editing an existing offering or creating a new one independently, choose the desired rule from this list.
226
+ 2. Click **"Create"** (or "Update") on the Offering modal.
227
+
228
+ This action creates (or updates) the Offering and effectively activates your Targeting Rule. You will then see the **Offering ID** in the modal.
229
+
230
+ * **Offering ID:** This ID is essential. Copy this ID and paste it into your application's code where you initialize the Kelviq SDK or render the pricing table component. This `Offering ID` instructs your application to apply the dynamic pricing and pricing table configuration determined by the linked Targeting Rule.
231
+
232
+
233
+
234
+ <img height="200" src="/images/offering-id-to-copy.png" />
235
+
236
+
237
+
238
+ ---
239
+
240
+ ## Managing Targeting Rules and Offerings Post-Creation
241
+
242
+ While rule conditions are immutable, you retain flexibility in managing your targeting strategies through rule naming and Offering edits.
243
+
244
+ ### Editing Targeting Rule Names
245
+ To maintain clarity and organization, you can edit the name of a Targeting Rule after its creation. The rule's conditions and price adjustments remain unchanged.
246
+ 1. Navigate to **Monetization > Targeting Rules**.
247
+ 2. Locate the rule you wish to rename in the list.
248
+ 3. Click the **three-dot menu icon** on that rule's row and select **"Edit"**.
249
+
250
+
251
+ <img height="200" src="/images/edit-targeting-rules.png" />
252
+
253
+
254
+ 4. Modify the name in the input field and save your changes.
255
+
256
+ ### Editing Offerings to Change Targeting Rules or Pricing Tables
257
+ The primary way to manage and iterate on your live targeting strategies is by editing the **Offering**. This approach provides significant flexibility without requiring code changes in your application.
258
+
259
+ **No Code Changes Needed for Iteration!**
260
+ This system is specifically designed so that Product Managers, Go-To-Market teams, and Sales teams can dynamically update pricing strategies. You can roll out new pricing tables, switch which Targeting Rule an Offering uses, or adjust the pricing table linked to an Offering, all from the Kelviq dashboard. The Offering ID in your application remains the same, ensuring seamless updates.
261
+
262
+ 1. Navigate to **Monetization > Offerings**.
263
+ 2. Find the Offering you wish to modify in the list.
264
+ 3. Click "**Edit**" icon.
265
+
266
+
267
+ <img height="200" src="/images/edit-offering.png" />
268
+
269
+
270
+ 4. In the "Edit offering" modal, you can:
271
+ * Select a **different Targeting Rule** from the dropdown to change the pricing logic applied.
272
+ * Select a **different Pricing Table** from the dropdown to change the visual presentation.
273
+
274
+
275
+ <img height="200" src="/images/offerings-edit.png" />
276
+
277
+
278
+ 5. Click **"Update"**. The Offering ID embedded in your code remains unchanged, but it now serves the new configuration (new rule and/or new pricing table) to your users.