# Track

URL: https://pieowl.com/docs/api/track



Good to know [#good-to-know]

* Send the `pieowl-client-ip` header with the visitor's IP address to get their location. Pieowl uses the IP only for the location lookup and the visitor hash. It does not store it.
* Send the `user-agent` header with the visitor's user agent to get their device, browser and OS.

Authentication [#authentication]

Any client type works. From a server, send your client ID and client secret. See the [Authentication](/docs/api/authentication) guide.

```bash
-H "pieowl-client-id: YOUR_CLIENT_ID" \
-H "pieowl-client-secret: YOUR_CLIENT_SECRET"
```

Base URL [#base-url]

```
https://api.pieowl.com
```

Event types [#event-types]

Send a `POST` request to `/track`. The `type` field decides what gets recorded, and `payload` holds the data:

| Type           | What it does                                   |
| -------------- | ---------------------------------------------- |
| `track`        | Records a named event with optional properties |
| `identify`     | Creates or updates a user profile              |
| `increment`    | Adds to a number property on a profile         |
| `decrement`    | Subtracts from a number property on a profile  |
| `group`        | Creates or updates a group                     |
| `assign_group` | Links a profile to one or more groups          |

Example: track an event [#example-track-an-event]

```bash
curl -X POST 'https://api.pieowl.com/track' \
  -H 'Content-Type: application/json' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET' \
  -H 'pieowl-client-ip: 203.0.113.42' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)' \
  -d '{
    "type": "track",
    "payload": {
      "name": "signup",
      "properties": { "plan": "pro" },
      "profileId": "user_123"
    }
  }'
```

A successful request returns `200` with the `deviceId` and `sessionId` the event was linked to.

Example: send a purchase [#example-send-a-purchase]

A purchase is a `track` event named `revenue`. `__amount` is in normal units, like `49.99`. `__currency` is optional and defaults to your site currency. `__orderId` is your order number: the same order sent twice counts once. `__deviceId` is the visitor's device ID from `pieowl.getDeviceId()` in the browser, so the purchase is credited to their visit.

```bash
curl -X POST 'https://api.pieowl.com/track' \
  -H 'Content-Type: application/json' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET' \
  -d '{
    "type": "track",
    "payload": {
      "name": "revenue",
      "properties": {
        "__amount": 49.99,
        "__currency": "EUR",
        "__orderId": "A-1001",
        "__deviceId": "DEVICE_ID"
      }
    }
  }'
```

For a refund, send the same event with `"__refund": true` and the `__orderId`. Leave out `__amount` to refund the whole order. See [Revenue attribution](/docs/revenue-attribution).

Example: identify a user [#example-identify-a-user]

```bash
curl -X POST 'https://api.pieowl.com/track' \
  -H 'Content-Type: application/json' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET' \
  -d '{
    "type": "identify",
    "payload": {
      "profileId": "user_123",
      "email": "jane@example.com",
      "firstName": "Jane",
      "properties": { "company": "Example Inc" }
    }
  }'
```

Groups and events [#groups-and-events]

Pieowl never adds groups to events on its own, not even after `assign_group`. Pass `groups` on each `track` call that needs group data.

For the full request and response schema of every event type, see the [API Reference](/docs/api-reference/track/track/post).