# Custom events

Version date: 26 January 2026

***

> To authorize, you need to add the header `"Authorization: Bearer ..."` (get your API KEY in your personal account on "Personal" tab).

## Endpoints

* [Create a custom event](#create-a-custom-event)
* [List all custom events](#list-all-custom-events)
* [Get a custom event](#get-a-custom-event)
* [Update a custom event](#update-a-custom-event)
* [Delete a custom event](#delete-a-custom-event)
* [Activate a custom event](#activate-a-custom-event)
* [Deactivate a custom event](#deactivate-a-custom-event)

***

### Create a custom event

**POST** `https://core.push.express/api/b/v2/events`

* **Description**: Creates a new custom event.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events"
    --request POST
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
    "name": "Trial event",
    "code": "trial"
}
'
```

### Body params:

* `name`, *required, string*. Name of event.
* `code`, *required, string*. The event code. It is needed to send the event to the PushExpress service. Must contain only alphanumeric characters and underscores.

### Response:

* 201: New event created

```json
{"id":12345}
```

* `id`, *int*. ID of newly created event.

***

### List all custom events

**GET** `https://core.push.express/api/b/v2/events`

* **Description**: Returns a list of all custom events for the authenticated user.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events" \
    --request GET \
    --header "Authorization: Bearer ..."
```

### Response:

* 200: Success

```json
{
"events": [
  {
    "id": 12345,
    "name": "Trial event",
    "code": "trial",
    "status": 1,
    "type": "CUSTOM"
  },
  {
    "id": 12346,
    "name": "Purchase event",
    "code": "purchase",
    "status": 1,
    "type": "CUSTOM"
  }
],
	"pagination": {
		"page": 1,
		"per_page": 50,
		"total_pages": 1,
		"total_count": 3
	}
}
```

* `id`, *int*. Event ID.
* `name`, *string*. Name of event.
* `code`, *string*. Event code.
* `status`, *int*. Event status (0 = inactive, 1 = active).
* `type`, *string*. Event type ("CUSTOM", "SYSTEM").

  **Pagination:**

Now supports one type of pagination:

1. **Page-based pagination** - for UI with numbered pages (limited to 10K records).

**Page-based**

Request

```bash
curl --url "https://core.push.express/api/b/v2/events?page=2&per_page=50"
    --request GET
    --header "Authorization: Bearer ..."
```

Query parameters:

* `page`, *int, optional*. Page number.
* `per_page`, *int, optional*. The number of entries per page.

````

Response:
```json
{
  "events": [
  {
    "id": 12345,
    "name": "Trial event",
    "code": "trial",
    "status": 1,
    "type": "CUSTOM"
  },
  {
    "id": 12346,
    "name": "Purchase event",
    "code": "purchase",
    "status": 1,
    "type": "CUSTOM"
  }
],
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total_pages": 15,
    "total_count": 705
  }
}
````

* `pagination`, *object*. Pagination metadata.
* `pagination.page`, *int*. Current page number.
* `pagination.per_page`, *int*. Records per page.
* `pagination.total_pages`, *int*. Total number of pages.
* `pagination.total_count`, *int*. Total matching records.

**Limit:** Max offset = 10,000 records. UI with numbered pages \[1] \[2] \[3]. Small/medium datasets.

***

### Get a custom event

**GET** `https://core.push.express/api/b/v2/events/{id}`

* **Description**: Returns details of a specific custom event.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events/12345" \
    --request GET \
    --header "Authorization: Bearer ..."
```

### URL params:

* `id`, *required, int*. Event ID.

### Response:

* 200: Success

```json
{
  "id": 12345,
  "name": "Trial event",
  "code": "trial",
  "status": 1,
  "type": "CUSTOM"
}
```

* `id`, *int*. Event ID.
* `name`, *string*. Name of event.
* `code`, *string*. Event code.
* `status`, *int*. Event status (0 = inactive, 1 = active).
* `type`, *string*. Event type.
* 404: Event not found

***

### Update a custom event

**PUT** `https://core.push.express/api/b/v2/events/{id}`

* **Description**: Updates an existing custom event. Only name and code can be updated.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events/12345" \
    --request PUT \
    --header "content-type: application/json" \
    --header "Authorization: Bearer ..." \
    --data '
{
    "name": "Updated Trial event",
    "code": "trial_updated"
}
'
```

### URL params:

* `id`, *required, int*. Event ID.

### Body params:

* `name`, *required, string*. New name of event.
* `code`, *required, string*. New event code. Must contain only alphanumeric characters and underscores.

### Response:

* 200: Event updated

```json
{
  "id": 12345,
  "name": "Updated Trial event",
  "code": "trial_updated",
  "status": 1,
  "type": "CUSTOM"
}
```

* 404: Event not found
* 400: Invalid data or code already exists

***

### Delete a custom event

**DELETE** `https://core.push.express/api/b/v2/events/{id}`

* **Description**: Deletes a custom event permanently.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events/12345" \
    --request DELETE \
    --header "Authorization: Bearer ..."
```

### URL params:

* `id`, *required, int*. Event ID.

### Response:

* 204: Event deleted successfully (no content)
* 404: Event not found

***

### Activate a custom event

**POST** `https://core.push.express/api/b/v2/events/{id}/activate`

* **Description**: Activates a custom event (sets status to 1).

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events/12345/activate" \
    --request POST \
    --header "Authorization: Bearer ..."
```

### URL params:

* `id`, *required, int*. Event ID.

### Response:

* 204: Event activated successfully (no content)
* 404: Event not found

***

### Deactivate a custom event

**POST** `https://core.push.express/api/b/v2/events/{id}/deactivate`

* **Description**: Deactivates a custom event (sets status to 0).

Request:

```bash
curl --url "https://core.push.express/api/b/v2/events/12345/deactivate" \
    --request POST \
    --header "Authorization: Bearer ..."
```

### URL params:

* `id`, *required, int*. Event ID.

### Response:

* 204: Event deactivated successfully (no content)
* 404: Event not found