The Event object

Events allow you to track and react to activity in your Zoneless integration. When the state of another API resource changes, Zoneless creates an Event object that contains all the relevant information associated with that action, including the affected API resource.

Stripe API equivalent

For example, a successful payout triggers a payout.paid event, which contains the Payout in the event's data property. Some actions trigger multiple events. For example, when an account is created, it triggers an account.created event.

Configure a webhook endpoint in your platform to listen for events that represent actions your integration needs to respond to. You can also retrieve individual events or a list of events from the API.

Attributes

id string

Unique identifier for the object. Zoneless event IDs are prefixed with evt_z_.

object string

String representing the object's type. Objects of the same type share the same value. Always event.

accountnullable string

The connected account that originates the event.

api_versionnullable string

The API version used to render data when the event was created.

contextnullable string

Authentication context needed to fetch the event or related object.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

data object

Object containing data associated with the event.

livemode boolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

pending_webhooks integer

Number of webhooks that haven't been successfully delivered (for example, to return a 2xx response) to the URLs you specify.

requestnullable object

Information on the API request that triggers the event.

type string

Description of the event (for example, account.updated or payout.paid).

More attributes

THE EVENT OBJECT

{
  "id": "evt_z_1Nv0FGQ9RKHgCVdK",
  "object": "event",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "api_version": null,
  "context": null,
  "created": 1704067200,
  "data": {
    "object": {
      "id": "acct_z_1Nv0FGQ9RKHgCVdK",
      "object": "account",
      "business_profile": {
        "mcc": null,
        "name": "Acme Corp",
        "product_description": null,
        "support_email": null,
        "support_phone": null,
        "support_url": null,
        "url": "https://acme.com"
      },
      "business_type": "individual",
      "capabilities": {
        "transfers": "active",
        "usdc_payouts": "active"
      },
      "charges_enabled": true,
      "country": "US",
      "created": 1704067200,
      "default_currency": "usdc",
      "details_submitted": true,
      "email": "seller@example.com",
      "payouts_enabled": true,
      "type": "express"
    },
    "previous_attributes": null
  },
  "livemode": true,
  "pending_webhooks": 1,
  "platform_account": "acct_z_Platform123abc",
  "request": {
    "id": "req_z_abc123",
    "idempotency_key": null
  },
  "type": "account.updated"
}

Retrieve an event

Retrieves the details of an event if it was created in the last 30 days. Supply the unique identifier of the event, which you might have received in a webhook.

ENDPOINTS

GET /v1/events/:id

Parameters

No parameters.

Returns

Returns an Event object if a valid identifier was provided. All events share a common structure. The only property that will differ is the data property.

In each case, the data dictionary will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, an account.created event will have the same information as retrieving the relevant account would.

In cases where the attributes of an object have changed, data will also contain a dictionary called previous_attributes containing the changes.

GET/v1/events/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const event = await zoneless.events.retrieve('evt_z_1Nv0FGQ9RKHgCVdK');

RESPONSE

{
  "id": "evt_z_1Nv0FGQ9RKHgCVdK",
  "object": "event",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "api_version": null,
  "context": null,
  "created": 1704067200,
  "data": {
    "object": {
      "id": "acct_z_1Nv0FGQ9RKHgCVdK",
      "object": "account",
      "business_profile": {
        "mcc": null,
        "name": "Acme Corp",
        "product_description": null,
        "support_email": null,
        "support_phone": null,
        "support_url": null,
        "url": "https://acme.com"
      },
      "business_type": "individual",
      "capabilities": {
        "transfers": "active",
        "usdc_payouts": "active"
      },
      "charges_enabled": true,
      "country": "US",
      "created": 1704067200,
      "default_currency": "usdc",
      "details_submitted": true,
      "email": "seller@example.com",
      "payouts_enabled": true,
      "type": "express"
    },
    "previous_attributes": null
  },
  "livemode": true,
  "pending_webhooks": 1,
  "platform_account": "acct_z_Platform123abc",
  "request": {
    "id": "req_z_abc123",
    "idempotency_key": null
  },
  "type": "account.updated"
}

List all events

List events, going back up to 30 days. Platforms receive events for themselves and all their connected accounts.

ENDPOINTS

GET /v1/events

Parameters

No required parameters.

More attributes

Returns

A dictionary with a data property that contains an array of up to limit events, starting after event starting_after. Each entry in the array is a separate Event object. If no more events are available, the resulting array is empty.

GET/v1/events

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const events = await zoneless.events.list({
  limit: 3,
});

RESPONSE

{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_z_1Nv0FGQ9RKHgCVdK",
      "object": "event",
      "account": "acct_z_1Nv0FGQ9RKHgCVdK",
      "api_version": null,
      "context": null,
      "created": 1704067200,
      "data": {
        "object": {
          "id": "acct_z_1Nv0FGQ9RKHgCVdK",
          "object": "account",
          "business_type": "individual",
          "capabilities": {
            "transfers": "active",
            "usdc_payouts": "active"
          },
          "charges_enabled": true,
          "country": "US",
          "created": 1704067200,
          "default_currency": "usdc",
          "details_submitted": true,
          "email": "seller@example.com",
          "payouts_enabled": true,
          "type": "express"
        },
        "previous_attributes": null
      },
      "livemode": true,
      "pending_webhooks": 0,
      "platform_account": "acct_z_Platform123abc",
      "request": {
        "id": "req_z_abc123",
        "idempotency_key": null
      },
      "type": "account.created"
    }
  ]
}

Types of events

This is a list of all the event types currently supported by Zoneless. Events use the resource.event naming convention.

Event types

account.created Account

Occurs whenever a connected account is created. data.object is an Account.

account.updated Account

Occurs whenever an account status or property has changed. data.object is an Account.

api_key.created ApiKey

Occurs whenever a new API key is created for the platform.

api_key.updated ApiKey

Occurs whenever an API key is updated (e.g., name changed or rolled).

api_key.deleted ApiKey

Occurs whenever an API key is deleted.

balance.available Balance

Occurs whenever your platform balance or a connected account balance has been updated (e.g., when a transfer is created or a payout is processed). data.object is a Balance.

balance_transaction.created BalanceTransaction

Occurs whenever a new balance transaction is created (transfers, payouts, top-ups, etc.). data.object is a BalanceTransaction.

charge.captured Charge

Occurs whenever a previously uncaptured charge is captured. data.object is a Charge.

charge.expired Charge

Occurs whenever an uncaptured charge expires. data.object is a Charge.

charge.failed Charge

Occurs whenever a failed charge attempt occurs. data.object is a Charge.

charge.pending Charge

Occurs whenever a pending charge is created. data.object is a Charge.

charge.refunded Charge

Occurs whenever a charge is refunded, including partial refunds. data.object is a Charge.

charge.succeeded Charge

Occurs whenever a charge is successful. data.object is a Charge.

charge.updated Charge

Occurs whenever a charge description or metadata is updated, or upon an asynchronous capture. data.object is a Charge.

checkout.session.async_payment_failed CheckoutSession

Occurs when a Checkout Session's payment attempt fails. data.object is a CheckoutSession.

checkout.session.async_payment_succeeded CheckoutSession

Occurs when a Checkout Session's payment attempt succeeds. data.object is a CheckoutSession.

checkout.session.completed CheckoutSession

Occurs when a Checkout Session has been successfully completed. data.object is a CheckoutSession.

checkout.session.expired CheckoutSession

Occurs when a Checkout Session is expired. data.object is a CheckoutSession.

customer.created Customer

Occurs whenever a new customer is created. data.object is a Customer.

customer.updated Customer

Occurs whenever any property of a customer changes. data.object is a Customer.

customer.deleted Customer

Occurs whenever a customer is deleted. data.object is a Customer.

customer.subscription.created Subscription

Occurs whenever a customer is signed up for a new subscription. data.object is a Subscription.

customer.subscription.deleted Subscription

Occurs whenever a customer's subscription ends. data.object is a Subscription.

customer.subscription.paused Subscription

Occurs whenever a subscription's status becomes paused when a trial ends without a payment method. data.object is a Subscription.

customer.subscription.pending_update_applied Subscription

Occurs whenever a pending update is applied to a subscription after the latest invoice is paid. data.object is a Subscription.

customer.subscription.pending_update_expired Subscription

Occurs whenever a pending update expires before it can be applied. data.object is a Subscription.

customer.subscription.resumed Subscription

Occurs whenever a paused subscription is resumed and becomes active again. data.object is a Subscription.

customer.subscription.trial_will_end Subscription

Occurs three days before a subscription's trial period is scheduled to end, if the subscription has a trial period. data.object is a Subscription.

customer.subscription.updated Subscription

Occurs whenever a subscription changes (for example, switching from one price to another, or changing the status from trial to active). data.object is a Subscription.

external_account.created ExternalWallet

Occurs whenever an external wallet is created (a Solana wallet address added to receive USDC payouts). data.object is an ExternalWallet.

external_account.updated ExternalWallet

Occurs whenever an external wallet is updated. data.object is an ExternalWallet.

external_account.deleted ExternalWallet

Occurs whenever an external wallet is deleted. data.object is an ExternalWallet.

invoice.created Invoice

Occurs whenever a new invoice is created. data.object is an Invoice.

invoice.deleted Invoice

Occurs whenever a draft invoice is deleted. data.object is an Invoice.

invoice.finalized Invoice

Occurs whenever a draft invoice is finalized and updated to be an open invoice. data.object is an Invoice.

invoice.marked_uncollectible Invoice

Occurs whenever an invoice is marked uncollectible. data.object is an Invoice.

invoice.paid Invoice

Occurs whenever an invoice payment attempt succeeds or an invoice is marked as paid out-of-band. data.object is an Invoice.

invoice.payment_failed Invoice

Occurs whenever an invoice payment attempt fails, for example due to insufficient USDC or a missing payment method. data.object is an Invoice.

invoice.payment_succeeded Invoice

Occurs whenever an invoice payment attempt succeeds. data.object is an Invoice.

invoice.updated Invoice

Occurs whenever an invoice changes (for example, the invoice amount). data.object is an Invoice.

invoice.voided Invoice

Occurs whenever an invoice is voided. data.object is an Invoice.

invoiceitem.created InvoiceItem

Occurs whenever an invoice item is created. data.object is an InvoiceItem.

invoiceitem.deleted InvoiceItem

Occurs whenever an invoice item is deleted. data.object is an InvoiceItem.

payment_intent.created PaymentIntent

Occurs when a new PaymentIntent is created. data.object is a PaymentIntent.

payment_intent.updated PaymentIntent

Occurs when a PaymentIntent is updated. data.object is a PaymentIntent.

payment_intent.canceled PaymentIntent

Occurs when a PaymentIntent is canceled. data.object is a PaymentIntent.

payment_intent.payment_failed PaymentIntent

Occurs when a PaymentIntent has failed the attempt to create a payment. data.object is a PaymentIntent.

payment_intent.processing PaymentIntent

Occurs when a PaymentIntent has started processing. data.object is a PaymentIntent.

payment_intent.requires_action PaymentIntent

Occurs when a PaymentIntent transitions to requires_action. data.object is a PaymentIntent.

payment_intent.succeeded PaymentIntent

Occurs when a PaymentIntent has successfully completed payment. data.object is a PaymentIntent.

payment_link.created PaymentLink

Occurs whenever a payment link is created. data.object is a PaymentLink.

payment_link.updated PaymentLink

Occurs whenever a payment link is updated. data.object is a PaymentLink.

payout.created Payout

Occurs whenever a payout is created. data.object is a Payout.

payout.updated Payout

Occurs whenever a payout is updated. data.object is a Payout.

payout.paid Payout

Occurs whenever a payout is expected to be available in the destination wallet. The USDC has been sent on-chain to the connected account's Solana wallet. data.object is a Payout.

payout.failed Payout

Occurs whenever a payout attempt fails. This can happen if the destination wallet is invalid or if there's an on-chain error. data.object is a Payout.

payout.canceled Payout

Occurs whenever a payout is canceled. data.object is a Payout.

person.created Person

Occurs whenever a person associated with an account is created. data.object is a Person.

person.updated Person

Occurs whenever a person associated with an account is updated. data.object is a Person.

person.deleted Person

Occurs whenever a person associated with an account is deleted. data.object is a Person.

product.created Product

Occurs whenever a product is created. data.object is a Product.

product.updated Product

Occurs whenever a product is updated. data.object is a Product.

product.deleted Product

Occurs whenever a product is deleted. data.object is a Product.

price.created Price

Occurs whenever a price is created. data.object is a Price.

price.updated Price

Occurs whenever a price is updated. data.object is a Price.

price.deleted Price

Occurs whenever a price is deleted. data.object is a Price.

topup.created TopUp

Occurs whenever a top-up is created. Top-ups add USDC to your platform balance by sending USDC to your platform's Solana wallet. data.object is a TopUp.

topup.canceled TopUp

Occurs whenever a top-up is canceled. data.object is a TopUp.

topup.failed TopUp

Occurs whenever a top-up fails. data.object is a TopUp.

topup.reversed TopUp

Occurs whenever a top-up is reversed. data.object is a TopUp.

topup.succeeded TopUp

Occurs whenever a top-up succeeds and the USDC is available in your platform balance. data.object is a TopUp.

transfer.created Transfer

Occurs whenever a transfer is created. Transfers move funds from your platform balance to a connected account's balance. data.object is a Transfer.

transfer.updated Transfer

Occurs whenever a transfer's description or metadata is updated. data.object is a Transfer.

transfer.reversed Transfer

Occurs whenever a transfer is reversed. data.object is a Transfer.