Service changes are asynchronous: the request is validated and recorded, you get 202 Accepted with an operation, and the change is carried out on the tracking platform in the background. Charging starts only when the activation is confirmed.
Request an activation
POST /partner-api/v1/activations
Authorization: Bearer fpk_live_…
Idempotency-Key: order-1042-activation-1
Content-Type: application/json
{
"external_order_reference": "ORDER-1042",
"external_request_id": "ORDER-1042-line-1-activate",
"customer_id": "cus_example_a",
"fleet_id": "flt_example_a",
"device_id": "dev_example_01",
"activate_when": "as_soon_as_ready"
}activate_when is as_soon_as_ready or at:<ISO 8601 UTC> for a scheduled start. The plan is the fleet's plan. The price comes from your rate card — requests never carry prices or payer ids.
{
"object": "operation",
"operation_id": "op_example_1042",
"type": "activation",
"status": "queued",
"service_id": "svc_example_01",
"device_id": "dev_example_01",
"fleet_id": "flt_example_a",
"service_status": "activation_pending",
"external_order_reference": "ORDER-1042",
"external_request_id": "ORDER-1042-line-1-activate",
"billing": {
"state": "not_started",
"policy": "confirmed_active_time",
"rate_card_version": "rc_example_v1",
"plan_code": "pro",
"full_month_price": { "amount_minor": 400, "currency": "GBP", "tax_mode": "exclusive" }
},
"created": true,
"request_id": "req_example_01"
}This means "accepted for processing" — not that the tracker is active or that anything was charged.
Completion
Wait for the service.activation_completed webhook, or poll GET /operations/{id} (scope operations.read, granted by devices.read) with backoff (for example after 2, 5, 15, 30 seconds, then every minute).
{
"object": "operation",
"operation_id": "op_example_1042",
"type": "activation",
"status": "completed",
"service_id": "svc_example_01",
"service_status": "active",
"effective_at": "2026-10-01T09:30:00Z",
"billing_status": "accruing",
"steps": [
{ "step": "service_start", "label": "Tracking service started", "status": "completed" },
{ "step": "confirmation", "label": "Confirmed with the tracking platform", "status": "completed" }
],
"request_id": "req_example_02"
}Operation states
| Status | Meaning | Terminal |
|---|---|---|
queued / scheduled | Waiting to run (scheduled for a future time). | No |
running / retrying | In progress; transient problems are retried with backoff. | No |
completed | Done. effective_at is when the change took effect (and when charging started or stopped). | Yes |
failed | Could not be done; nothing was charged for it. See error. | Yes |
requires_attention | Needs Fleetalyse or you; it will not retry by itself. Event operation.requires_attention. | Until resolved |
cancelled | Withdrawn or superseded by a newer request for the same service. Event operation.cancelled. | Yes |
Duplicates and unknown outcomes
- The same
Idempotency-Keyorexternal_request_idreturns the original operation — never a second service or charge. - Only one activation, reactivation or deactivation can be in progress per service (
409 OPERATION_IN_PROGRESS). - If the tracking platform does not answer, Fleetalyse reconciles before retrying; you simply see the operation take longer.
Service and operation endpoints
| Endpoint | Purpose | Scope |
|---|---|---|
POST /activations | Activate a verified device in a fleet (202 + operation). | services.activate |
POST /services/{id}/deactivations | Stop a service now or at a scheduled time — see Deactivation & charging. | services.deactivate |
POST /services/{id}/reactivations | Start a new charging period for an inactive service. | services.activate |
POST /services/{id}/plan-changes · POST /fleets/{id}/plan-changes | Change the plan of a single-service fleet, or of a whole fleet. | services.activate |
GET /services · GET /services/{id} | Service status, billing state and any pending change. Filters: device_id, fleet_id, customer_id, status. | devices.read |
GET /operations · GET /operations/{id} | Operations and their steps. Filters: status, type, service_id, device_id, fleet_id. | operations.read |
POST /operations/{id}/cancellations | Withdraw a scheduled or not-yet-started change. | operations.read |
All of them live under https://fleetalyse.co.uk/partner-api/v1 and need a management key with the scope shown.