--- title: "Create a new or update a customer override" method: PUT path: "/api/v1/billing/customers/{customerId}" tags: ["Billing"] --- # Create a new or update a customer override `PUT /api/v1/billing/customers/{customerId}` The customer override can be used to pin a given customer to a billing profile different from the default one. This can be used to test the effect of different billing profiles before making them the default ones or have different workflow settings for example for enterprise customers. ## Path parameters - `customerId` string, required ## Request body - BillingProfileCustomerOverrideCreate — Payload for creating a new or updating an existing customer override. - `billingProfileId` string — The billing profile this override is associated with. If not provided, the default billing profile is chosen if available. ## Response `200` The request has succeeded. - BillingProfileCustomerOverrideWithDetails — Customer specific workflow overrides. - `customerOverride` BillingProfileCustomerOverride — Customer override values. - `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. - `billingProfileId` string — The billing profile this override is associated with. If empty the default profile is looked up dynamically. - `customerId` string, required — The customer id this override is associated with. - `baseBillingProfileId` string, required — The billing profile the customerProfile is associated with at the time of query. customerOverride contains the explicit mapping set in the customer override object. If that is empty, then the baseBillingProfileId is the default profile. - `customerProfile` BillingCustomerProfile — Customer specific merged profile. This profile is calculated from the customer override and the billing profile it references or the default. Thus this does not have any kind of resource fields, only the calculated values. - `supplier` BillingParty, required — Party represents a person or business entity. - `id` string — Unique identifier for the party (if available) - `key` string — An optional unique key of the party (if available) - `name` string — Legal name or representation of the organization. - `taxId` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - `code` string — TaxIdentificationCode is a normalized tax code shown on the original identity document. - `addresses` Address[] — Regular post addresses for where information should be sent if needed. - `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. - `postalCode` 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. - `phoneNumber` string — Phone number. - `workflow` BillingWorkflow, required — BillingWorkflow represents the settings for a billing workflow. - `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. - `recurringPeriod` RecurringPeriodV2, required — Recurring period with an interval and an anchor. - … - `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 — BillingWorkflowInvoicingSettings represents the invoice settings for a billing workflow - `autoAdvance` boolean — Whether to automatically issue the invoice after the draftPeriod has passed. - `draftPeriod` string, ISO8601 — The period for the invoice to be kept in draft status for manual reviews. - `dueAfter` string, ISO8601 — The period after which the invoice is due. With some payment solutions it's only applicable for manual collection method. - `progressiveBilling` boolean — Should progressive billing be allowed for this workflow? - `subscriptionEndProrationMode` 'bill_full_period' | 'bill_actual_period' — Billing workflow subscription end proration mode. - `defaultTaxConfig` 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. - `payment` BillingWorkflowPaymentSettings — BillingWorkflowPaymentSettings represents the payment settings for a billing workflow - `collectionMethod` 'charge_automatically' | 'send_invoice' — CollectionMethod specifies how the invoice should be collected (automatic vs manual) - `tax` BillingWorkflowTaxSettings — BillingWorkflowTaxSettings represents the 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, OpenMeter 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. - `apps` union, required — ProfileAppsOrReference represents the union of ProfileApps and ProfileAppReferences for a billing profile. - BillingProfileApps — BillingProfileApps represents the applications used by a billing profile - `tax` union, required — App. One of: stripe - object — A installed Stripe app object. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'stripe', required — The app's type is Stripe. - `stripeAccountId` string, required — The Stripe account ID. - `livemode` boolean, required — Livemode, true if the app is in production mode. - `maskedAPIKey` string, required — The masked API key. Only shows the first 8 and last 3 characters. - object — Sandbox app can be used for testing OpenMeter features. The app is not creating anything in external systems, thus it is safe to use for verifying OpenMeter features. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'sandbox', required — The app's type is Sandbox. - object — Custom Invoicing app can be used for interface with any invoicing or payment system. This app provides ways to manipulate invoices and payments, however the integration must rely on Notifications API to get notified about invoice changes. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'custom_invoicing', required — The app's type is CustomInvoicing. - `enableDraftSyncHook` boolean, required — Enable draft.sync hook. If the hook is not enabled, the invoice will be progressed to the next state automatically. - `enableIssuingSyncHook` boolean, required — Enable issuing.sync hook. If the hook is not enabled, the invoice will be progressed to the next state automatically. - `invoicing` union, required — App. One of: stripe - object — A installed Stripe app object. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'stripe', required — The app's type is Stripe. - `stripeAccountId` string, required — The Stripe account ID. - `livemode` boolean, required — Livemode, true if the app is in production mode. - `maskedAPIKey` string, required — The masked API key. Only shows the first 8 and last 3 characters. - object — Sandbox app can be used for testing OpenMeter features. The app is not creating anything in external systems, thus it is safe to use for verifying OpenMeter features. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'sandbox', required — The app's type is Sandbox. - object — Custom Invoicing app can be used for interface with any invoicing or payment system. This app provides ways to manipulate invoices and payments, however the integration must rely on Notifications API to get notified about invoice changes. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'custom_invoicing', required — The app's type is CustomInvoicing. - `enableDraftSyncHook` boolean, required — Enable draft.sync hook. If the hook is not enabled, the invoice will be progressed to the next state automatically. - `enableIssuingSyncHook` boolean, required — Enable issuing.sync hook. If the hook is not enabled, the invoice will be progressed to the next state automatically. - `payment` union, required — App. One of: stripe - object — A installed Stripe app object. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'stripe', required — The app's type is Stripe. - `stripeAccountId` string, required — The Stripe account ID. - `livemode` boolean, required — Livemode, true if the app is in production mode. - `maskedAPIKey` string, required — The masked API key. Only shows the first 8 and last 3 characters. - object — Sandbox app can be used for testing OpenMeter features. The app is not creating anything in external systems, thus it is safe to use for verifying OpenMeter features. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'sandbox', required — The app's type is Sandbox. - object — Custom Invoicing app can be used for interface with any invoicing or payment system. This app provides ways to manipulate invoices and payments, however the integration must rely on Notifications API to get notified about invoice changes. - `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. - `listing` MarketplaceListing, required — A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model. - … - `status` 'ready' | 'unauthorized', required — App installed status. - `type` 'custom_invoicing', required — The app's type is CustomInvoicing. - `enableDraftSyncHook` boolean, required — Enable draft.sync hook. If the hook is not enabled, the invoice will be progressed to the next state automatically. - `enableIssuingSyncHook` boolean, required — Enable issuing.sync hook. If the hook is not enabled, the invoice will be progressed to the next state automatically. - BillingProfileAppReferences — BillingProfileAppReferences represents the references (id, type) to the apps used by a billing profile - `tax` AppReference, required — App reference Can be used as a short reference to an app if the full app object is not needed. - `id` string, required — The ID of the app. - `invoicing` AppReference, required — App reference Can be used as a short reference to an app if the full app object is not needed. - `id` string, required — The ID of the app. - `payment` AppReference, required — App reference Can be used as a short reference to an app if the full app object is not needed. - `id` string, required — The ID of the app. - `customer` Customer — A customer object. - `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 — An optional unique key of the customer. Either key or usageAttribution.subjectKeys must be provided. Useful to reference the customer in external systems. For example, your database ID. - `usageAttribution` CustomerUsageAttribution — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer. - `subjectKeys` string[], required — The subjects that are attributed to the customer. Can be empty when no subjects are associated with the customer. - `primaryEmail` string — The primary email address of the customer. - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `billingAddress` Address — 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. - `postalCode` 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. - `phoneNumber` string — Phone number. - `currentSubscriptionId` string — The ID of the Subscription if the customer has one. - `subscriptions` Subscription[] — The subscriptions of the customer. Only with the `subscriptions` expand option. - `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. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `alignment` Alignment — Alignment configuration for a plan or subscription. - `billablesMustAlign` boolean — Whether all Billable items and RateCards must align. Alignment means the Price's BillingCadence must align for both duration and anchor time. - `status` 'active' | 'inactive' | 'canceled' | 'scheduled', required — Subscription status. - `customerId` string, required — The customer ID of the subscription. - `plan` PlanReference — References an exact plan. - `id` string, required — The plan ID. - `key` string, required — The plan key. - `version` integer, required — The plan version. - `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. - `billingCadence` string, duration, required — The billing cadence for the subscriptions. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually). - `proRatingConfig` ProRatingConfig — Configuration for pro-rating behavior. - `enabled` boolean, required — Whether pro-rating is enabled for this plan. - `mode` 'prorate_prices', required — Pro-rating mode options for handling billing period changes. - `billingAnchor` string, date-time, required — The normalizedbilling anchor of the subscription. - `settlementMode` 'credit_then_invoice' | 'credit_only', required — The settlement mode of a plan. It determines how the billing system generates invoices and credits for the subscriptions using this plan. - credit_then_invoice: credits from the previous billing period are applied first, then the remaining balance is invoiced. This is the default and most common settlement mode. - credit_only: only credits from the previous billing period are generated and applied. No invoices are generated for the subscription. - `annotations` 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)