Features

Methods

GET

Retrieve Single Feature

/backend/api/v1/features/ID - fetch feature with specified ID.

List Features

/backend/api/v1/features/ - list all features.

/backend/api/v1/customers/ID/features/ - list features belonging to customer with specified ID.

/backend/api/v1/customers/ID/features/?includeNumbers - list features belonging to customer with specified ID, including those on numbers owned by the customer.

/backend/api/v1/numbers/ID/features/ - list features belonging to number with specified ID.

Additional Query Parameters

Search Example:

# Find feature by CRM reference
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/features?CRMReference=CRM-12345"

# Find only active features by CRM reference
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/features?CRMReference=CRM-12345&active=true"

# Search within a specific customer's features
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers/123/features?CRMReference=CRM-12345"

# Search within a specific number's features
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers/456/features?CRMReference=CRM-12345"

Search Notes:

• The CRMReference parameter performs an exact match
• Returns an array containing a single feature (or empty array if not found)
• CRM references are unique, so only one result is expected
• Can be used with customer-specific or number-specific endpoints
• Combining with filters like active can exclude dropped features
• Optimised for performance using indexed fields

POST

/backend/api/v1/customers/ID/features/ - add a new feature to the specified customer, the newly-added feature will be returned.

/backend/api/v1/numbers/ID/features/ - add a new feature to the specified number, the newly-added feature will be returned.

PATCH

/backend/api/v1/features/ID - update feature with specified ID. The modified feature will be returned.

DELETE

/backend/api/v1/features/ID - delete feature with specified ID.

Actions

Available Actions

drop

Drop (deactivate) a feature. This action changes the feature’s status to dropped and records the drop date.

Parameters:

• status (required) - The status name for the dropped feature (e.g., “Dropped”)
• dateDrop (required) - The date the feature was dropped (format: YYYY-MM-DD)
• dateBillTo (optional) - Override the calculated bill-to date. If not provided, the system calculates the appropriate date based on the feature type, drop date, and notice period
• statusReason (optional) - Text explanation for dropping the feature

Example:

curl -X POST https://example.com/backend/api/v1/features/123?action=drop \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Dropped",
    "dateDrop": "2025-01-24",
    "statusReason": "Customer requested cancellation"
  }'

reinstate

Reinstate a previously dropped feature, returning it to active status.

Parameters:

• status (required) - The status name for the reinstated feature (e.g., “Active”)
• dateReinstate (required) - The date the feature is reinstated (format: YYYY-MM-DD)
• statusReason (optional) - Text explanation for reinstating the feature

Example:

curl -X POST https://example.com/backend/api/v1/features/123?action=reinstate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active",
    "dateReinstate": "2025-01-24"
  }'

suspend

Suspend a feature. This moves the feature to a suspended status. Recurring charges are suppressed while the feature is suspended, but usage charges still apply.

Parameters:

• status (required) - The status name for the suspended feature (e.g., “Suspended”)
• dateSuspend (optional) - The date the suspension takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for suspending the feature

Example:

curl -X POST https://example.com/backend/api/v1/features/123?action=suspend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Suspended",
    "dateSuspend": "2025-01-24"
  }'

unsuspend

Unsuspend a previously suspended feature. The platform back-fills any recurring charges that were missed during the suspension period.

Parameters:

• status (required) - The status name for the unsuspended feature (e.g., “Active”)
• dateUnsuspend (optional) - The date the unsuspension takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for unsuspending the feature

Example:

curl -X POST https://example.com/backend/api/v1/features/123?action=unsuspend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active",
    "dateUnsuspend": "2025-01-24"
  }'

makeNonBillable

Move a feature to a non-billable status. Automated billing runs skip the feature while it is non-billable, but manual invoices can still be raised. The feature’s active and suspended state is preserved.

Parameters:

• status (required) - The status name for the non-billable feature (e.g., “Active - Do Not Bill”)
• dateMakeNonBillable (optional) - The date the change takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for making the feature non-billable

Example:

curl -X POST https://example.com/backend/api/v1/features/123?action=makeNonBillable \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active - Do Not Bill",
    "dateMakeNonBillable": "2025-01-24"
  }'

makeBillable

Move a feature back to a billable status. The platform back-fills any recurring charges that were missed while the feature was non-billable. The feature’s active and suspended state is preserved.

Parameters:

• status (required) - The status name for the billable feature (e.g., “Active”)
• dateMakeBillable (optional) - The date the change takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for making the feature billable

Example:

curl -X POST https://example.com/backend/api/v1/features/123?action=makeBillable \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active",
    "dateMakeBillable": "2025-01-24"
  }'

changeRecurringCharge

Change the recurring charge amount and/or feature count on an active feature. The platform handles refunds, pro-rating, and new charge creation automatically.

Parameters:

• serviceCharge (optional) - The new recurring charge amount. Omit to keep the existing charge.
• featureCount (optional) - The new feature count. Omit to keep the existing count.
• dateFrom (optional) - The date the change takes effect (format: YYYY-MM-DD). Defaults to the next changeover date.
• chargeChangeMode (optional) - How existing charges are handled. One of:
  • replace (default) - Refunds or deletes charges from the effective date and adds new ones at the new rate.
  • add - Adds new charges from the effective date without removing or refunding existing ones. dateFrom is required and must be on or before the feature’s current due date. Use when a credit note is being raised outside the platform to cover the old charges.
  • delta - Keeps approved charges in place and adds adjustment rows for the net difference. Unapproved charges are updated in place. Only available when the Recurring Charge Adjustment and Recurring Charge Adjustment Refund transaction types are configured.

Example (replace mode):

curl -X POST https://example.com/backend/api/v1/features/123?action=changeRecurringCharge \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCharge": "60.00",
    "dateFrom": "2026-04-01"
  }'

Example (add mode):

curl -X POST https://example.com/backend/api/v1/features/123?action=changeRecurringCharge \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCharge": "60.00",
    "dateFrom": "2026-04-01",
    "chargeChangeMode": "add"
  }'

Example (delta mode):

curl -X POST https://example.com/backend/api/v1/features/123?action=changeRecurringCharge \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCharge": "60.00",
    "dateFrom": "2026-03-15",
    "chargeChangeMode": "delta"
  }'

Error Responses:

• 400201 - Invalid chargeChangeMode value. Must be replace, add, or delta.
• 400201 - add mode requires a dateFrom value on or before the feature’s current due date.
• 400201 - add mode cannot be used on a feature with no existing recurring charges.
• 400201 - delta mode unavailable. Recurring Charge Adjustment and Recurring Charge Adjustment Refund transaction types are not configured.
• 400502 - Action failed (for example, feature is not active).

For full details on how each mode works, see Changing Recurring Charges.

Response Format

Actions return the updated feature object in JSON format, using the same structure as GET requests.

Error Handling

If an action fails, the API will return an appropriate HTTP status code with error details:

{
    "error": "Invalid Action",
    "error_code": 400502,
    "hint": "The action was not performed"
}

Common error codes:

• 400501 - Action not recognised
• 400502 - Action failed to execute
• 400503 - Missing required parameters
• 403xxx - Permission denied

Fields