--- title: "Create a new billing profile" method: POST path: "/openmeter/profiles" tags: ["OpenMeter Billing Settings"] --- # Create a new billing profile `POST /openmeter/profiles` Create a new billing profile. Billing profiles contain the settings for billing and controls invoice generation. An organization can have multiple billing profiles defined. A billing profile is linked to a specific app. This association is established during the billing profile's creation and remains immutable. ## Request body - CreateBillingProfileRequest — BillingProfile create request. - `name` string, required — Display name of the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `labels` Labels — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `supplier` BillingParty, required — Party represents a person or business entity. - `id` string — Unique identifier for the party. - `key` string — ExternalResourceKey is a unique string that is used to identify a resource in an external system. - `name` string — Legal name or representation of the party. - `tax_id` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - `code` string — Tax identifier code is a normalized tax code shown on the original identity document. - `addresses` BillingPartyAddresses — A collection of addresses for the party. - `billing_address` Address, required — Address - `country` string — [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country code. Custom two-letter country codes are also supported for convenience. - `postal_code` string — Postal code. - `state` string — State or province. - `city` string — City. - `line1` string — First line of the address. - `line2` string — Second line of the address. - `phone_number` string — Phone number. - `workflow` BillingWorkflow, required — Billing workflow settings. - `collection` BillingWorkflowCollectionSettings — Workflow collection specifies how to collect the pending line items for an invoice. - `alignment` union — The alignment for collecting the pending line items into an invoice. Defaults to subscription, which means that we are to create a new invoice every time the a subscription period starts (for in advance items) or ends (for in arrears items). - object — BillingWorkflowCollectionAlignmentSubscription specifies the alignment for collecting the pending line items into an invoice. - `type` 'subscription', required — The type of alignment. - object — BillingWorkflowCollectionAlignmentAnchored specifies the alignment for collecting the pending line items into an invoice. - `type` 'anchored', required — The type of alignment. - `recurring_period` RecurringPeriod, required — Recurring period with an anchor and an interval. - `anchor` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `interval` string, ISO8601, required — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `interval` string, ISO8601 — This grace period can be used to delay the collection of the pending line items specified in alignment. This is useful, in case of multiple subscriptions having slightly different billing periods. - `invoicing` BillingWorkflowInvoicingSettings — Invoice settings for a billing workflow. - `auto_advance` boolean — Whether to automatically issue the invoice after the draftPeriod has passed. - `draft_period` string, ISO8601 — The period for the invoice to be kept in draft status for manual reviews. - `progressive_billing` boolean — Should progressive billing be allowed for this workflow? - `subscription_end_proration_mode` 'bill_full_period' | 'bill_actual_period' — Billing workflow subscription end proration mode. - `payment` union — Payment settings for a billing workflow. - object — Payment settings for a billing workflow when the collection method is charge automatically. - `collection_method` 'charge_automatically', required — The collection method for the invoice. - object — Payment settings for a billing workflow when the collection method is send invoice. - `collection_method` 'send_invoice', required — The collection method for the invoice. - `due_after` string, ISO8601 — The period after which the invoice is due. With some payment solutions it's only applicable for manual collection method. - `tax` BillingWorkflowTaxSettings — Tax settings for a billing workflow. - `enabled` boolean — Enable automatic tax calculation when tax is supported by the app. For example, with Stripe Invoicing when enabled, tax is calculated via Stripe Tax. - `enforced` boolean — Enforce tax calculation when tax is supported by the app. When enabled, the billing system will not allow to create an invoice without tax calculation. Enforcement is different per apps, for example, Stripe app requires customer to have a tax location when starting a paid subscription. - `default_tax_config` BillingTaxConfig — 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` BillingTaxConfigStripe — The tax config for Stripe. - `code` string, required — Product [tax code](https://docs.stripe.com/tax/tax-codes). - `external_invoicing` BillingTaxConfigExternalInvoicing — External invoicing tax config. - `code` string, required — The tax code should be interpreted by the external invoicing provider. - `tax_code_id` string — ULID (Universally Unique Lexicographically Sortable Identifier). - `tax_code` TaxCodeReference — TaxCode reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `apps` BillingProfileAppReferences, required — References to the applications used by a billing profile. - `tax` BillingAppReference, required — App reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `invoicing` BillingAppReference, required — App reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `payment` BillingAppReference, required — App reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `default` boolean, required — Whether this is the default profile. ## Response `201` BillingProfile created response. - BillingProfile — Billing profiles contain the settings for billing and controls invoice generation. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required — Display name of the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `labels` Labels — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `created_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `updated_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `supplier` BillingParty, required — Party represents a person or business entity. - `id` string — Unique identifier for the party. - `key` string — ExternalResourceKey is a unique string that is used to identify a resource in an external system. - `name` string — Legal name or representation of the party. - `tax_id` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - `code` string — Tax identifier code is a normalized tax code shown on the original identity document. - `addresses` BillingPartyAddresses — A collection of addresses for the party. - `billing_address` Address, required — Address - `country` string — [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country code. Custom two-letter country codes are also supported for convenience. - `postal_code` string — Postal code. - `state` string — State or province. - `city` string — City. - `line1` string — First line of the address. - `line2` string — Second line of the address. - `phone_number` string — Phone number. - `workflow` BillingWorkflow, required — Billing workflow settings. - `collection` BillingWorkflowCollectionSettings — Workflow collection specifies how to collect the pending line items for an invoice. - `alignment` union — The alignment for collecting the pending line items into an invoice. Defaults to subscription, which means that we are to create a new invoice every time the a subscription period starts (for in advance items) or ends (for in arrears items). - object — BillingWorkflowCollectionAlignmentSubscription specifies the alignment for collecting the pending line items into an invoice. - `type` 'subscription', required — The type of alignment. - object — BillingWorkflowCollectionAlignmentAnchored specifies the alignment for collecting the pending line items into an invoice. - `type` 'anchored', required — The type of alignment. - `recurring_period` RecurringPeriod, required — Recurring period with an anchor and an interval. - `anchor` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `interval` string, ISO8601, required — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `interval` string, ISO8601 — This grace period can be used to delay the collection of the pending line items specified in alignment. This is useful, in case of multiple subscriptions having slightly different billing periods. - `invoicing` BillingWorkflowInvoicingSettings — Invoice settings for a billing workflow. - `auto_advance` boolean — Whether to automatically issue the invoice after the draftPeriod has passed. - `draft_period` string, ISO8601 — The period for the invoice to be kept in draft status for manual reviews. - `progressive_billing` boolean — Should progressive billing be allowed for this workflow? - `subscription_end_proration_mode` 'bill_full_period' | 'bill_actual_period' — Billing workflow subscription end proration mode. - `payment` union — Payment settings for a billing workflow. - object — Payment settings for a billing workflow when the collection method is charge automatically. - `collection_method` 'charge_automatically', required — The collection method for the invoice. - object — Payment settings for a billing workflow when the collection method is send invoice. - `collection_method` 'send_invoice', required — The collection method for the invoice. - `due_after` string, ISO8601 — The period after which the invoice is due. With some payment solutions it's only applicable for manual collection method. - `tax` BillingWorkflowTaxSettings — Tax settings for a billing workflow. - `enabled` boolean — Enable automatic tax calculation when tax is supported by the app. For example, with Stripe Invoicing when enabled, tax is calculated via Stripe Tax. - `enforced` boolean — Enforce tax calculation when tax is supported by the app. When enabled, the billing system will not allow to create an invoice without tax calculation. Enforcement is different per apps, for example, Stripe app requires customer to have a tax location when starting a paid subscription. - `default_tax_config` BillingTaxConfig — 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` BillingTaxConfigStripe — The tax config for Stripe. - `code` string, required — Product [tax code](https://docs.stripe.com/tax/tax-codes). - `external_invoicing` BillingTaxConfigExternalInvoicing — External invoicing tax config. - `code` string, required — The tax code should be interpreted by the external invoicing provider. - `tax_code_id` string — ULID (Universally Unique Lexicographically Sortable Identifier). - `tax_code` TaxCodeReference — TaxCode reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `apps` BillingProfileAppReferences, required — References to the applications used by a billing profile. - `tax` BillingAppReference, required — App reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `invoicing` BillingAppReference, required — App reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `payment` BillingAppReference, required — App reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `default` boolean, required — Whether this is the default profile. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden --- [API](https://skmtc.net/openmeterio/apis/openmeter-and-konnect-metering-billing-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-and-konnect-metering-billing-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-and-konnect-metering-billing-api/versions/9bca44e2d61d/schema)