> ## Documentation Index > Fetch the complete documentation index at: https://docs.unprice.dev/llms.txt > Use this file to discover all available pages before exploring further. # apply monetization configuration > Turn one configuration document into draft plan versions for this project. Nothing is published: a human reviews and publishes the drafts from the dashboard. ## OpenAPI ````yaml /openapi.json post /v1/monetization/apply openapi: 3.0.3 info: title: Unprice API version: 1.0.0 servers: - url: https://api.unprice.dev description: Production - url: http://localhost:8787 description: Development - url: https://preview-api.unprice.dev description: Preview security: - bearerAuth: [] paths: /v1/monetization/apply: post: tags: - monetization summary: apply monetization configuration description: >- Turn one configuration document into draft plan versions for this project. Nothing is published: a human reviews and publishes the drafts from the dashboard. operationId: monetization.apply requestBody: description: >- The desired monetization configuration for the project the key belongs to required: true content: application/json: schema: type: object properties: config: type: object properties: events: type: array items: type: object properties: slug: type: string minLength: 1 maxLength: 64 pattern: ^[a-z0-9._-]+$ description: >- Project-scoped SDK event slug. Example: 'llm_completion' or 'storage_snapshot' name: type: string minLength: 1 maxLength: 64 description: >- Human-readable event name. Example: 'AI Completion' availableProperties: type: array nullable: true items: type: string minLength: 1 maxLength: 64 pattern: ^[a-z0-9._-]+$ description: >- Optional list of numeric payload properties available for aggregation. Example: ['input_tokens', 'output_tokens'] required: - slug - name additionalProperties: false description: >- An SDK event the application reports. Meters aggregate over these default: [] features: type: array items: type: object properties: slug: type: string minLength: 1 description: >- URL-friendly unique identifier for the feature. Must be lowercase with hyphens only. Used for API lookups and references. Example: 'api-calls', 'storage-gb', 'team-members' title: type: string minLength: 1 maxLength: 50 description: >- Human-readable name for the feature displayed to users. Must contain only letters, numbers, and spaces. Example: 'API Calls', 'Storage GB', 'Team Members' description: type: string nullable: true description: >- Detailed explanation of what the feature provides or enables. Helps users understand the feature's purpose and value. Example: 'Number of API requests allowed per billing period' unitOfMeasure: type: string default: units description: >- Unit of measurement for the feature. Describes what is being counted or measured. Examples: 'calls', 'GB', 'seats', 'tokens', 'requests', 'minutes'. Defaults to 'units' if not specified required: - slug - title additionalProperties: false description: >- A feature the application sells. Plan versions price it default: [] plans: type: array items: type: object properties: slug: type: string minLength: 3 description: >- URL-friendly plan identifier (lowercase, hyphens). Examples: 'starter', 'pro', 'enterprise'. This becomes the parent for all plan versions. title: type: string description: >- Human-readable plan title (1-50 chars). Will be UPPERCASED. Examples: 'Starter', 'Pro', 'Enterprise' description: type: string description: >- Description of the plan explaining its target audience and value proposition defaultPlan: type: boolean nullable: true description: >- Whether this is the default plan shown to new users (only one plan can be default). Use for your 'Starter' or 'Free' tier. version: type: object properties: currency: type: string enum: - USD - EUR description: >- Required. ISO 4217 currency code. Examples: 'USD', 'EUR'. Determines the currency for all pricing in this version paymentProvider: type: string enum: - stripe - square - sandbox paymentMethodRequired: type: boolean default: true description: >- Whether a customer must provide a payment method before starting this plan. Defaults to true billingConfig: type: object properties: name: type: string minLength: 1 description: >- Human-readable cadence name. Example: 'monthly' interval: type: string enum: - month - year - week - day - minute - onetime description: 'Billing interval. Example: ''month''' intervalCount: type: integer minimum: 1 maximum: 60 description: Number of intervals per billing period required: - name - interval - intervalCount additionalProperties: false description: >- Billing cadence for the plan version. The server derives billingAnchor and planType from it features: type: array items: type: object properties: featureSlug: type: string minLength: 1 description: >- Slug of a feature declared in this document featureType: type: string enum: - flat - tier - package - usage description: '''flat'', ''tier'', ''package'', or ''usage''' config: type: object properties: price: type: string pattern: ^\d{1,8}(\.\d{1,8})?$ description: >- Price as a decimal string. Example: '0.000002' usageMode: type: string enum: - tier - package - unit description: >- How usage is calculated and billed: 'unit' (per-unit pricing), 'tier' (volume-based tiers), or 'package' (bundle of units) tierMode: type: string enum: - volume - graduated description: >- Tier calculation method when usageMode is 'tier': 'volume' or 'graduated'. Only applicable when usageMode is 'tier' tiers: type: array items: type: object properties: unitPrice: type: string pattern: ^\d{1,8}(\.\d{1,8})?$ description: >- Price per unit inside this tier, as a decimal string flatPrice: type: string pattern: ^\d{1,8}(\.\d{1,8})?$ description: >- Fixed price for entering this tier, as a decimal string firstUnit: type: integer minimum: 1 description: >- The starting unit number for this tier (inclusive). Must be 1 for the first tier, and consecutive with previous tier's lastUnit + 1 for subsequent tiers lastUnit: type: integer nullable: true minimum: 1 description: >- The ending unit number for this tier (inclusive). Set to null for the final tier to indicate unlimited. Example: 1000 means this tier covers up to 1000 units label: type: string description: >- Display name for this tier shown in pricing UI. Examples: 'Starter', 'Growth', 'Enterprise', '1-100 units' required: - unitPrice - flatPrice - firstUnit - lastUnit additionalProperties: false description: >- Configuration for a single pricing tier defining unit ranges and associated pricing description: Pricing tiers, decimal strings units: type: integer minimum: 1 description: >- Number of units in a package when usageMode is 'package'. Required for package mode. Example: 100 API calls per package additionalProperties: false description: >- Pricing configuration. Prices cross the boundary as decimal strings, never as Dinero meterConfig: type: object properties: eventSlug: type: string minLength: 1 aggregationMethod: type: string enum: - sum - count - max - latest description: >- How to aggregate usage events within the current billing period. 'sum' totals values, 'count' counts events, 'max' keeps the highest value, and 'latest' keeps the most recent value. aggregationField: type: string minLength: 1 required: - eventSlug - aggregationMethod additionalProperties: false description: >- How usage is measured from a declared event limit: anyOf: - type: number - type: string pattern: ^\d+$ description: >- Maximum usage per reset window. Omit for unlimited resetConfig: type: object properties: interval: type: string enum: - month - year - week - day - minute - onetime description: 'Reset interval. Example: ''day''' intervalCount: type: integer minimum: 1 maximum: 60 default: 1 description: >- Number of intervals per reset window. Defaults to 1 required: - interval additionalProperties: false description: >- When usage counters reset. Omit to reset on the billing cadence required: - featureSlug - featureType - config additionalProperties: false minItems: 1 required: - currency - paymentProvider - billingConfig - features additionalProperties: false required: - slug - title - version additionalProperties: false minItems: 1 required: - plans additionalProperties: false description: The whole desired monetization configuration for a project required: - config additionalProperties: false responses: '200': description: >- Per-plan outcomes, drafts left behind by earlier documents, what the application has to call at runtime, and a dashboard link to the first draft created for review content: application/json: schema: type: object properties: plans: type: array items: type: object properties: slug: type: string planVersionId: type: string status: type: string enum: - created - unchanged - published description: >- 'created' when this apply wrote or finished a draft, 'unchanged' when a complete draft already matched, 'published' when a live version already matches required: - slug - planVersionId - status description: >- One outcome per plan, in the same order as the `plans` of the submitted document staleDrafts: type: array items: type: object properties: slug: type: string description: Slug of the plan the draft belongs to planVersionId: type: string required: - slug - planVersionId description: >- Drafts made by an earlier, now-superseded document, plus same-hash duplicates left by a concurrent apply. Reported, never deleted integrationContract: type: object properties: defaultPlan: type: object properties: slug: type: string planVersionId: type: string note: type: string required: - slug - planVersionId - note events: type: array items: type: object properties: slug: type: string name: type: string requiredProperties: type: array items: type: string description: >- Numeric payload properties the application must send for the meters to work required: - slug - name - requiredProperties features: type: array items: type: object properties: slug: type: string kind: type: string enum: - flat-access - usage-gate - usage-evidence - run-budget description: >- How the application integrates the feature: entitlement check only ('flat-access'), synchronous allowance check before the work ('usage-gate'), usage reported after the work ('usage-evidence'), or work executed inside a budgeted run ('run-budget') eventSlug: type: string nullable: true planSlugs: type: array items: type: string required: - slug - kind - eventSlug - planSlugs warnings: type: array items: type: object properties: featureSlug: type: string code: type: string enum: - usage_unknown_before_work message: type: string required: - featureSlug - code - message required: - defaultPlan - events - features - warnings description: >- What the application has to call at runtime for this configuration to work reviewUrl: type: string nullable: true format: uri description: >- Dashboard link to the first draft this apply created, for a human to review and publish. Null when no draft was created — every plan was already unchanged or published — and also null when the link could not be built, so a null here does not prove nothing was created; read `plans` for that required: - plans - staleDrafts - integrationContract - reviewUrl '400': description: >- The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' '401': description: >- Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' '403': description: >- The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. content: application/json: schema: $ref: '#/components/schemas/ErrForbidden' '404': description: >- The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' '409': description: >- This response is sent when a request conflicts with the current state of the server. content: application/json: schema: $ref: '#/components/schemas/ErrConflict' '412': description: >- The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails. content: application/json: schema: $ref: '#/components/schemas/ErrPreconditionFailed' '413': description: The request payload is larger than the server is willing to process. content: application/json: schema: $ref: '#/components/schemas/ErrPayloadTooLarge' '429': description: >- The user has sent too many requests in a given amount of time ("rate limiting") content: application/json: schema: $ref: '#/components/schemas/ErrTooManyRequests' '500': description: >- The server has encountered a situation it does not know how to handle. content: application/json: schema: $ref: '#/components/schemas/ErrInternalServerError' components: schemas: ErrBadRequest: type: object properties: error: type: object properties: code: type: string enum: - BAD_REQUEST description: A machine readable error code. example: BAD_REQUEST docs: type: string description: >- A link to our documentation with more details about this error code example: https://docs.unprice.dev/api-reference/errors/code/BAD_REQUEST message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrUnauthorized: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHORIZED description: A machine readable error code. example: UNAUTHORIZED docs: type: string description: >- A link to our documentation with more details about this error code example: https://docs.unprice.dev/api-reference/errors/code/UNAUTHORIZED message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrForbidden: type: object properties: error: type: object properties: code: type: string enum: - FORBIDDEN description: A machine readable error code. example: FORBIDDEN docs: type: string description: >- A link to our documentation with more details about this error code example: https://docs.unprice.dev/api-reference/errors/code/FORBIDDEN message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrNotFound: type: object properties: error: type: object properties: code: type: string enum: - NOT_FOUND description: A machine readable error code. example: NOT_FOUND docs: type: string description: >- A link to our documentation with more details about this error code example: https://docs.unprice.dev/api-reference/errors/code/NOT_FOUND message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrConflict: type: object properties: error: type: object properties: code: type: string enum: - CONFLICT description: A machine readable error code. example: CONFLICT docs: type: string description: >- A link to our documentation with more details about this error code example: https://docs.unprice.dev/api-reference/errors/code/CONFLICT message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrPreconditionFailed: type: object properties: error: type: object properties: code: type: string enum: - PRECONDITION_FAILED description: A machine readable error code. example: PRECONDITION_FAILED docs: type: string description: >- A link to our documentation with more details about this error code example: >- https://docs.unprice.dev/api-reference/errors/code/PRECONDITION_FAILED message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrPayloadTooLarge: type: object properties: error: type: object properties: code: type: string enum: - PAYLOAD_TOO_LARGE description: A machine readable error code. example: PAYLOAD_TOO_LARGE docs: type: string description: >- A link to our documentation with more details about this error code example: >- https://docs.unprice.dev/api-reference/errors/code/PAYLOAD_TOO_LARGE message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrTooManyRequests: type: object properties: error: type: object properties: code: type: string enum: - TOO_MANY_REQUESTS description: A machine readable error code. example: TOO_MANY_REQUESTS docs: type: string description: >- A link to our documentation with more details about this error code example: >- https://docs.unprice.dev/api-reference/errors/code/TOO_MANY_REQUESTS message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error ErrInternalServerError: type: object properties: error: type: object properties: code: type: string enum: - INTERNAL_SERVER_ERROR description: A machine readable error code. example: INTERNAL_SERVER_ERROR docs: type: string description: >- A link to our documentation with more details about this error code example: >- https://docs.unprice.dev/api-reference/errors/code/INTERNAL_SERVER_ERROR message: type: string description: A human readable explanation of what went wrong requestId: type: string description: Please always include the requestId in your error report example: req_1234 details: type: object properties: kind: type: string enum: - invalid_config - slug_conflict - unresolved_reference description: >- What kind of failure this is. Currently only the monetization configuration operations set it example: invalid_config issues: type: array items: type: object properties: path: type: string description: JSON path into the submitted document example: config.plans[0].version.features[1].featureSlug message: type: string required: - path - message description: Per-location detail, when the failure has locations required: - kind required: - code - docs - message - requestId required: - error securitySchemes: bearerAuth: bearerFormat: root key type: http scheme: bearer x-speakeasy-example: UNPRICE_API_KEY ````