---
title: "Publish add-on"
method: POST
path: "/api/v1/addons/{addonId}/publish"
tags: ["Product Catalog"]
---

# Publish add-on

`POST /api/v1/addons/{addonId}/publish`

Publish a add-on version.

## Path parameters

- `addonId` string, required

## Response `200`

The request has succeeded.

- Addon — Add-on allows extending subscriptions with compatible plans with additional ratecards.
  - `id` string, required — A unique identifier for the resource.
  - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters.
  - `description` string — Optional description of the resource. Maximum 1024 characters.
  - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
  - `createdAt` string, date-time, required — Timestamp of when the resource was created.
  - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated.
  - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted.
  - `key` string, required — A semi-unique identifier for the resource.
  - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user.
  - `version` integer, required — Version of the add-on. Incremented when the add-on is updated.
  - `instanceType` 'single' | 'multiple', required — The instanceType of the add-on. Single instance add-ons can be added to subscription only once while add-ons with multiple type can be added more then once.
  - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.
  - `effectiveFrom` string, date-time — The date and time when the add-on becomes effective. When not specified, the add-on is a draft.
  - `effectiveTo` string, date-time — The date and time when the add-on is no longer effective. When not specified, the add-on is effective indefinitely.
  - `status` 'draft' | 'active' | 'archived', required — The status of the add-on defined by the effectiveFrom and effectiveTo properties.
  - `rateCards` RateCard[], required — The rate cards of the add-on.
    - union — A rate card defines the pricing and entitlement of a feature or service.
      - object — A flat fee rate card defines a one-time purchase or a recurring fee.
        - `type` 'flat_fee', required — The type of the RateCard.
        - `key` string, required — A semi-unique identifier for the resource.
        - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters.
        - `description` string — Optional description of the resource. Maximum 1024 characters.
        - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
        - `featureKey` string — The feature the customer is entitled to use.
        - `entitlementTemplate` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card.
          - object — The entitlement template with a metered entitlement.
            - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
            - `type` 'metered', required
            - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.
            - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.
            - `issueAfterResetPriority` integer — Defines the grant priority for the default grant.
            - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0.
            - `usagePeriod` string, duration — The interval of the metered entitlement. Defaults to the billing cadence of the rate card.
          - object — Entitlement template of a static entitlement.
            - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
            - `type` 'static', required
            - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object.
          - object — Entitlement template of a boolean entitlement.
            - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
            - `type` 'boolean', required
        - `taxConfig` TaxConfig — Set of provider specific tax configs.
          - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price.
          - `stripe` StripeTaxConfig — The tax config for Stripe.
            - `code` string, required — Product tax code. See: https://docs.stripe.com/tax/tax-codes
          - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config.
            - `code` string, required — Tax code. The tax code should be interpreted by the custom invoicing provider.
          - `taxCodeId` string — Tax code reference. When both `taxCodeId` and `stripe.code` are provided, `taxCodeId` takes precedence: the referenced tax code entity is used and `stripe.code` is ignored.
        - `billingCadence` string, duration, nullable, required — The billing cadence of the rate card. When null it means it is a one time fee.
        - `price` FlatPriceWithPaymentTerm, required — Flat price with payment term.
          - `type` 'flat', required — The type of the price.
          - `amount` string, required — Numeric represents an arbitrary precision number.
          - `paymentTerm` 'in_advance' | 'in_arrears' — The payment term of a flat price. One of: in_advance or in_arrears.
        - `discounts` Discounts — Discount by type on a price
          - `percentage` DiscountPercentage — Percentage discount.
            - `percentage` number, double, required — Numeric representation of a percentage 50% is represented as 50
          - `usage` DiscountUsage — Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted.
            - `quantity` string, required — Numeric represents an arbitrary precision number.
      - object — A usage-based rate card defines a price based on usage.
        - `type` 'usage_based', required — The type of the RateCard.
        - `key` string, required — A semi-unique identifier for the resource.
        - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters.
        - `description` string — Optional description of the resource. Maximum 1024 characters.
        - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
        - `featureKey` string — The feature the customer is entitled to use.
        - `entitlementTemplate` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card.
          - object — The entitlement template with a metered entitlement.
            - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
            - `type` 'metered', required
            - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.
            - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.
            - `issueAfterResetPriority` integer — Defines the grant priority for the default grant.
            - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0.
            - `usagePeriod` string, duration — The interval of the metered entitlement. Defaults to the billing cadence of the rate card.
          - object — Entitlement template of a static entitlement.
            - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
            - `type` 'static', required
            - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object.
          - object — Entitlement template of a boolean entitlement.
            - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
            - `type` 'boolean', required
        - `taxConfig` TaxConfig — Set of provider specific tax configs.
          - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price.
          - `stripe` StripeTaxConfig — The tax config for Stripe.
            - `code` string, required — Product tax code. See: https://docs.stripe.com/tax/tax-codes
          - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config.
            - `code` string, required — Tax code. The tax code should be interpreted by the custom invoicing provider.
          - `taxCodeId` string — Tax code reference. When both `taxCodeId` and `stripe.code` are provided, `taxCodeId` takes precedence: the referenced tax code entity is used and `stripe.code` is ignored.
        - `billingCadence` string, duration, required — The billing cadence of the rate card.
        - `price` union, required — The price of the usage based rate card.
          - object — Flat price with payment term.
            - `type` 'flat', required — The type of the price.
            - `amount` string, required — Numeric represents an arbitrary precision number.
            - `paymentTerm` 'in_advance' | 'in_arrears' — The payment term of a flat price. One of: in_advance or in_arrears.
          - object — Unit price with spend commitments.
            - `type` 'unit', required — The type of the price.
            - `amount` string, required — Numeric represents an arbitrary precision number.
            - `minimumAmount` string — Numeric represents an arbitrary precision number.
            - `maximumAmount` string — Numeric represents an arbitrary precision number.
          - object — Tiered price with spend commitments.
            - `type` 'tiered', required — The type of the price. One of: flat, unit, or tiered.
            - `mode` 'volume' | 'graduated', required — The mode of the tiered price.
            - `tiers` PriceTier[], required — The tiers of the tiered price. At least one price component is required in each tier.
              - …
            - `minimumAmount` string — Numeric represents an arbitrary precision number.
            - `maximumAmount` string — Numeric represents an arbitrary precision number.
          - object — Dynamic price with spend commitments.
            - `type` 'dynamic', required — The type of the price.
            - `multiplier` string — Numeric represents an arbitrary precision number.
            - `minimumAmount` string — Numeric represents an arbitrary precision number.
            - `maximumAmount` string — Numeric represents an arbitrary precision number.
          - object — Package price with spend commitments.
            - `type` 'package', required — The type of the price.
            - `amount` string, required — Numeric represents an arbitrary precision number.
            - `quantityPerPackage` string, required — Numeric represents an arbitrary precision number.
            - `minimumAmount` string — Numeric represents an arbitrary precision number.
            - `maximumAmount` string — Numeric represents an arbitrary precision number.
        - `discounts` Discounts — Discount by type on a price
          - `percentage` DiscountPercentage — Percentage discount.
            - `percentage` number, double, required — Numeric representation of a percentage 50% is represented as 50
          - `usage` DiscountUsage — Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted.
            - `quantity` string, required — Numeric represents an arbitrary precision number.
  - `validationErrors` ValidationError[], nullable, required — List of validation errors.
    - `field` string, required — The path to the field.
    - `code` string, required — The machine readable description of the error.
    - `message` string, required — The human readable description of the error.
    - `attributes` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user.

## Other responses

- `400` — 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).
- `401` — The request has not been applied because it lacks valid authentication credentials for the target resource.
- `403` — The server understood the request but refuses to authorize it.
- `404` — The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
- `412` — One or more conditions given in the request header fields evaluated to false when tested on the server.
- `500` — The server encountered an unexpected condition that prevented it from fulfilling the request.
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
- `default` — An unexpected error response.

---

[API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/versions/927d82ffe647/schema)