Metronome Notifications API

openapi: 3.0.1
info:
  title: Metronome Alerts Notifications 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: Notifications
paths:
  /v2/notifications/create:
    post:
      description: 'Create an offset lifecycle event notification configuration. The lifecycle event type is inferred from the policy.type field.

        '
      summary: Create an offset lifecycle event notification configuration
      operationId: createNotificationConfig-v2
      tags:
      - Notifications
      requestBody:
        description: Notification configuration details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotificationConfigPayload'
            example:
              name: +1 day after contract starts
              policy:
                type: contract.start
                offset: P1D
              uniqueness_key: contract-start-notification-823j7fqzo1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/LifecycleEventOffsetNotificationConfig'
              example:
                data:
                  id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
                  name: +1 day after contract starts
                  type: OFFSET_LIFECYCLE_EVENT
                  policy:
                    type: contract.start
                    offset: P1D
                  environment_type: PRODUCTION
                  created_at: '2024-01-15T10:30:00Z'
                  created_by: Martins Seyi
                  archived_at: null
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - BadRequest
                  message:
                    type: string
  /v2/notifications/get:
    post:
      description: Retrieve a specific offset lifecycle event notification configuration by ID.
      summary: Get an offset lifecycle event notification configuration
      operationId: getNotificationConfig-v2
      tags:
      - Notifications
      requestBody:
        description: Offset notification configuration ID
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetNotificationConfigPayload'
            example:
              id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/LifecycleEventOffsetNotificationConfig'
              example:
                data:
                  id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
                  name: +1 day after contract starts
                  type: OFFSET_LIFECYCLE_EVENT
                  policy:
                    type: contract.start
                    offset: P1D
                  environment_type: PRODUCTION
                  created_at: '2024-01-15T10:30:00Z'
                  created_by: Martins Seyi
                  archived_at: null
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - BadRequest
                  message:
                    type: string
        '404':
          description: Error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - NotificationConfigNotFound
                  message:
                    type: string
  /v2/notifications/offset/list:
    post:
      description: 'List offset lifecycle event notification configurations. These are user-created notifications that trigger at a specified time offset relative to lifecycle events. Returns a maximum of 400 results per request.

        '
      summary: List offset lifecycle event notification configurations
      operationId: listOffsetNotificationConfigs-v2
      tags:
      - Notifications
      requestBody:
        description: Optional pagination and filtering parameters
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListOffsetNotificationConfigsPayload'
            example:
              limit: 20
              cursor: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
              archive_filter: NOT_ARCHIVED
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LifecycleEventOffsetNotificationConfig'
                  cursor:
                    type: string
                    nullable: true
              example:
                data:
                - id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
                  name: +1 day after contract starts
                  type: OFFSET_LIFECYCLE_EVENT
                  policy:
                    type: contract.start
                    offset: P1D
                  environment_type: PRODUCTION
                  created_at: '2024-01-15T10:30:00Z'
                  created_by: Martins Seyi
                  archived_at: null
  /v2/notifications/system/list:
    post:
      description: List available system lifecycle event types for notifications. These are read-only event types that can be used when creating offset notifications.
      summary: List system notification event types
      operationId: listSystemNotificationConfigs-v2
      tags:
      - Notifications
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LifecycleEventSystemNotificationConfig'
                  cursor:
                    type: string
                    nullable: true
              example:
                data:
                - type: SYSTEM_LIFECYCLE_EVENT
                  policy:
                    type: contract.create
                cursor: null
  /v2/notifications/edit:
    post:
      description: Edit an existing offset lifecycle event notification configuration.
      summary: Edit an offset lifecycle event notification configuration
      operationId: editNotificationConfig-v2
      tags:
      - Notifications
      requestBody:
        description: Offset notification configuration updates
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditNotificationConfigPayload'
            example:
              id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
              policy:
                type: contract.start
                offset: P2D
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/LifecycleEventSystemNotificationConfig'
                    - $ref: '#/components/schemas/LifecycleEventOffsetNotificationConfig'
              example:
                data:
                  id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
                  name: +1 day after contract starts
                  type: OFFSET_LIFECYCLE_EVENT
                  policy:
                    type: contract.start
                    offset: P2D
                  environment_type: PRODUCTION
                  created_at: '2024-01-15T10:30:00Z'
                  created_by: Martins Seyi
                  archived_at: null
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - NotificationConfigNotFound
                    - BadRequest
                  message:
                    type: string
  /v2/notifications/archive:
    post:
      description: 'Archive an offset lifecycle event notification configuration. Archived notifications are not processed.

        '
      summary: Archive an offset lifecycle event notification configuration
      operationId: archiveNotificationConfig-v2
      tags:
      - Notifications
      requestBody:
        description: Offset notification configuration ID to archive
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveNotificationConfigPayload'
            example:
              id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/LifecycleEventOffsetNotificationConfig'
              example:
                data:
                  id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
                  name: +1 day after contract starts
                  type: OFFSET_LIFECYCLE_EVENT
                  policy:
                    type: contract.start
                    offset: P1D
                  environment_type: PRODUCTION
                  created_at: '2024-01-15T10:30:00Z'
                  created_by: Martins Seyi
                  archived_at: null
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - BadRequest
                  message:
                    type: string
        '404':
          description: Error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - NotificationConfigNotFound
                  message:
                    type: string
components:
  schemas:
    GetNotificationConfigPayload:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the notification configuration to retrieve
    EditNotificationConfigPayload:
      type: object
      required:
      - policy
      properties:
        id:
          type: string
          format: uuid
          description: 'The ID of the notification configuration to edit. Not provided when updating the configuration for system events

            '
        is_enabled:
          type: boolean
          description: 'Set to true to enable webhook messages for the notification indicated in the policy, false to disable.

            Only supported by system lifecycle events.

            '
        policy:
          oneOf:
          - $ref: '#/components/schemas/LifecycleEventOffsetPolicy'
          - $ref: '#/components/schemas/LifecycleEventSystemPolicy'
          description: Updated policy configuration. The policy.type must match the existing lifecycle event type.
    LifecycleEventOffsetPolicy:
      type: object
      required:
      - type
      - offset
      properties:
        type:
          type: string
          description: 'The type of lifecycle event that this offset is based on.

            '
        offset:
          type: string
          description: 'ISO-8601 duration string indicating how much time before or after the base event this notification should be sent. Positive values indicate notifications after the event, negative values indicate notifications before the event. Examples: "P1D" (1 day after), "-PT2H" (2 hours before)

            '
          example: P1D
    UniquenessKey:
      type: string
      minLength: 1
      maxLength: 128
      description: Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.
    CreateNotificationConfigPayload:
      type: object
      required:
      - name
      - policy
      properties:
        name:
          type: string
          description: 'The name for this offset notification configuration.

            '
        policy:
          description: 'The offset lifecycle event policy that defines when and how this notification should be triggered. The lifecycle event type is inferred from the policy.type field.

            '
          $ref: '#/components/schemas/LifecycleEventOffsetPolicy'
        uniqueness_key:
          $ref: '#/components/schemas/UniquenessKey'
          description: 'Optional uniqueness key to prevent duplicate notification configurations.

            '
    ListOffsetNotificationConfigsPayload:
      type: object
      properties:
        limit:
          type: number
        cursor:
          type: string
        archive_filter:
          type: string
          enum:
          - ARCHIVED
          - NOT_ARCHIVED
          - ALL
          description: Filter options for the notification configurations. If not provided, defaults to NOT_ARCHIVED.
    LifecycleEventSystemNotificationConfig:
      type: object
      required:
      - type
      - policy
      properties:
        type:
          type: string
          description: Indicates this is a system lifecycle event notification
        is_enabled:
          type: boolean
          description: Whether or not webhook publishing for this lifecycle event is enabled
        policy:
          $ref: '#/components/schemas/LifecycleEventSystemPolicy'
    ArchiveNotificationConfigPayload:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: 'The ID of the offset lifecycle event notification configuration to archive.

            '
    LifecycleEventOffsetNotificationConfig:
      type: object
      required:
      - id
      - name
      - type
      - policy
      - environment_type
      - created_at
      - created_by
      - archived_at
      properties:
        id:
          type: string
          format: uuid
          description: ID for this offset notification configuration
        name:
          type: string
          description: 'The name for this offset notification configuration.

            '
        type:
          type: string
          description: Indicates this is an offset lifecycle event notification
        policy:
          $ref: '#/components/schemas/LifecycleEventOffsetPolicy'
        environment_type:
          type: string
          description: 'The environment type where this notification configuration was created.

            '
        created_at:
          type: string
          format: date-time
          description: 'RFC 3339 timestamp when this notification configuration was created.

            '
        created_by:
          type: string
          description: Who created this notification configuration
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: When this notification configuration was archived
    LifecycleEventSystemPolicy:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: The type of lifecycle event (e.g., "contract.create", "contract.start")
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer