Service Adjustments

Service Adjustments provide an audit trail of all service modifications, tracking what changed, who made the change, when it occurred, and the values before and after the adjustment.

Key Components of a Service Adjustment

Each Service Adjustment contains detailed information to fully document a change:

Identifiers and Metadata

Field	Description
`service_adjustment_id`	Unique identifier for the adjustment record
`service_id`	ID of the service that was modified
`invoice_id`	ID of any invoice generated by this adjustment
`service_adjustment_creation_datetime`	When the adjustment was created
`service_adjustment_last_update_datetime`	When the adjustment was last updated

Type and Status

Field	Description
`service_adjustment_type`	The type of adjustment (see types below)
`service_adjustment_status`	Current status: `pending`, `complete`, or `failed`

Source Tracking

Field	Description
`service_adjustment_is_administrator`	Whether an administrator made the change
`service_adjustment_is_automatic`	Whether the system made the change automatically
`service_adjustment_is_customer`	Whether a customer made the change

Change Documentation

Field	Description
`service_adjustment_pre`	JSON snapshot of service state before the adjustment
`service_adjustment_post`	JSON snapshot of service state after the adjustment
`service_adjustment_eval`	Side-by-side comparison of changed values

Service Adjustment Types

Service adjustments can be of various types, each representing a different kind of modification:

Type	Description
`ingestion`	Initial creation of a service
`fulfillment`	Allocation of proxies to a service
`remove_proxy`	Removal of proxies from a service
`additional_fulfillment`	Adding more proxies to an existing service
`update`	General update to service attributes
`proxy_replacement`	Replacing proxies with new ones
`extension`	Extending the service period
`top_up`	Adding additional data to a residential or mobile service
`top_up_and_extension`	Both extending service and adding data
`cancel`	Cancellation of a service

Understanding the Adjustment Evaluation

The service_adjustment_eval field is particularly useful as it provides a clear, side-by-side comparison of the changed values. This field contains an object where:

Each key represents a field that was changed
Each value is an array with two elements:
- The first element is the value before the change
- The second element is the value after the change

For example:

{
  "service_expiry_datetime": ["2023-09-14 18:30:00", "2024-09-14 18:30:00"],
  "service_quantity": [5, 10]
}

This evaluation shows that the service expiry was extended by one year and the quantity was increased from 5 to 10.

Special Adjustment Types

Proxy Replacements

For proxy_replacement adjustments, the object will include additional data in a proxy_replacements array, which contains records of each proxy that was replaced:

{
  "proxy_replacements": [
    {
      "proxy_replacement_id": 7018,
      "proxy_replacement_ip_address_ipv4": "107.225.73.142",
      "proxy_replacement_new_ip_address_ipv4": "107.225.74.89",
      "proxy_replacement_reason": "customer_request"
    }
  ]
}

This shows the old and new IP addresses, as well as the reason for the replacement.

Where Adjustments Come From

Service adjustments are created automatically in response to various events:

Customer Actions:
- Manually editing a service through the dashboard
- Making changes via the API
- Canceling a service
- Adding data to a residential or mobile service
Administrative Actions:
- Support staff making changes to services
- Manual adjustments by the Byteful team
Automated System Actions:
- Automatic fulfillment of newly purchased services
- Scheduled service renewals
- System-initiated proxy replacements
- Error recovery processes

Accessing Service Adjustments

Service adjustments can be accessed through the API using:

Retrieve by ID: To get details of a specific adjustment
Search: To find adjustments for a particular service or type

When retrieving a service adjustment with a proxy replacement, the response will include details of all replaced proxies to provide a complete picture of what changed.

How Adjustments Connect to Other Objects

Services: Each adjustment belongs to a specific service
Invoices: Adjustments that involve billing changes reference the corresponding invoice
Proxy Replacements: When proxies are replaced, the adjustment contains replacement details
Residential Ledger: For residential services, data adjustments may link to ledger entries
Mobile Ledger: For mobile services, data adjustments may link to ledger entries

Getting Started

API Basics

Core API Features

Core Objects

Explainers

Service Adjustments Explained

Service Adjustments

Key Components of a Service Adjustment

Identifiers and Metadata

Type and Status

Source Tracking

Change Documentation

Service Adjustment Types

Understanding the Adjustment Evaluation

Special Adjustment Types

Proxy Replacements

Where Adjustments Come From

Accessing Service Adjustments

How Adjustments Connect to Other Objects

​Service Adjustments

​Key Components of a Service Adjustment

​Identifiers and Metadata

​Type and Status

​Source Tracking

​Change Documentation

​Service Adjustment Types

​Understanding the Adjustment Evaluation

​Special Adjustment Types

​Proxy Replacements

​Where Adjustments Come From

​Accessing Service Adjustments

​How Adjustments Connect to Other Objects

Service Adjustments

Key Components of a Service Adjustment

Identifiers and Metadata

Type and Status

Source Tracking

Change Documentation

Service Adjustment Types

Understanding the Adjustment Evaluation

Special Adjustment Types

Proxy Replacements

Where Adjustments Come From

Accessing Service Adjustments

How Adjustments Connect to Other Objects