Events

Events are how your software tells Zahrex what happened.

The response lists each event in results as accepted, duplicate, or rejected with an error. A rejected event does not fail the others in the batch.

You can send up to 100 events in one batch.

`customer.upserted`

Create a customer, or update the one with the same phone or email.

Scope: customers:write

Required: namephone or email

Optional: cityexternal_idsourcenotetagsstage

data

{
  "name": "Sara Example",
  "phone": "+212600000000",
  "email": "sara@example.com",
  "city": "Casablanca",
  "tags": [
    "vip"
  ]
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "customer.upserted",
  "data": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com",
    "city": "Casablanca",
    "tags": [
      "vip"
    ]
  }
}'

`lead.created`

A new prospect who has not bought yet.

Scope: leads:write

Required: namephone or email

Optional: cityexternal_idsourcenotetagsstage

data

{
  "name": "Sara Example",
  "phone": "+212600000000",
  "email": "sara@example.com",
  "source": "pricing_page",
  "stage": "signed_up"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "lead.created",
  "data": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com",
    "source": "pricing_page",
    "stage": "signed_up"
  }
}'

`order.created`

A new order with its line items.

Scope: orders:write

Required: external_idcustomer.nameitems[].nameitems[].quantityitems[].unit_pricecurrencytotal

Optional: customer.phonecustomer.emailcustomer.citystatuspayment_status

data

{
  "external_id": "ord_1001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "items": [
    {
      "name": "Starter plan",
      "quantity": 1,
      "unit_price": 29
    }
  ],
  "currency": "USD",
  "total": 29,
  "payment_status": "pending"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "order.created",
  "data": {
    "external_id": "ord_1001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "items": [
      {
        "name": "Starter plan",
        "quantity": 1,
        "unit_price": 29
      }
    ],
    "currency": "USD",
    "total": 29,
    "payment_status": "pending"
  }
}'

`payment.succeeded`

A payment for an order went through.

Scope: orders:write

Required: order_external_idamountcurrency

data

{
  "order_external_id": "ord_1001",
  "amount": 29,
  "currency": "USD"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "payment.succeeded",
  "data": {
    "order_external_id": "ord_1001",
    "amount": 29,
    "currency": "USD"
  }
}'

`payment.refunded`

A payment for an order was refunded.

Scope: orders:write

Required: order_external_idamountcurrency

data

{
  "order_external_id": "ord_1001",
  "amount": 29,
  "currency": "USD"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "payment.refunded",
  "data": {
    "order_external_id": "ord_1001",
    "amount": 29,
    "currency": "USD"
  }
}'

`subscription.started`

A customer started a subscription.

Scope: events:write

Required: external_idcustomerplan

Optional: amountcurrencyinterval

data

{
  "external_id": "sub_2001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "plan": "Pro",
  "amount": 29,
  "currency": "USD",
  "interval": "month"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "subscription.started",
  "data": {
    "external_id": "sub_2001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "plan": "Pro",
    "amount": 29,
    "currency": "USD",
    "interval": "month"
  }
}'

`subscription.renewed`

A subscription renewed for another period.

Scope: events:write

Required: external_idcustomerplan

Optional: amountcurrencyinterval

data

{
  "external_id": "sub_2001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "plan": "Pro",
  "amount": 29,
  "currency": "USD",
  "interval": "month"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "subscription.renewed",
  "data": {
    "external_id": "sub_2001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "plan": "Pro",
    "amount": 29,
    "currency": "USD",
    "interval": "month"
  }
}'

`subscription.canceled`

A customer canceled a subscription.

Scope: events:write

Required: external_idcustomerplan

Optional: amountcurrencyinterval

data

{
  "external_id": "sub_2001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "plan": "Pro"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "subscription.canceled",
  "data": {
    "external_id": "sub_2001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "plan": "Pro"
  }
}'

`booking.created`

A customer booked a time slot.

Scope: events:write

Required: external_idcustomerstarts_at

Optional: ends_atservice

data

{
  "external_id": "bk_3001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "starts_at": "2026-12-01T10:00:00Z",
  "ends_at": "2026-12-01T10:30:00Z",
  "service": "Consultation"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "booking.created",
  "data": {
    "external_id": "bk_3001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "starts_at": "2026-12-01T10:00:00Z",
    "ends_at": "2026-12-01T10:30:00Z",
    "service": "Consultation"
  }
}'

`booking.updated`

A booking changed, for example to a new time.

Scope: events:write

Required: external_idcustomerstarts_at

Optional: ends_atservice

data

{
  "external_id": "bk_3001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "starts_at": "2026-12-02T10:00:00Z"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "booking.updated",
  "data": {
    "external_id": "bk_3001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "starts_at": "2026-12-02T10:00:00Z"
  }
}'

`booking.canceled`

A booking was canceled.

Scope: events:write

Required: external_idcustomerstarts_at

Optional: ends_atservice

data

{
  "external_id": "bk_3001",
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  },
  "starts_at": "2026-12-01T10:00:00Z"
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "booking.canceled",
  "data": {
    "external_id": "bk_3001",
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    },
    "starts_at": "2026-12-01T10:00:00Z"
  }
}'

`form.submitted`

A visitor submitted a form on your site.

Scope: events:write

Required: formfields

Optional: customer

data

{
  "form": "contact",
  "fields": {
    "message": "Hello"
  },
  "customer": {
    "name": "Sara Example",
    "phone": "+212600000000",
    "email": "sara@example.com"
  }
}

curl

curl -X POST https://api.zahrex.com/v1/events \
  -H "Authorization: Bearer $ZAHREX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_0001",
  "type": "form.submitted",
  "data": {
    "form": "contact",
    "fields": {
      "message": "Hello"
    },
    "customer": {
      "name": "Sara Example",
      "phone": "+212600000000",
      "email": "sara@example.com"
    }
  }
}'

Custom events

Event types matching custom.<name> are accepted as custom events with scope events:write, up to 32768 bytes each.