> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # Issue Entitlement > Issue a new entitlement to a customer, granting them access to a specific feature. The feature must exist and belong to the same merchant as the customer. ## OpenAPI ````yaml /openapi.json post /v1/entitlements openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v1/entitlements: post: tags: - Entitlements summary: Issue Entitlement description: >- Issue a new entitlement to a customer, granting them access to a specific feature. The feature must exist and belong to the same merchant as the customer. operationId: issueEntitlement requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IssueEntitlementRequest' examples: booleanEntitlement: summary: Issue a boolean feature entitlement description: Grant access to a simple on/off feature like SSO. value: customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_a1b2c3d4e5f6g7h8 template: type: boolean staticEntitlement: summary: Issue a static feature entitlement with config description: >- Grant access to a feature with configuration values like seat limits. value: customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_a1b2c3d4e5f6g7h8 template: type: static config: limit: 25 tier: pro timedEntitlement: summary: Issue a time-limited entitlement description: Grant access to a feature with specific start and end dates. value: customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_a1b2c3d4e5f6g7h8 template: type: boolean activeFrom: '2024-01-01T00:00:00Z' activeTo: '2025-01-01T00:00:00Z' responses: '201': description: >- Entitlement successfully issued. Returns the same shape as `GET /v1/entitlements/{entitlementId}` (a discriminated `EntitlementDetail`), so callers can read `featureType`, `hasAccess`, and metered balance/usage fields directly from the create response. content: application/json: schema: $ref: '#/components/schemas/EntitlementDetail' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' components: schemas: IssueEntitlementRequest: type: object required: - customerId - featureId - template properties: customerId: $ref: '#/components/schemas/CustomerId' description: The customer to issue the entitlement to. featureId: type: string pattern: ^feat_[a-zA-Z0-9]+$ description: The feature to grant access to. template: $ref: '#/components/schemas/EntitlementTemplate' description: The template defining the entitlement type and configuration. activeFrom: type: string format: date-time description: When the entitlement becomes active. Defaults to now. activeTo: type: string format: date-time nullable: true description: When the entitlement expires. Null means no expiration. subscriptionId: type: string nullable: true description: Optional subscription ID to associate with this entitlement. metadata: type: object additionalProperties: type: string description: Additional metadata for the entitlement. EntitlementDetail: oneOf: - $ref: '#/components/schemas/BooleanEntitlementDetail' - $ref: '#/components/schemas/StaticEntitlementDetail' - $ref: '#/components/schemas/MeteredEntitlementDetail' discriminator: propertyName: featureType mapping: boolean: $ref: '#/components/schemas/BooleanEntitlementDetail' static: $ref: '#/components/schemas/StaticEntitlementDetail' metered: $ref: '#/components/schemas/MeteredEntitlementDetail' description: A specific entitlement. The response shape varies by featureType. CustomerId: type: string pattern: ^cus_[a-zA-Z0-9]+$ description: Unique identifier for a customer EntitlementTemplate: oneOf: - type: object required: - type properties: type: type: string enum: - boolean - type: object required: - type - config properties: type: type: string enum: - static config: type: object additionalProperties: true description: Configuration values for the entitlement. - type: object required: - type properties: type: type: string enum: - metered usagePeriod: type: object description: >- Recurrence configuration. Omit for a one-time grant that does not refill. required: - interval properties: interval: type: string description: >- ISO 8601 duration for the usage period, e.g. P1D, P1W, P1M, P1Y. anchor: type: string format: date-time description: Optional anchor date-time for period alignment. isSoftLimit: type: boolean description: >- When false (hard limit), access is blocked when balance is exhausted and overage is not charged on invoices. When true (soft limit), access continues past the grant and overage is charged at the per-unit rate. issueAfterReset: type: number minimum: 0 description: >- Credits issued at each period reset. Set to 0 for entitlements without included credits; top-ups may be supplied via direct grants or grant purchases. issueAfterResetPriority: type: integer description: Priority for grants issued after reset. preserveOverageAtReset: type: boolean description: When true, overage from the previous period carries over. resetMaxRollover: type: number description: Maximum amount of unused balance that rolls over on reset. resetMinRollover: type: number description: Minimum amount of balance guaranteed to roll over on reset. description: >- Template for the entitlement. Boolean for simple on/off features, static for features with configuration, metered for usage-based features. BooleanEntitlementDetail: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementDetailBase' - type: object required: - config properties: featureType: type: string enum: - boolean config: type: object nullable: true additionalProperties: true description: >- Always `null` for boolean entitlements. Surfaced on every entitlement so clients can read `config` without first switching on `featureType`. StaticEntitlementDetail: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementDetailBase' - type: object required: - config properties: featureType: type: string enum: - static config: type: object additionalProperties: true description: Configuration values for this entitlement. MeteredEntitlementDetail: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementDetailBase' - type: object required: - balance - usageInPeriod - overage - isSoftLimit - config - currentPeriodStart - currentPeriodEnd - pricingUnitId properties: featureType: type: string enum: - metered config: type: object nullable: true additionalProperties: true description: >- Always `null` for metered entitlements. Surfaced on every entitlement so clients can read `config` without first switching on `featureType`. isSoftLimit: type: boolean description: >- When false (hard limit), access is blocked when balance is exhausted and overage is not charged on invoices. When true (soft limit), access continues past the grant and overage is charged at the per-unit rate. balance: type: number description: >- Remaining balance for the current period. When `pricingUnitId` is set, this is expressed in that pricing unit's credits (a balance shared across every feature drawing the same unit); otherwise it is in the feature's native metered units. usageInPeriod: type: number description: >- Total usage consumed in the current billing period, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units). When `pricingUnitId` is set, this is the shared-pool aggregate across every feature drawing the same unit, not usage specific to this feature. overage: type: number description: >- Amount of usage exceeding the balance, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units). pricingUnitId: type: string nullable: true pattern: ^pu_[a-zA-Z0-9]+$ description: >- The pricing unit this feature is denominated in when it draws a credit pool. When set, `balance`/`usageInPeriod`/`overage` are in that unit's credits and reflect a balance shared across all features on the same unit. `null` for currency-denominated features (native metered units). currentPeriodStart: type: string format: date-time nullable: true description: >- Start of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation "dark window", when the query time is earlier than `activeFrom`) this instead describes the pre-activation `[subscription start, activation)` window and may be `null` when there is no associated subscription. currentPeriodEnd: type: string format: date-time nullable: true description: >- End of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation "dark window", when the query time is earlier than `activeFrom`) this instead holds `activeFrom` — the end of the pre-activation `[subscription start, activation)` window. Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format EntitlementDetailBase: type: object description: Common fields shared by all entitlement types. required: - object - id - customerId - featureId - featureKey - featureType - productId - subscriptionId - status - activeFrom - activeTo - hasAccess - metadata properties: object: type: string enum: - entitlement default: entitlement id: type: string pattern: ^ent_[a-zA-Z0-9]+$ description: Unique identifier for the entitlement. customerId: $ref: '#/components/schemas/CustomerId' featureId: type: string pattern: ^feat_[a-zA-Z0-9]+$ description: The feature this entitlement grants access to. featureKey: type: string description: The unique key identifying the feature. featureType: $ref: '#/components/schemas/EntitlementFeatureType' productId: $ref: '#/components/schemas/ProductId' subscriptionId: type: string nullable: true description: The subscription this entitlement is associated with, if any. status: $ref: '#/components/schemas/EntitlementStatus' activeFrom: type: string format: date-time description: When the entitlement becomes active. activeTo: type: string format: date-time nullable: true description: When the entitlement expires. Null means no expiration. hasAccess: type: boolean description: >- Whether the customer currently has active access to this entitlement. metadata: type: object additionalProperties: type: string description: Additional metadata for the entitlement. EntitlementFeatureType: type: string enum: - boolean - static - metered description: The type of feature. ProductId: type: string pattern: ^prod_[a-zA-Z0-9]+$ description: Unique identifier for a product EntitlementStatus: type: string enum: - active - canceled - expired description: Current status of the entitlement. responses: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not Found - The requested resource could not be found content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Conflict - The request conflicts with the current state of the resource content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````