For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SupportDashboard
Getting StartedAPI ReferenceRoadmapBlog
Getting StartedAPI ReferenceRoadmapBlog
    • Resources
    • Authentication
    • Pagination
    • Rate limiting
  • API Keys
    • GETList api keys
    • GETGet api key
    • POSTCreate api key
    • PUTUpdate api key
    • DELDelete api key
  • Environments
    • POSTCreate environment
    • PUTUpdate environment
    • DELDelete environment
  • Plans
    • The Plan object
    • GETList plans
    • GETGet plan
    • POSTCreate plan
    • PUTUpdate plan
    • DELDelete plan
  • Companies
    • The Company object
    • GETList companies
    • POSTUpsert company
    • GETLookup company
    • DELDelete company
    • POSTDelete company by keys
    • GETList company memberships
    • POSTGet or create company membership
    • DELDelete company membership
    • POSTUpsert company trait
  • Users
    • The User object
    • GETList users
    • GETLookup user
    • POSTUpsert user
    • DELDelete user
    • POSTDelete user by keys
    • POSTUpsert user trait
  • Events
    • The Event object
    • GETList events
    • POSTCreate event
    • POSTCreate event batch
    • GETGet event
  • Features
    • The Feature object
    • GETList features
    • GETGet feature
    • POSTCreate feature
    • PUTUpdate feature
    • DELDelete feature
  • Flags
    • The Flag object
    • GETList flags
    • GETGet flag
    • POSTCreate flag
    • PUTUpdate flag
    • DELDelete flag
    • PUTUpdate flag rules
    • POSTCheck flag
    • POSTCheck flags
  • Entitlements
    • GETList company overrides
    • GETGet company override
    • POSTCreate company override
    • PUTUpdate company override
    • DELDelete company override
    • GETList plan entitlements
    • GETGet plan entitlement
    • POSTCreate plan entitlement
    • PUTUpdate plan entitlement
    • DELDelete plan entitlement
  • Feature Usage
    • GETList feature usage
  • Billing Credits
    • GETList credits
    • POSTCreate credit
    • GETGet credit
    • PUTUpdate credit
    • DELDelete credit
    • GETList credit bundles
    • POSTCreate credit bundle
    • GETGet credit bundle
    • PUTUpdate credit bundle
    • DELDelete credit bundle
    • POSTGrant credits to company
    • GETList company credit grants
    • GETList credit grants
    • PUTZero out credit grant
    • GETList plan credit grants
    • POSTCreate plan credit grant
    • DELDelete plan credit grant
    • GETGet credit ledger
  • Account Members
    • GETList account members
    • GETGet account member
LogoLogo
SupportDashboard
Entitlements

Create plan entitlement

POST
https://api.schematichq.com/plan-entitlements
POST
/plan-entitlements
1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3async function main() {
4    const client = new SchematicClient({
5        apiKey: "YOUR_API_KEY_HERE",
6    });
7    await client.entitlements.createPlanEntitlement({
8        featureId: "f8a1c2d4-3b6e-4f9a-9d2e-7b5c1a2e3d4f",
9        planId: "p9b2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
10        valueType: "boolean",
11    });
12}
13main();
1{
2  "data": {
3    "created_at": "2024-01-15T09:30:00Z",
4    "currency_prices": [
5      {
6        "currency": "USD",
7        "monthly_price": {
8          "billing_scheme": "per_unit",
9          "created_at": "2024-01-15T09:30:00Z",
10          "currency": "USD",
11          "id": "price-monthly-001",
12          "interval": "month",
13          "interval_count": 1,
14          "is_active": true,
15          "package_size": 1,
16          "price": 1500,
17          "price_external_id": "ext-price-monthly-001",
18          "price_id": "price-monthly-001",
19          "price_tier": [
20            {
21              "flat_amount": 500,
22              "per_unit_price": 100,
23              "per_unit_price_decimal": "1.00",
24              "up_to": 1000
25            }
26          ],
27          "product_external_id": "prod-ext-001",
28          "product_id": "prod-001",
29          "product_name": "Standard Product",
30          "provider_type": "metronome",
31          "updated_at": "2024-01-15T09:30:00Z",
32          "usage_type": "licensed",
33          "meter_event_name": "usage_event",
34          "meter_event_payload_key": "units_used",
35          "meter_id": "meter-123",
36          "nickname": "Standard Monthly Price",
37          "price_decimal": "15.00",
38          "tiers_mode": "graduated"
39        },
40        "quarterly_price": {
41          "billing_scheme": "per_unit",
42          "created_at": "2024-01-15T09:30:00Z",
43          "currency": "USD",
44          "id": "price-quarterly-001",
45          "interval": "month",
46          "interval_count": 3,
47          "is_active": true,
48          "package_size": 1,
49          "price": 4200,
50          "price_external_id": "ext-price-quarterly-001",
51          "price_id": "price-quarterly-001",
52          "price_tier": [
53            {
54              "flat_amount": 1200,
55              "per_unit_price": 90,
56              "per_unit_price_decimal": "0.90",
57              "up_to": 3000
58            }
59          ],
60          "product_external_id": "prod-ext-001",
61          "product_id": "prod-001",
62          "product_name": "Standard Product",
63          "provider_type": "metronome",
64          "updated_at": "2024-01-15T09:30:00Z",
65          "usage_type": "licensed",
66          "meter_event_name": "usage_event",
67          "meter_event_payload_key": "units_used",
68          "meter_id": "meter-123",
69          "nickname": "Standard Quarterly Price",
70          "price_decimal": "42.00",
71          "tiers_mode": "graduated"
72        },
73        "yearly_price": {
74          "billing_scheme": "per_unit",
75          "created_at": "2024-01-15T09:30:00Z",
76          "currency": "USD",
77          "id": "price-yearly-001",
78          "interval": "year",
79          "interval_count": 1,
80          "is_active": true,
81          "package_size": 1,
82          "price": 15000,
83          "price_external_id": "ext-price-yearly-001",
84          "price_id": "price-yearly-001",
85          "price_tier": [
86            {
87              "flat_amount": 4000,
88              "per_unit_price": 80,
89              "per_unit_price_decimal": "0.80",
90              "up_to": 12000
91            }
92          ],
93          "product_external_id": "prod-ext-001",
94          "product_id": "prod-001",
95          "product_name": "Standard Product",
96          "provider_type": "metronome",
97          "updated_at": "2024-01-15T09:30:00Z",
98          "usage_type": "licensed",
99          "meter_event_name": "usage_event",
100          "meter_event_payload_key": "units_used",
101          "meter_id": "meter-123",
102          "nickname": "Standard Yearly Price",
103          "price_decimal": "150.00",
104          "tiers_mode": "graduated"
105        }
106      }
107    ],
108    "environment_id": "env-7890",
109    "feature_id": "f8a1c2d4-3b6e-4f9a-9d2e-7b5c1a2e3d4f",
110    "id": "entitlement-9876",
111    "plan_id": "p9b2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
112    "rule_id": "rule-7890",
113    "updated_at": "2024-01-15T09:30:00Z",
114    "value_type": "boolean",
115    "billing_linked_resource": {
116      "billing_provider": "metronome",
117      "external_resource_id": "ext-res-12345",
118      "originator": "metronome"
119    },
120    "billing_threshold": 100,
121    "consumption_rate": 2.5,
122    "feature": {
123      "created_at": "2024-01-10T08:00:00Z",
124      "description": "Enables advanced analytics features",
125      "feature_type": "boolean",
126      "icon": "analytics",
127      "id": "feat-1234",
128      "name": "Advanced Analytics",
129      "updated_at": "2024-01-12T10:00:00Z",
130      "event_subtype": "feature_toggle",
131      "lifecycle_phase": "ga",
132      "maintainer_account_member_id": "member-5678",
133      "plural_name": "Advanced Analytics Features",
134      "singular_name": "Advanced Analytics Feature",
135      "trait_id": "trait-4321"
136    },
137    "metered_monthly_price": {
138      "billing_scheme": "per_unit",
139      "created_at": "2024-01-15T09:30:00Z",
140      "currency": "USD",
141      "id": "price-monthly-001",
142      "interval": "month",
143      "interval_count": 1,
144      "is_active": true,
145      "package_size": 1,
146      "price": 1500,
147      "price_external_id": "ext-price-monthly-001",
148      "price_id": "price-monthly-001",
149      "price_tier": [
150        {
151          "flat_amount": 500,
152          "per_unit_price": 100,
153          "per_unit_price_decimal": "1.00",
154          "up_to": 1000
155        }
156      ],
157      "product_external_id": "prod-ext-001",
158      "product_id": "prod-001",
159      "product_name": "Standard Product",
160      "provider_type": "metronome",
161      "updated_at": "2024-01-15T09:30:00Z",
162      "usage_type": "licensed",
163      "meter_event_name": "usage_event",
164      "meter_event_payload_key": "units_used",
165      "meter_id": "meter-123",
166      "nickname": "Monthly Metered Price",
167      "price_decimal": "15.00",
168      "tiers_mode": "graduated"
169    },
170    "metered_quarterly_price": {
171      "billing_scheme": "per_unit",
172      "created_at": "2024-01-15T09:30:00Z",
173      "currency": "USD",
174      "id": "price-quarterly-001",
175      "interval": "month",
176      "interval_count": 3,
177      "is_active": true,
178      "package_size": 1,
179      "price": 4200,
180      "price_external_id": "ext-price-quarterly-001",
181      "price_id": "price-quarterly-001",
182      "price_tier": [
183        {
184          "flat_amount": 1200,
185          "per_unit_price": 90,
186          "per_unit_price_decimal": "0.90",
187          "up_to": 3000
188        }
189      ],
190      "product_external_id": "prod-ext-001",
191      "product_id": "prod-001",
192      "product_name": "Standard Product",
193      "provider_type": "metronome",
194      "updated_at": "2024-01-15T09:30:00Z",
195      "usage_type": "licensed",
196      "meter_event_name": "usage_event",
197      "meter_event_payload_key": "units_used",
198      "meter_id": "meter-123",
199      "nickname": "Quarterly Metered Price",
200      "price_decimal": "42.00",
201      "tiers_mode": "graduated"
202    },
203    "metered_yearly_price": {
204      "billing_scheme": "per_unit",
205      "created_at": "2024-01-15T09:30:00Z",
206      "currency": "USD",
207      "id": "price-yearly-001",
208      "interval": "year",
209      "interval_count": 1,
210      "is_active": true,
211      "package_size": 1,
212      "price": 15000,
213      "price_external_id": "ext-price-yearly-001",
214      "price_id": "price-yearly-001",
215      "price_tier": [
216        {
217          "flat_amount": 4000,
218          "per_unit_price": 80,
219          "per_unit_price_decimal": "0.80",
220          "up_to": 12000
221        }
222      ],
223      "product_external_id": "prod-ext-001",
224      "product_id": "prod-001",
225      "product_name": "Standard Product",
226      "provider_type": "metronome",
227      "updated_at": "2024-01-15T09:30:00Z",
228      "usage_type": "licensed",
229      "meter_event_name": "usage_event",
230      "meter_event_payload_key": "units_used",
231      "meter_id": "meter-123",
232      "nickname": "Yearly Metered Price",
233      "price_decimal": "150.00",
234      "tiers_mode": "graduated"
235    },
236    "metric_period": "all_time",
237    "metric_period_month_reset": "billing_cycle",
238    "plan": {
239      "created_at": "2023-12-01T12:00:00Z",
240      "description": "Enterprise plan with advanced features",
241      "icon": "amber",
242      "id": "p9b2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
243      "name": "Enterprise Plan",
244      "plan_type": "plan",
245      "updated_at": "2024-01-10T15:00:00Z",
246      "company_id": "comp-12345",
247      "copied_from_plan_id": "plan-54321",
248      "audience_type": "enterprise"
249    },
250    "price_behavior": "credit_burndown",
251    "rule_id_usage_exceeded": "rule-usage-exceeded-7890",
252    "soft_limit": 500,
253    "usage_based_product": {
254      "account_id": "acc-4567",
255      "created_at": "2024-01-10T08:00:00Z",
256      "environment_id": "env-7890",
257      "external_id": "prod-ext-usage-001",
258      "is_active": true,
259      "name": "Usage Based Product",
260      "price": 0.05,
261      "product_id": "prod-usage-001",
262      "provider_type": "metronome",
263      "quantity": 1000,
264      "updated_at": "2024-01-15T09:30:00Z",
265      "price_decimal": "0.05",
266      "currency": "USD"
267    },
268    "usage_quantity": 100,
269    "value_bool": true,
270    "value_credit": {
271      "burn_strategy": "expiration_priority",
272      "cost_editable": true,
273      "created_at": "2024-01-15T09:30:00Z",
274      "currency_prices": [
275        {
276          "currency": "USD",
277          "price": {
278            "currency": "USD",
279            "external_price_id": "ext-price-credit-001",
280            "id": "price-credit-001",
281            "interval": "month",
282            "interval_count": 1,
283            "price": 1000,
284            "provider_type": "metronome",
285            "scheme": "per_unit",
286            "nickname": "Credit Monthly Price",
287            "price_decimal": "10.00"
288          }
289        }
290      ],
291      "default_expiry_unit": "billing_periods",
292      "default_rollover_policy": "expire",
293      "description": "Credit for additional usage",
294      "id": "credit-1234",
295      "name": "Additional Usage Credit",
296      "updated_at": "2024-01-15T09:30:00Z",
297      "default_expiry_unit_count": 12,
298      "icon": "credit_icon",
299      "plural_name": "Additional Usage Credits",
300      "price": {
301        "currency": "USD",
302        "external_price_id": "ext-price-credit-001",
303        "id": "price-credit-001",
304        "interval": "month",
305        "interval_count": 1,
306        "price": 1000,
307        "provider_type": "metronome",
308        "scheme": "per_unit",
309        "nickname": "Credit Monthly Price",
310        "price_decimal": "10.00"
311      },
312      "product": {
313        "account_id": "acc-4567",
314        "created_at": "2024-01-10T08:00:00Z",
315        "environment_id": "env-7890",
316        "external_id": "prod-ext-credit-001",
317        "is_active": true,
318        "name": "Credit Product",
319        "price": 10,
320        "product_id": "prod-credit-001",
321        "provider_type": "metronome",
322        "quantity": 1,
323        "updated_at": "2024-01-15T09:30:00Z",
324        "price_decimal": "10.00",
325        "currency": "USD"
326      },
327      "singular_name": "Additional Usage Credit"
328    },
329    "value_numeric": 10,
330    "value_trait": {
331      "created_at": "2024-01-10T08:00:00Z",
332      "display_name": "Premium User",
333      "entity_type": "company",
334      "hierarchy": [
335        "tier1",
336        "tier2"
337      ],
338      "id": "trait-5678",
339      "trait_type": "boolean",
340      "updated_at": "2024-01-12T10:00:00Z"
341    },
342    "value_trait_id": "trait-5678"
343  },
344  "params": {}
345}
Was this page helpful?
Previous

Update plan entitlement

Next
Built with

Authentication

X-Schematic-Api-Keystring
API Key authentication via header

Request

This endpoint expects an object.
feature_idstringRequired
plan_idstringRequired
value_typeenumRequired
billing_product_idstring or nullOptional
billing_thresholdlong or nullOptional50-9999999999999
credit_consumption_ratedouble or nullOptional
currencystring or nullOptional
currency_priceslist of objects or nullOptional
metric_periodenum or nullOptional
Allowed values:
metric_period_month_resetenum or nullOptional
Allowed values:
monthly_price_tierslist of objects or nullOptional
monthly_unit_pricelong or nullOptional
monthly_unit_price_decimalstring or nullOptional
plan_version_idstring or nullOptional
price_behaviorenum or nullOptional
Allowed values:
quarterly_price_tierslist of objects or nullOptional
quarterly_unit_pricelong or nullOptional
quarterly_unit_price_decimalstring or nullOptional
soft_limitlong or nullOptional
tier_modeenum or nullOptional
Allowed values:
usage_quantitylong or nullOptional>=0

The committed unit quantity for this entitlement. For custom plans this is the quantity the company is contractually committed to; for standard plans it is the quantity pre-filled when subscribing. Only applies to pay-in-advance entitlements. Note: this is not yet enforced/auto-provisioned as a true default — it is currently stored for downstream billing use.

value_boolboolean or nullOptional
value_credit_idstring or nullOptional
value_numericlong or nullOptional
value_trait_idstring or nullOptional
yearly_price_tierslist of objects or nullOptional
yearly_unit_pricelong or nullOptional
yearly_unit_price_decimalstring or nullOptional
monthly_metered_price_idstring or nullOptionalDeprecated
overage_billing_product_idstring or nullOptionalDeprecated
price_tierslist of objects or nullOptionalDeprecated
Use MonthlyPriceTiers or YearlyPriceTiers instead
quarterly_metered_price_idstring or nullOptionalDeprecated
yearly_metered_price_idstring or nullOptionalDeprecated

Response

Created
dataobject
paramsobject
Input parameters

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error