Stripe Events API
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.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Accounts Account Events API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
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
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Events
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.
tags:
- Events
/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.
tags:
- Events
components:
schemas:
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
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
GetEventsRequest:
type: object
properties: {}
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
GetEventsIdRequest:
type: object
properties: {}