openapi: 3.0.1 info: title: Metronome Alerts Products API version: 1.0.0 description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)' servers: - url: https://api.metronome.com description: Production server security: - bearerAuth: [] tags: - name: Products description: Products are the items that customers purchase. paths: /v1/contract-pricing/products/get: post: description: 'Retrieve a product by its ID, including all metadata and historical changes. ' operationId: getProduct-v1 summary: Get a product tags: - Products requestBody: description: The ID of the product to get content: application/json: schema: $ref: '#/components/schemas/Id' example: id: d84e7f4e-7a70-4fe4-be02-7a5027beffcc responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ProductListItem' example: data: id: 9c9a4a71-171e-41f9-b8da-d982baf1a388 type: COMPOSITE initial: name: My Composite Product starting_at: '2020-01-01T00:00:00.000Z' composite_product_ids: - e5e40bc7-ef69-42ec-a77e-cd696f6bfa3d created_at: '2019-12-30T04:24:55.123Z' created_by: Bob current: name: My Updated Composite Product Name starting_at: '2020-01-01T00:00:00.000Z' composite_product_ids: - e5e40bc7-ef69-42ec-a77e-cd696f6bfa3d created_at: '2019-12-30T04:24:55.123Z' created_by: Bob updates: - name: My Updated Composite Product Name starting_at: '2020-02-01T00:00:00.000Z' created_at: '2019-12-30T09:24:55.123Z' created_by: Alice custom_fields: x_account_id: KyVnHhSBWl7eY2bl '404': $ref: '#/components/responses/NotFound' /v1/contract-pricing/products/list: post: description: 'Get a paginated list of all products in your organization with their complete configuration, version history, and metadata. By default excludes archived products unless explicitly requested via the `archive_filter` parameter. ' operationId: listProducts-v1 summary: List products parameters: - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/NextPage' tags: - Products requestBody: description: Get list of products content: application/json: schema: $ref: '#/components/schemas/ListProductsPayload' example: archive_filter: NOT_ARCHIVED responses: '200': description: Success content: application/json: schema: type: object required: - data - next_page properties: data: type: array items: $ref: '#/components/schemas/ProductListItem' next_page: type: string nullable: true example: data: - id: 9c9a4a71-171e-41f9-b8da-d982baf1a388 type: COMPOSITE archived_at: null initial: name: My Composite Product starting_at: '2020-01-01T00:00:00.000Z' composite_product_ids: - e5e40bc7-ef69-42ec-a77e-cd696f6bfa3d created_at: '2019-12-30T04:24:55.123Z' created_by: Bob current: name: My Updated Composite Product Name starting_at: '2020-01-01T00:00:00.000Z' composite_product_ids: - e5e40bc7-ef69-42ec-a77e-cd696f6bfa3d created_at: '2019-12-30T04:24:55.123Z' created_by: Bob updates: - name: My Updated Composite Product Name starting_at: '2020-02-01T00:00:00.000Z' created_at: '2019-12-30T09:24:55.123Z' created_by: Alice custom_fields: x_account_id: KyVnHhSBWl7eY2bl next_page: null /v1/contract-pricing/products/create: post: description: 'Create a new product object. Products in Metronome represent your company''s individual product or service offerings. A Product can be thought of as the basic unit of a line item on the invoice. This is analogous to SKUs or items in an ERP system. Give the product a meaningful name as they will appear on customer invoices. ' operationId: createProduct-v1 summary: Create a product tags: - Products requestBody: description: Create a new product content: application/json: schema: $ref: '#/components/schemas/CreateProductListItemPayload' example: name: My Product type: USAGE billable_metric_id: 13117714-3f05-48e5-a6e9-a66093f13b4d responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' /v1/contract-pricing/products/update: post: description: "Updates a product's configuration while maintaining billing continuity for active customers. Use this endpoint to modify product names, metrics, pricing rules, and composite settings without disrupting ongoing billing cycles. Changes are scheduled using the starting_at timestamp, which must be on an hour boundary—set future dates to schedule updates ahead of time, or past dates for retroactive changes. Returns the updated product ID upon success. \n\n### Usage guidance: \n- Product type cannot be changed after creation. For incorrect product types, create a new product and archive the original instead.\n" operationId: updateProduct-v1 summary: Update a product tags: - Products requestBody: description: "Updates a product's configuration while maintaining billing continuity for active customers. Use this endpoint to modify product names, metrics, pricing rules, and composite settings without disrupting ongoing billing cycles. Changes are scheduled using the starting_at timestamp, which must be on an hour boundary–set future dates to schedule updates ahead of time, or past dates for retroactive changes. Returns the updated product ID upon success. \n\nUsage guidance: \nProduct type cannot be changed after creation. For incorrect product types, create a new product and archive the original instead.\n" content: application/json: schema: $ref: '#/components/schemas/UpdateProductListItemPayload' example: product_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc name: My Updated Product starting_at: '2020-01-01T00:00:00.000Z' responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' /v1/contract-pricing/products/archive: post: description: 'Archive a product. Any current rate cards associated with this product will continue to function as normal. However, it will no longer be available as an option for newly created rates. Once you archive a product, you can still retrieve it in the UI and API, but you cannot unarchive it. ' operationId: archiveProductListItem-v1 summary: Archive a product tags: - Products requestBody: description: Archive a product content: application/json: schema: $ref: '#/components/schemas/ArchiveProductListItemPayload' example: product_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' components: schemas: CreateProductListItemPayload: type: object required: - name - type properties: name: type: string description: displayed on invoices type: type: string enum: - FIXED - fixed - USAGE - usage - COMPOSITE - composite - SUBSCRIPTION - subscription - PROFESSIONAL_SERVICE - professional_service - PRO_SERVICE - pro_service x-mint-enum: PROFESSIONAL_SERVICE: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 professional_service: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 PRO_SERVICE: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 pro_service: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 netsuite_internal_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. netsuite_overage_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. billable_metric_id: type: string format: uuid description: Required for USAGE products composite_product_ids: type: array items: type: string format: uuid description: Required for COMPOSITE products composite_tags: type: array items: type: string description: Required for COMPOSITE products is_refundable: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: boolean description: This field's availability is dependent on your client's configuration. Defaults to true. composite_scope: type: string enum: - customer - CUSTOMER - contract - CONTRACT description: Determines what spend contributes to calculating this charge. When composite scope is contract, calculates composite charge based on applicable spend per contract. When composite scope is customer, calculates composite charge based on applicable spend across all customer contracts. Defaults to contract. x-mint: groups: - ff:composite-support-charge-m1-enabled x-stainless-skip: true exclude_free_usage: type: boolean description: Beta feature only available for composite products. If true, products with $0 will not be included when computing composite usage. Defaults to false tags: type: array items: type: string pricing_group_key: $ref: '#/components/schemas/PricingGroupKey' presentation_group_key: $ref: '#/components/schemas/PresentationGroupKey' quantity_conversion: $ref: '#/components/schemas/QuantityConversion' quantity_rounding: $ref: '#/components/schemas/QuantityRounding' custom_fields: $ref: '#/components/schemas/CustomField' ArchiveProductListItemPayload: type: object required: - product_id properties: product_id: type: string format: uuid description: ID of the product to be archived UpdateProductListItemPayload: type: object required: - product_id - starting_at properties: product_id: type: string format: uuid description: ID of the product to update name: type: string description: displayed on invoices. If not provided, defaults to product's current name. starting_at: type: string format: date-time description: Timestamp representing when the update should go into effect. It must be on an hour boundary (e.g. 1:00, not 1:30). is_refundable: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: boolean description: Defaults to product's current refundability status. This field's availability is dependent on your client's configuration. exclude_free_usage: type: boolean description: Beta feature only available for composite products. If true, products with $0 will not be included when computing composite usage. Defaults to false billable_metric_id: type: string format: uuid description: Available for USAGE products only. If not provided, defaults to product's current billable metric. netsuite_internal_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: If not provided, defaults to product's current netsuite_internal_item_id. This field's availability is dependent on your client's configuration. netsuite_overage_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: Available for USAGE and COMPOSITE products only. If not provided, defaults to product's current netsuite_overage_item_id. This field's availability is dependent on your client's configuration. composite_product_ids: type: array items: type: string format: uuid description: Available for COMPOSITE products only. If not provided, defaults to product's current composite_product_ids. quantity_conversion: $ref: '#/components/schemas/QuantityConversion' quantity_rounding: $ref: '#/components/schemas/QuantityRounding' tags: type: array items: type: string description: If not provided, defaults to product's current tags composite_tags: type: array items: type: string description: Available for COMPOSITE products only. If not provided, defaults to product's current composite_tags. pricing_group_key: $ref: '#/components/schemas/PricingGroupKey' presentation_group_key: $ref: '#/components/schemas/PresentationGroupKey' Error: required: - message type: object properties: message: type: string ProductListItem: type: object required: - id - type - initial - current - updates properties: id: type: string format: uuid type: type: string enum: - USAGE - SUBSCRIPTION - COMPOSITE - FIXED - PRO_SERVICE archived_at: type: string format: date-time nullable: true initial: $ref: '#/components/schemas/ProductListItemState' current: $ref: '#/components/schemas/ProductListItemState' updates: type: array items: $ref: '#/components/schemas/ProductListItemUpdate' custom_fields: x-cf-entity: contract_product $ref: '#/components/schemas/CustomField' PricingGroupKey: type: array items: type: string description: For USAGE products only. If set, pricing for this product will be determined for each pricing_group_key value, as opposed to the product as a whole. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric. Id: required: - id type: object properties: id: type: string format: uuid PresentationGroupKey: type: array items: type: string description: For USAGE products only. Groups usage line items on invoices. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric. QuantityConversion: type: object nullable: true description: Optional. Only valid for USAGE products. If provided, the quantity will be converted using the provided conversion factor and operation. For example, if the operation is "multiply" and the conversion factor is 100, then the quantity will be multiplied by 100. This can be used in cases where data is sent in one unit and priced in another. For example, data could be sent in MB and priced in GB. In this case, the conversion factor would be 1024 and the operation would be "divide". required: - conversion_factor - operation properties: name: type: string description: Optional name for this conversion. conversion_factor: type: number description: The factor to multiply or divide the quantity by. operation: type: string enum: - multiply - divide - MULTIPLY - DIVIDE description: The operation to perform on the quantity ProductListItemUpdate: type: object required: - created_at - created_by properties: name: type: string starting_at: type: string format: date-time is_refundable: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: boolean created_at: type: string format: date-time created_by: type: string billable_metric_id: type: string format: uuid quantity_conversion: $ref: '#/components/schemas/QuantityConversion' quantity_rounding: $ref: '#/components/schemas/QuantityRounding' netsuite_internal_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. netsuite_overage_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. composite_product_ids: type: array items: type: string format: uuid composite_tags: type: array items: type: string tags: type: array items: type: string exclude_free_usage: type: boolean pricing_group_key: $ref: '#/components/schemas/PricingGroupKey' presentation_group_key: $ref: '#/components/schemas/PresentationGroupKey' ProductListItemState: type: object required: - name - created_at - created_by properties: name: type: string starting_at: type: string format: date-time netsuite_internal_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. created_at: type: string format: date-time created_by: type: string netsuite_overage_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. billable_metric_id: type: string composite_product_ids: type: array items: type: string format: uuid quantity_conversion: $ref: '#/components/schemas/QuantityConversion' quantity_rounding: $ref: '#/components/schemas/QuantityRounding' composite_tags: type: array items: type: string is_refundable: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: boolean description: This field's availability is dependent on your client's configuration. tags: type: array items: type: string composite_scope: type: string enum: - CUSTOMER - CONTRACT x-mint: groups: - ff:composite-support-charge-m1-enabled x-stainless-skip: true description: Determines what spend contributes to calculating this charge. exclude_free_usage: type: boolean pricing_group_key: $ref: '#/components/schemas/PricingGroupKey' presentation_group_key: $ref: '#/components/schemas/PresentationGroupKey' ListProductsPayload: type: object properties: archive_filter: type: string enum: - ARCHIVED - NOT_ARCHIVED - ALL description: Filter options for the product list. If not provided, defaults to not archived. CustomField: type: object description: 'Custom fields to be added eg. { "key1": "value1", "key2": "value2" }' additionalProperties: type: string QuantityRounding: type: object nullable: true description: Optional. Only valid for USAGE products. If provided, the quantity will be rounded using the provided rounding method and decimal places. For example, if the method is "round up" and the decimal places is 0, then the quantity will be rounded up to the nearest integer. required: - rounding_method - decimal_places properties: rounding_method: type: string enum: - round_up - round_down - round_half_up - ROUND_UP - ROUND_DOWN - ROUND_HALF_UP decimal_places: type: number minimum: 0 parameters: PageLimit: name: limit in: query description: Max number of results that should be returned required: false schema: type: integer minimum: 1 maximum: 100 NextPage: name: next_page in: query description: Cursor that indicates where the next page of results should start. required: false schema: type: string responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer