Data plan management — create and configure plans with coverage, data allowances, throttle speeds, validity, and usage notifications.
List plans
Paginated list of plans in your organisation.
Filters combine with AND semantics. Repeatable filters
(operator_ids, compatibility_zones) match any of the provided
values. min/max ranges are inclusive. search does a
case-insensitive substring match across plan name, description, and
id. for_link_id is a convenience filter — resolves the link's
compatibility zones and applies them; if compatibility_zones is
also provided, the link-derived set takes precedence (the service
overwrites the kwarg).
query Parameters
pagePage number (1-based).
Page number (1-based).
page_sizeItems per page.
Items per page.
sort_byField to sort by. Omit for default ordering (most recently updated first).
Field to sort by. Omit for default ordering (most recently updated first).
sort_orderSort direction.
Sort direction.
base_throttleFilter by base throttle speed.
Filter by base throttle speed.
reactivation_triggerFilter by reactivation trigger type.
Filter by reactivation trigger type.
coverage_idFilter to plans using this coverage.
Filter to plans using this coverage.
operator_idsFilter to plans whose coverage includes any of these operator ids. Repeatable.
Filter to plans whose coverage includes any of these operator ids. Repeatable.
compatibility_zonesFilter by compatibility zone (matched against the plan's coverage). Repeatable.
Filter by compatibility zone (matched against the plan's coverage). Repeatable.
min_included_data_mbMinimum bundled data, in MB.
Minimum bundled data, in MB.
max_included_data_mbMaximum bundled data, in MB.
Maximum bundled data, in MB.
min_validity_daysMinimum validity, in days.
Minimum validity, in days.
max_validity_daysMaximum validity, in days.
Maximum validity, in days.
searchFree-text match against plan name, description, or id.
Free-text match against plan name, description, or id.
for_link_idReturn only plans compatible with the given link (matched via compatibility zones).
Return only plans compatible with the given link (matched via compatibility zones).
List plans › Responses
Successful Response
Items on the current page.
totalTotal number of items across all pages.
pageCurrent page number (1-based).
page_sizeItems per page used to compute this response.
pagesTotal number of pages at the current page_size.
Create a plan
Create a plan from a coverage plus usage / activation parameters.
The supplied name is stored locally and never sent to the
upstream system — the upstream side gets a synthesized id, so a
later rename (via PATCH) doesn't propagate. Use notifications to
seed the initial set; further notifications can be added via
POST /plans/{plan_id}/notifications.
reactivation_trigger presence is fixed at creation: a plan
created without one cannot have one added later, and vice versa.
Create a plan › Request Body
nameDisplay name for the plan. Not required to be unique.
coverage_idCoverage this plan applies to.
included_data_mbBundled data in MB.
validity_daysPlan validity from activation, in days.
activation_typeWhen the plan activates after being assigned to a link.
base_throttleBaseline throttle speed — max speed the plan can ever provide.
Free-text description.
In-plan soft cap — speed action applied at threshold.
Initial set of plan notifications. At most one per type.
What triggers plan renewal. Presence is immutable post-create.
Cap on automatic reactivations. -1 means unlimited.
Create a plan › Responses
Plan created.
idInternal plan identifier.
nameCustomer-assigned plan name.
Minimal coverage info embedded on other resources' responses.
Enough to identify a coverage without bloating the host payload
with the full operator list. Used on PlanResponse so a customer
can see which coverage a plan applies to without a second request.
included_data_mbBundled data in MB.
validity_daysPlan validity from activation, in days.
base_throttleBaseline throttle speed — max speed the plan can ever provide.
activation_typeWhen the plan activates after being assigned to a link.
created_atUTC timestamp when the plan was created.
updated_atUTC timestamp of the last update.
Free-text description.
In-plan soft cap.
Renewal trigger, if any.
Max reactivations (-1 = unlimited).
SMS notifications configured for this plan.
compatibility_zonesCompatibility zones derived from the coverage.
Get a plan
Fetch a single plan by id within the caller's organisation.
path Parameters
plan_idGet a plan › Responses
Successful Response
idInternal plan identifier.
nameCustomer-assigned plan name.
Minimal coverage info embedded on other resources' responses.
Enough to identify a coverage without bloating the host payload
with the full operator list. Used on PlanResponse so a customer
can see which coverage a plan applies to without a second request.
included_data_mbBundled data in MB.
validity_daysPlan validity from activation, in days.
base_throttleBaseline throttle speed — max speed the plan can ever provide.
activation_typeWhen the plan activates after being assigned to a link.
created_atUTC timestamp when the plan was created.
updated_atUTC timestamp of the last update.
Free-text description.
In-plan soft cap.
Renewal trigger, if any.
Max reactivations (-1 = unlimited).
SMS notifications configured for this plan.
compatibility_zonesCompatibility zones derived from the coverage.
Delete a plan
Soft-delete a plan.
The upstream resource is deleted and the plan is marked REMOVED
locally — subsequent reads return 410. Notifications attached to
the plan are NOT individually cleaned up (the upstream system drops
them with the plan; locally they persist alongside the soft-deleted
plan row but become unreachable).
A plan that still has active activations or live subscribers cannot be deleted (422).
Returns 204 No Content — same reasoning as DELETE /coverages/{id}:
we deliberately don't expose status on the wire, so a returned
body here would look identical to a pre-delete GET.
path Parameters
plan_idDelete a plan › Responses
Plan deleted.
Update a plan
Patch a plan.
Only fields explicitly present in the payload are forwarded —
payload.model_fields_set is used to distinguish "field omitted"
from "field present with null". Sending null for a nullable
field (description, data_cap, max_reactivations) clears it;
omitting it leaves it unchanged.
Validation rules surface as 422 validation_error:
reactivation_triggerpresence is immutable (cannot add to a trigger-less plan, cannot remove from one that has one).data_cap.threshold_mbcannot exceed the effectiveincluded_data_mb(post-merge with the current plan).
path Parameters
plan_idUpdate a plan › Request Body
New plan name.
New description; pass null to clear.
New coverage id.
New bundled data in MB.
New validity in days.
New base throttle. Use unlimited for no throttle. Omit the field to leave the current value unchanged — null here would canonicalize to unlimited on read, so use the explicit value instead to keep intent obvious.
New data cap; pass null to clear.
New activation type.
New reactivation trigger type. Presence cannot be toggled — to change between two non-null values, send the new value.
New max reactivations (-1 = unlimited); pass null to clear.
Update a plan › Responses
Successful Response
idInternal plan identifier.
nameCustomer-assigned plan name.
Minimal coverage info embedded on other resources' responses.
Enough to identify a coverage without bloating the host payload
with the full operator list. Used on PlanResponse so a customer
can see which coverage a plan applies to without a second request.
included_data_mbBundled data in MB.
validity_daysPlan validity from activation, in days.
base_throttleBaseline throttle speed — max speed the plan can ever provide.
activation_typeWhen the plan activates after being assigned to a link.
created_atUTC timestamp when the plan was created.
updated_atUTC timestamp of the last update.
Free-text description.
In-plan soft cap.
Renewal trigger, if any.
Max reactivations (-1 = unlimited).
SMS notifications configured for this plan.
compatibility_zonesCompatibility zones derived from the coverage.
Add a notification to a plan
Add an SMS notification to a plan.
At most one notification per type per plan — duplicates return 409.
Threshold rules are validated against the type (see
PlanNotificationCreateRequest); mismatches return 422. The full
updated plan is returned so the caller can see the new notification
with its assigned id.
path Parameters
plan_idAdd a notification to a plan › Request Body
typeTypes of plan notifications sent via SMS to the link.
messageSMS body sent to the link (max 85 chars).
Threshold value — MB for data_consumption_absolute, percentage 1-100 for data_consumption_relative, null for activation/expiration.
Add a notification to a plan › Responses
Notification added.
idInternal plan identifier.
nameCustomer-assigned plan name.
Minimal coverage info embedded on other resources' responses.
Enough to identify a coverage without bloating the host payload
with the full operator list. Used on PlanResponse so a customer
can see which coverage a plan applies to without a second request.
included_data_mbBundled data in MB.
validity_daysPlan validity from activation, in days.
base_throttleBaseline throttle speed — max speed the plan can ever provide.
activation_typeWhen the plan activates after being assigned to a link.
created_atUTC timestamp when the plan was created.
updated_atUTC timestamp of the last update.
Free-text description.
In-plan soft cap.
Renewal trigger, if any.
Max reactivations (-1 = unlimited).
SMS notifications configured for this plan.
compatibility_zonesCompatibility zones derived from the coverage.
Update a plan notification
Replace a notification's message and threshold.
type is fixed at creation — to change the type, delete and re-add.
The threshold is validated against the existing notification's type:
relative ∈ [50, 100], absolute > 0, lifecycle types reject any
threshold. Mismatches return 422.
path Parameters
plan_idnotification_idUpdate a plan notification › Request Body
messageNew SMS body (max 85 chars).
New threshold (semantics depend on the notification's type).
Update a plan notification › Responses
Successful Response
idInternal plan identifier.
nameCustomer-assigned plan name.
Minimal coverage info embedded on other resources' responses.
Enough to identify a coverage without bloating the host payload
with the full operator list. Used on PlanResponse so a customer
can see which coverage a plan applies to without a second request.
included_data_mbBundled data in MB.
validity_daysPlan validity from activation, in days.
base_throttleBaseline throttle speed — max speed the plan can ever provide.
activation_typeWhen the plan activates after being assigned to a link.
created_atUTC timestamp when the plan was created.
updated_atUTC timestamp of the last update.
Free-text description.
In-plan soft cap.
Renewal trigger, if any.
Max reactivations (-1 = unlimited).
SMS notifications configured for this plan.
compatibility_zonesCompatibility zones derived from the coverage.