Metronome Named schedules API

openapi: 3.0.1
info:
  title: Metronome Alerts Named schedules 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: Named schedules
  description: Named schedules are used for storing custom data that can change over time. Named schedules are often used in custom pricing logic.
paths:
  /v1/customers/getNamedSchedule:
    post:
      x-mint:
        groups:
        - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
        - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
        - client_id:f157d376-0781-4ef3-9db9-775a9052148e
        - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
        - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
        - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
      description: Get a named schedule for the given customer. This endpoint's availability is dependent on your client's configuration.
      operationId: getCustomerNamedSchedule-v1
      summary: Get a customer's named schedule
      tags:
      - Named schedules
      requestBody:
        description: Which customer, schedule name, and date to retrieve.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCustomerNamedSchedulePayload'
            example:
              customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
              schedule_name: my-schedule
              covering_date: '2022-02-15T00:00:00Z'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedSchedule'
              example:
                data:
                - starting_at: '2022-02-01T00:00:00Z'
                  ending_before: '2022-03-01T00:00:00Z'
                  value: my-value
  /v1/customers/updateNamedSchedule:
    post:
      x-mint:
        groups:
        - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
        - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
        - client_id:f157d376-0781-4ef3-9db9-775a9052148e
        - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
        - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
        - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
      description: Update a named schedule for the given customer. This endpoint's availability is dependent on your client's configuration.
      operationId: updateCustomerNamedSchedule-v1
      summary: Update a customer's named schedule
      tags:
      - Named schedules
      requestBody:
        description: The customer, schedule name, date range, and value to set.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerNamedSchedulePayload'
            example:
              customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
              schedule_name: my-schedule
              starting_at: '2022-02-01T00:00:00Z'
              ending_before: '2022-02-15T00:00:00Z'
              value:
                my_key: my_value
      responses:
        '200':
          description: Success
  /v1/contracts/getNamedSchedule:
    post:
      x-mint:
        groups:
        - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
        - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
        - client_id:f157d376-0781-4ef3-9db9-775a9052148e
        - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
        - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
        - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
      description: Get a named schedule for the given contract. This endpoint's availability is dependent on your client's configuration.
      operationId: getContractNamedSchedule-v1
      summary: Get a contract's named schedule
      tags:
      - Named schedules
      requestBody:
        description: Which customer, contract, schedule name, and date to retrieve.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetContractNamedSchedulePayload'
            example:
              customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
              contract_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
              schedule_name: my-schedule
              covering_date: '2022-02-15T00:00:00Z'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedSchedule'
              example:
                data:
                - starting_at: '2022-02-01T00:00:00Z'
                  ending_before: '2022-03-01T00:00:00Z'
                  value: my-value
  /v1/contracts/listNamedSchedules:
    post:
      x-mint:
        groups:
        - ff:fancy-schedules-enabled
      x-stainless-skip: true
      description: List contract-level named schedules for a customer, optionally scoped to a single contract.
      operationId: listContractsNamedSchedules-v1
      summary: List contract named schedules
      tags:
      - Named schedules
      requestBody:
        description: Specify which customer and optional filters to use when listing contract named schedules.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListContractsNamedSchedulesPayload'
            example:
              customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
              schedule_name: reserved-instance
              properties:
                sku: A100
              covering_date: '2026-01-15T00:00:00Z'
              limit: 10
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContractsNamedSchedulesPage'
              example:
                data:
                - contract_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
                  schedule_name: reserved-instance
                  properties:
                    sku: A100
                  segments:
                  - starting_at: '2026-01-01T00:00:00Z'
                    ending_before: '2026-07-01T00:00:00Z'
                    value: 50
                  - starting_at: '2026-07-01T00:00:00Z'
                    value: 80
                - contract_id: 74d99eeb-b8c3-4f13-a7ef-fcf5f01686d6
                  schedule_name: reserved-instance
                  properties:
                    sku: A100
                  segments:
                  - starting_at: '2026-06-01T00:00:00Z'
                    value: 30
                next_page: null
  /v1/contracts/updateNamedSchedule:
    post:
      x-mint:
        groups:
        - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
        - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
        - client_id:f157d376-0781-4ef3-9db9-775a9052148e
        - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
        - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
        - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
      description: Update a named schedule for the given contract. This endpoint's availability is dependent on your client's configuration.
      operationId: updateContractNamedSchedule-v1
      summary: Update a contract's named schedule
      tags:
      - Named schedules
      requestBody:
        description: The customer, contract, schedule name, date range, and value to set.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContractNamedSchedulePayload'
            example:
              customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
              contract_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
              schedule_name: my-schedule
              starting_at: '2022-02-01T00:00:00Z'
              ending_before: '2022-02-15T00:00:00Z'
              value:
                my_key: my_value
      responses:
        '200':
          description: Success
  /v1/contract-pricing/rate-cards/getNamedSchedule:
    post:
      x-mint:
        groups:
        - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
        - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
        - client_id:f157d376-0781-4ef3-9db9-775a9052148e
        - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
        - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
        - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
      description: Get a named schedule for the given rate card. This endpoint's availability is dependent on your client's configuration.
      operationId: getRateCardNamedSchedule-v1
      summary: Get a rate card's named schedule
      tags:
      - Named schedules
      requestBody:
        description: Which rate card, schedule name, and date to retrieve.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRateCardNamedSchedulePayload'
            example:
              rate_card_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
              schedule_name: my-schedule
              covering_date: '2022-02-15T00:00:00Z'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedSchedule'
              example:
                data:
                - starting_at: '2022-02-01T00:00:00Z'
                  ending_before: '2022-03-01T00:00:00Z'
                  value: my-value
  /v1/contract-pricing/rate-cards/updateNamedSchedule:
    post:
      x-mint:
        groups:
        - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
        - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
        - client_id:f157d376-0781-4ef3-9db9-775a9052148e
        - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
        - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
        - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
      description: Update a named schedule for the given rate card. This endpoint's availability is dependent on your client's configuration.
      operationId: updateRateCardNamedSchedule-v1
      summary: Update a rate card's named schedule
      tags:
      - Named schedules
      requestBody:
        description: The rate card, schedule name, date range, and value to set.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRateCardNamedSchedulePayload'
            example:
              rate_card_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
              schedule_name: my-schedule
              starting_at: '2022-02-01T00:00:00Z'
              ending_before: '2022-02-15T00:00:00Z'
              value:
                my_key: my_value
      responses:
        '200':
          description: Success
components:
  schemas:
    UpdateCustomerNamedSchedulePayload:
      type: object
      required:
      - customer_id
      - schedule_name
      - starting_at
      - value
      properties:
        customer_id:
          type: string
          format: uuid
          description: ID of the customer whose named schedule is to be updated
        schedule_name:
          type: string
          description: The identifier for the schedule to be updated
        starting_at:
          type: string
          format: date-time
        ending_before:
          type: string
          format: date-time
        value:
          description: The value to set for the named schedule. The structure of this object is specific to the named schedule.
    GetContractNamedSchedulePayload:
      type: object
      required:
      - customer_id
      - contract_id
      - schedule_name
      properties:
        customer_id:
          type: string
          format: uuid
          description: ID of the customer whose named schedule is to be retrieved
        contract_id:
          type: string
          format: uuid
          description: ID of the contract whose named schedule is to be retrieved
        schedule_name:
          type: string
          description: The identifier for the schedule to be retrieved
        covering_date:
          type: string
          format: date-time
          description: If provided, at most one schedule segment will be returned (the one that covers this date). If not provided, all segments will be returned.
        properties:
          type: object
          additionalProperties:
            type: string
          description: A set of key-value pairs that qualifies which schedule should be applied when looking up a schedule by name.
          x-stainless-skip: true
          x-mint:
            groups:
            - ff:fancy-schedules-enabled
    ListContractsNamedSchedulesPage:
      type: object
      x-stainless-skip: true
      x-mint:
        groups:
        - ff:fancy-schedules-enabled
      required:
      - data
      - next_page
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContractNamedSchedule'
        next_page:
          type: string
          nullable: true
          description: Cursor for the next page of results.
    GetCustomerNamedSchedulePayload:
      type: object
      required:
      - customer_id
      - schedule_name
      properties:
        customer_id:
          type: string
          format: uuid
          description: ID of the customer whose named schedule is to be retrieved
        schedule_name:
          type: string
          description: The identifier for the schedule to be retrieved
        covering_date:
          type: string
          format: date-time
          description: If provided, at most one schedule segment will be returned (the one that covers this date). If not provided, all segments will be returned.
    UpdateContractNamedSchedulePayload:
      type: object
      required:
      - customer_id
      - contract_id
      - schedule_name
      - starting_at
      - value
      properties:
        customer_id:
          type: string
          format: uuid
          description: ID of the customer whose named schedule is to be updated
        contract_id:
          type: string
          format: uuid
          description: ID of the contract whose named schedule is to be updated
        schedule_name:
          type: string
          description: The identifier for the schedule to be updated
        starting_at:
          type: string
          format: date-time
        ending_before:
          type: string
          format: date-time
        value:
          description: The value to set for the named schedule. The structure of this object is specific to the named schedule.
        properties:
          type: object
          additionalProperties:
            type: string
          description: A set of key-value pairs that qualifies which schedule should be applied when looking up a schedule by name.
          x-stainless-skip: true
          x-mint:
            groups:
            - ff:fancy-schedules-enabled
    UpdateRateCardNamedSchedulePayload:
      type: object
      required:
      - rate_card_id
      - schedule_name
      - starting_at
      - value
      properties:
        rate_card_id:
          type: string
          format: uuid
          description: ID of the rate card whose named schedule is to be updated
        schedule_name:
          type: string
          description: The identifier for the schedule to be updated
        starting_at:
          type: string
          format: date-time
        ending_before:
          type: string
          format: date-time
        value:
          description: The value to set for the named schedule. The structure of this object is specific to the named schedule.
    CustomerContractNamedSchedule:
      type: object
      x-stainless-skip: true
      x-mint:
        groups:
        - ff:fancy-schedules-enabled
      required:
      - contract_id
      - schedule_name
      - segments
      properties:
        contract_id:
          type: string
          format: uuid
          description: ID of the contract this named schedule belongs to.
        schedule_name:
          type: string
          description: Name of the schedule.
        properties:
          type: object
          additionalProperties:
            type: string
          description: Properties on this named schedule.
        segments:
          type: array
          items:
            type: object
            required:
            - starting_at
            - value
            properties:
              value: {}
              starting_at:
                type: string
                format: date-time
              ending_before:
                type: string
                format: date-time
    NamedSchedule:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - starting_at
            - value
            properties:
              value: {}
              starting_at:
                type: string
                format: date-time
              ending_before:
                type: string
                format: date-time
    ListContractsNamedSchedulesPayload:
      type: object
      x-stainless-skip: true
      x-mint:
        groups:
        - ff:fancy-schedules-enabled
      required:
      - customer_id
      properties:
        customer_id:
          type: string
          format: uuid
          description: ID of the customer to list contract named schedules for
        contract_id:
          type: string
          format: uuid
          description: Optional ID of a contract to scope the results to a single contract
        schedule_name:
          type: string
          description: Optional filter to scope the results to a single schedule name
        properties:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value filters. A schedule matches when it contains at least this subset of properties.
        covering_date:
          type: string
          format: date-time
          description: If provided, result contains at most one segment covering this date for each schedule.
        limit:
          type: integer
          description: Maximum number of named schedules to return.
        next_page:
          type: string
          description: Cursor for pagination. Use the value from a previous response's next_page.
    GetRateCardNamedSchedulePayload:
      type: object
      required:
      - rate_card_id
      - schedule_name
      properties:
        rate_card_id:
          type: string
          format: uuid
          description: ID of the rate card whose named schedule is to be retrieved
        schedule_name:
          type: string
          description: The identifier for the schedule to be retrieved
        covering_date:
          type: string
          format: date-time
          description: If provided, at most one schedule segment will be returned (the one that covers this date). If not provided, all segments will be returned.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer