openapi: 3.0.0
info:
  title: Stripe Events API
  description: >-
    Events are our way of letting you know when something interesting happens in
    your account. When an interesting event occurs, we create a new Event
    object.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
security:
  - basicAuth: []
  - bearerAuth: []
servers:
  - url: https://api.stripe.com/
paths:
  /v1/events:
    get:
      description: >-
        <p>List events, going back up to 30 days. Each event data is rendered
        according to Stripe API version at its creation time, specified in <a
        href="/docs/api/events/object">event object</a> <code>api_version</code>
        attribute (not according to your current Stripe API version or
        <code>Stripe-Version</code> header).</p>
      operationId: getEvents
      parameters:
        - explode: true
          in: query
          name: created
          required: false
          schema:
            anyOf:
              - properties:
                  gt:
                    type: integer
                  gte:
                    type: integer
                  lt:
                    type: integer
                  lte:
                    type: integer
                title: range_query_specs
                type: object
              - type: integer
          style: deepObject
        - description: >-
            Filter events by whether all webhooks were successfully delivered.
            If false, events which are still pending or have failed all delivery
            attempts to a webhook endpoint will be returned.
          in: query
          name: delivery_success
          required: false
          schema:
            type: boolean
          style: form
        - description: >-
            A cursor for use in pagination. `ending_before` is an object ID that
            defines your place in the list. For instance, if you make a list
            request and receive 100 objects, starting with `obj_bar`, your
            subsequent call can include `ending_before=obj_bar` in order to
            fetch the previous page of the list.
          in: query
          name: ending_before
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
        - description: >-
            A limit on the number of objects to be returned. Limit can range
            between 1 and 100, and the default is 10.
          in: query
          name: limit
          required: false
          schema:
            type: integer
          style: form
        - description: >-
            A cursor for use in pagination. `starting_after` is an object ID
            that defines your place in the list. For instance, if you make a
            list request and receive 100 objects, ending with `obj_foo`, your
            subsequent call can include `starting_after=obj_foo` in order to
            fetch the next page of the list.
          in: query
          name: starting_after
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
        - description: >-
            A string containing a specific event name, or group of events using
            * as a wildcard. The list will be filtered to include only events
            with a matching event property.
          in: query
          name: type
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
        - description: >-
            An array of up to 20 strings containing specific event names. The
            list will be filtered to include only events with a matching event
            property. You may pass either `type` or `types`, but not both.
          explode: true
          in: query
          name: types
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetEventsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                  - data
                $ref: '#/components/schemas/NotificationEventList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Events
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Events
        - Get
  /v1/events/{id}:
    get:
      description: >-
        <p>Retrieves the details of an event. Supply the unique identifier of
        the event, which you might have received in a webhook.</p>
      operationId: getEventsId
      parameters:
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
        - in: path
          name: id
          required: true
          schema:
            maxLength: 5000
            type: string
          style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetEventsIdRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Events Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Events
        - Get
        - Identifiers
components:
  schemas:
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
        - error
      type: object
    event:
      description: >-
        Events are our way of letting you know when something interesting
        happens in

        your account. When an interesting event occurs, we create a new `Event`

        object. For example, when a charge succeeds, we create a
        `charge.succeeded`

        event, and when an invoice payment attempt fails, we create an

        `invoice.payment_failed` event. Certain API requests might create
        multiple

        events. For example, if you create a new subscription for a

        customer, you receive both a `customer.subscription.created` event and a

        `charge.succeeded` event.


        Events occur when the state of another API resource changes. The event's
        data

        field embeds the resource's state at the time of the change. For

        example, a `charge.succeeded` event contains a charge, and an

        `invoice.payment_failed` event contains an invoice.


        As with other API resources, you can use endpoints to retrieve an

        [individual event](https://stripe.com/docs/api#retrieve_event) or a
        [list of events](https://stripe.com/docs/api#list_events)

        from the API. We also have a separate

        [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the

        `Event` objects directly to an endpoint on your server. You can manage

        webhooks in your

        [account settings](https://dashboard.stripe.com/account/webhooks). Learn
        how

        to [listen for events](https://stripe.com/docs/webhooks)

        so that your integration can automatically trigger reactions.


        When using [Connect](https://stripe.com/docs/connect), you can also
        receive event notifications

        that occur in connected accounts. For these events, there's an

        additional `account` attribute in the received `Event` object.


        We only guarantee access to events through the [Retrieve Event
        API](https://stripe.com/docs/api#retrieve_event)

        for 30 days.
      properties:
        account:
          description: The connected account that originates the event.
          maxLength: 5000
          type: string
        api_version:
          description: >-
            The Stripe API version used to render `data`. This property is
            populated only for events on or after October 31, 2014.
          maxLength: 5000
          nullable: true
          type: string
        created:
          description: >-
            Time at which the object was created. Measured in seconds since the
            Unix epoch.
          format: unix-time
          type: integer
        data:
          $ref: '#/components/schemas/notification_event_data'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        livemode:
          description: >-
            Has the value `true` if the object exists in live mode or the value
            `false` if the object exists in test mode.
          type: boolean
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - event
          type: string
        pending_webhooks:
          description: >-
            Number of webhooks that haven't been successfully delivered (for
            example, to return a 20x response) to the URLs you specify.
          type: integer
        request:
          anyOf:
            - $ref: '#/components/schemas/notification_event_request'
          description: Information on the API request that triggers the event.
          nullable: true
        type:
          description: >-
            Description of the event (for example, `invoice.created` or
            `charge.refunded`).
          maxLength: 5000
          type: string
      required:
        - created
        - data
        - id
        - livemode
        - object
        - pending_webhooks
        - type
      title: NotificationEvent
      type: object
      x-expandableFields:
        - data
        - request
      x-resourceId: event
    GetEventsRequest:
      type: object
      properties: {}
    NotificationEventList:
      type: object
      required:
        - data
        - has_more
        - object
        - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/event'
          type: array
        has_more:
          description: >-
            True if this list has another page of items after this one that can
            be fetched.
          type: boolean
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value. Always has the value `list`.
          enum:
            - list
          type: string
        url:
          description: The URL where this list can be accessed.
          maxLength: 5000
          pattern: ^/v1/events
          type: string
    GetEventsIdRequest:
      type: object
      properties: {}
  securitySchemes:
    basicAuth:
      description: >-
        Basic HTTP authentication. Allowed headers-- Authorization: Basic
        <api_key> | Authorization: Basic <base64 hash of `api_key:`>
      scheme: basic
      type: http
    bearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
tags:
  - name: Events
  - name: Get
  - name: Identifiers