# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.push.express/api/custom-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.