Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating a bus

You create a bus with CreateEventBus, for example aws eventsv2 create-event-bus --name orders. The name is the only required parameter. At creation you can also set a description, the number of days the bus retains events, the Amazon KMS key that encrypts them, and tags. The call returns at once with the bus in the CREATING state; publish to the bus or create a subscriber on it once DescribeEventBus reports ACTIVE.

Creating a bus with the Amazon CLI

The following command creates a bus named orders that retains events for 30 days, encrypts them with your Amazon KMS key, and carries one tag.

aws eventsv2 create-event-bus \
    --name orders \
    --description "Order events from the checkout service" \
    --storage-configuration RetentionPeriodInDays=30 \
    --encryption-configuration KmsKeyIdentifier=arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags team=orders

The following table lists what each parameter accepts.

The response returns the bus ARN, which every later call on the bus uses. The ARN ends in an identifier that EventBridge generates, so you cannot construct it from the name.

{
    "EventBusArn": "arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef",
    "Name": "orders",
    "Description": "Order events from the checkout service",
    "EncryptionConfiguration": {
        "KmsKeyIdentifier": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    "StorageConfiguration": {
        "RetentionPeriodInDays": 30,
        "RetentionWindowStartTime": "2026-09-21T16:00:00+00:00"
    },
    "State": "CREATING",
    "CreationTime": "2026-09-21T16:00:00+00:00"
}

Describe the bus by its ARN until State is ACTIVE.

aws eventsv2 describe-event-bus \
    --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef

To create a bus with Amazon CloudFormation instead, see Creating Custom Event Bus resources with Amazon CloudFormation. For the IAM actions that creating and describing a bus require, see Actions, resources, and condition keys for the Custom Event Bus.

Choosing the retention period

A bus retains every event that it accepts for the number of days in StorageConfiguration.RetentionPeriodInDays, from 1 to 365; omit it and the bus retains events for 1 day. Retention is what lets a subscriber start from a point in the past, pause and resume without losing events, and read events again after a failure. A longer period costs more storage. You can change the period later with UpdateEventBus.

aws eventsv2 create-event-bus \
    --name orders \
    --storage-configuration RetentionPeriodInDays=30

DescribeEventBus returns RetentionWindowStartTime, the earliest point that a subscriber can read from. To deliver retained events to a subscriber, see Replaying retained events to a subscriber.

Bus states and what each allows

Creating, updating, and deleting a bus are asynchronous. Every state other than ACTIVE refuses some operations, and the three failed states carry a StateReason that tells you why. The following table lists the states a bus moves through and what you can do in each.

Deleting a bus that has subscribers

DeleteEventBus succeeds only when every subscriber and event source on the bus is deleted or revoked. A subscriber that another account created counts. You cannot delete that account's subscriber yourself, so either ask the owner to delete it or revoke it with RevokeResource; see Revoking a subscriber or an event source. If a subscriber is created between your check and the delete, the bus lands in DELETE_FAILED; deal with the new subscriber and delete again.

Recovering from a failed key change

Both failed states that a running bus can reach come from the Amazon KMS key. When an update to a new key fails, retry UpdateEventBus after you fix the key's policy or grant. If the new key itself is unusable, the retry can name a different key, because EventBridge did not adopt the failed key. Do not disable, delete, or remove EventBridge's access to the previous key until DescribeEventBus shows the bus ACTIVE with the new key; a bus that loses its old key part-way through a change can only be repaired by restoring that key, or deleted. For the key permissions, see Encrypting events on a Custom Event Bus.