--- title: "List customer overrides" method: GET path: "/api/v1/billing/customers" tags: ["Billing"] --- # List customer overrides `GET /api/v1/billing/customers` List customer overrides using the specified filters. The response will include the customer override values and the merged billing profile values. If the includeAllCustomers is set to true, the list contains all customers. This mode is useful for getting the current effective billing workflow settings for all users regardless if they have customer orverrides or not. ## Query parameters - `billingProfile` string[] - `customersWithoutPinnedProfile` boolean - `includeAllCustomers` boolean - `customerId` string[] - `customerName` string - `customerKey` string - `customerPrimaryEmail` string - `expand` BillingProfileCustomerOverrideExpand[] - `order` 'ASC' | 'DESC' — The order direction. - `orderBy` 'customerId' | 'customerName' | 'customerKey' | 'customerPrimaryEmail' | 'customerCreatedAt' — Order by options for customers. - `page` integer - `pageSize` integer ## Response `200` The request has succeeded. - BillingProfileCustomerOverrideWithDetailsPaginatedResponse — Paginated response - `totalCount` integer, required — The total number of items. - `page` integer, required — The page index. - `pageSize` integer, required — The maximum number of items per page. - `items` BillingProfileCustomerOverrideWithDetails[], required — The items in the current page. - `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. - … - object — BillingWorkflowCollectionAlignmentAnchored specifies the alignment for collecting the pending line items into an invoice. - … - `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. - … - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config. - … - `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. - … - 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. - … - 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. - … - `invoicing` union, required — App. One of: stripe - object — A installed Stripe app object. - … - 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. - … - 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. - … - `payment` union, required — App. One of: stripe - object — A installed Stripe app object. - … - 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. - … - 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. - … - 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. - `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)