Send app events

POST/v1/app_events

Accepts up to 100 events in one request. With a member token, every event belongs to that member. With a secret key (from your server), each event names its guest with member_id or anonymous_id. Events are deduplicated by event_id, so resending a batch after a timeout is safe. They reach unPLUG within about 20 minutes.

Permissions: Member token, or secret key with members:write.

Guide

App events

Request headers#

Idempotency-Keystring
Any string up to 255 characters; use a UUID v4. Kept 24 hours per key (or member) and endpoint. Same key and body replays the first response with Idempotent-Replayed: true.
Max Length 255

Request body#

eventsarray of AppEventRequired
1 to 100 events.
Min Items 1Max Items 100
Show attributesAppEvent
- event_idstring (uuid)Required
  Created once when the event happens and reused on every retry.
- namestringRequired
  snake_case, up to 64 characters. Recommended: app_opened, session_started, screen_viewed, product_viewed, added_to_cart, removed_from_cart, checkout_started, signed_up, signed_in, push_permission_changed, reward_viewed.
- occurred_atstring (date-time)Required
  When it happened on the device.
- member_idstring (uuid)
  Secret key only. The member, if the guest is signed in. Ignored with a member token.
- anonymous_idstring
  Your id for the install, created before sign-in. With a secret key, send member_id, anonymous_id or both.
- device_idstringRequired
  The same id you use for device registration. For a website, a per-browser id.
- session_idstringRequired
  Your id for the current session.
- propertiesobject
  Flat key and value pairs: strings, numbers or booleans. No personal data: no names, email addresses, phone numbers, street addresses or text the guest typed.

accepted counts new events. duplicates counts events whose event_id was already received; they are dropped.

Response fields#

Returns 202 with AppEventResult

acceptedinteger
duplicatesinteger

From your server#

POSTRequest

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl -X POST https://api.unplugdining.com/v1/app_events \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "b6e0d4a8-3c1f-4a72-9e5b-8d2f7c0a1e93",
        "name": "screen_viewed",
        "occurred_at": "2026-11-03T14:08:12Z",
        "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
        "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
        "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
        "properties": { "screen": "menu" }
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21const response = await fetch("https://api.unplugdining.com/v1/app_events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "b6e0d4a8-3c1f-4a72-9e5b-8d2f7c0a1e93",
        name: "screen_viewed",
        occurred_at: "2026-11-03T14:08:12Z",
        anonymous_id: "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
        device_id: "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
        session_id: "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
        properties: { screen: "menu" },
      },
    ],
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import os
import requests

response = requests.post(
    "https://api.unplugdining.com/v1/app_events",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
    json={
        "events": [
            {
                "event_id": "b6e0d4a8-3c1f-4a72-9e5b-8d2f7c0a1e93",
                "name": "screen_viewed",
                "occurred_at": "2026-11-03T14:08:12Z",
                "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
                "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
                "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
                "properties": {"screen": "menu"},
            },
        ],
    },
)
data = response.json()

POST/v1/app_events

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40curl -X POST https://api.unplugdining.com/v1/app_events \
  -H "Authorization: Bearer mt_4kQ9xV2mR7tB8nW3pL6yZ1cH5fJ0dS" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "e2b7c4a1-9d38-4f65-8a0e-3c1f6b9d2e57",
        "name": "added_to_cart",
        "occurred_at": "2026-11-03T14:12:40Z",
        "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
        "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
        "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
        "properties": {
          "cart_id": "cart_5Tn8qW2x",
          "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
          "name": "Oat latte",
          "quantity": 1,
          "price_cents": 575,
          "currency": "USD",
          "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53"
        }
      },
      {
        "event_id": "7a3d9f0c-2e6b-4b18-a4c7-5e9b1d3f8a26",
        "name": "checkout_started",
        "occurred_at": "2026-11-03T14:13:05Z",
        "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
        "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
        "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
        "properties": {
          "cart_id": "cart_5Tn8qW2x",
          "subtotal_cents": 1000,
          "currency": "USD",
          "item_count": 2,
          "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
          "fulfillment": "pickup"
        }
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45const response = await fetch("https://api.unplugdining.com/v1/app_events", {
  method: "POST",
  headers: {
    Authorization: "Bearer mt_4kQ9xV2mR7tB8nW3pL6yZ1cH5fJ0dS",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "e2b7c4a1-9d38-4f65-8a0e-3c1f6b9d2e57",
        name: "added_to_cart",
        occurred_at: "2026-11-03T14:12:40Z",
        anonymous_id: "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
        device_id: "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
        session_id: "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
        properties: {
          cart_id: "cart_5Tn8qW2x",
          pos_item_id: "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
          name: "Oat latte",
          quantity: 1,
          price_cents: 575,
          currency: "USD",
          location_id: "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
        },
      },
      {
        event_id: "7a3d9f0c-2e6b-4b18-a4c7-5e9b1d3f8a26",
        name: "checkout_started",
        occurred_at: "2026-11-03T14:13:05Z",
        anonymous_id: "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
        device_id: "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
        session_id: "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
        properties: {
          cart_id: "cart_5Tn8qW2x",
          subtotal_cents: 1000,
          currency: "USD",
          item_count: 2,
          location_id: "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
          fulfillment: "pickup",
        },
      },
    ],
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46import requests

response = requests.post(
    "https://api.unplugdining.com/v1/app_events",
    headers={
        "Authorization": "Bearer mt_4kQ9xV2mR7tB8nW3pL6yZ1cH5fJ0dS",
    },
    json={
        "events": [
            {
                "event_id": "e2b7c4a1-9d38-4f65-8a0e-3c1f6b9d2e57",
                "name": "added_to_cart",
                "occurred_at": "2026-11-03T14:12:40Z",
                "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
                "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
                "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
                "properties": {
                    "cart_id": "cart_5Tn8qW2x",
                    "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
                    "name": "Oat latte",
                    "quantity": 1,
                    "price_cents": 575,
                    "currency": "USD",
                    "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
                },
            },
            {
                "event_id": "7a3d9f0c-2e6b-4b18-a4c7-5e9b1d3f8a26",
                "name": "checkout_started",
                "occurred_at": "2026-11-03T14:13:05Z",
                "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
                "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
                "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
                "properties": {
                    "cart_id": "cart_5Tn8qW2x",
                    "subtotal_cents": 1000,
                    "currency": "USD",
                    "item_count": 2,
                    "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
                    "fulfillment": "pickup",
                },
            },
        ],
    },
)
data = response.json()

Response JSON202

1
2
3
4{
  "accepted": 2,
  "duplicates": 0
}

Error descriptions#

400Bad request

invalid_param

A field is the wrong type, a batch has more than 100 events, or properties isn't flat. param names the event, for example events[1].occurred_at. The whole batch is refused; drop or fix that event and resend.

400Bad request

missing_param

A required field is missing, or a secret-key event has neither member_id nor anonymous_id.

404Not found

member_not_found

Secret key only, a member_id that doesn't exist.

401Unauthorized

token_expired

Get a new member token and resend the batch.

429Too many requests

rate_limited

Wait Retry-After seconds and resend. Batching keeps you well under the limit.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#invalid_param",
  "title": "Bad request",
  "status": 400,
  "code": "invalid_param",
  "detail": "A field is the wrong type, a batch has more than 100 events, or properties isn't flat. param names the event, for example events[1].occurred_at. The whole batch is refused; drop or fix that event and resend."
}