Documentation Index
Fetch the complete documentation index at: https://documentation.byteful.com/llms.txt
Use this file to discover all available pages before exploring further.
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:
| 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]
}
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"
}
]
}
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
