> ## 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 Explained

> Understanding the service adjustment audit trail in the Byteful API

# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

1. **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

2. **Administrative Actions**:
   * Support staff making changes to services
   * Manual adjustments by the Byteful team

3. **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