Service Adjustments Explained

Understanding the service adjustment audit trail in the Ping Proxies 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 bandwidth to a residential service
top_up_and_extension	Both extending service and adding bandwidth
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:

1. Customer Actions:

   • Manually editing a service through the dashboard
   • Making changes via the API
   • Canceling a service
   • Adding bandwidth to a residential service

2. Administrative Actions:

   • Support staff making changes to services
   • Manual adjustments by the Ping Proxies 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, bandwidth adjustments may link to ledger entries