​
Service Adjustments

Service Adjustments provide a comprehensive audit trail of all modifications made to services within the Ping Proxies system. They capture detailed information about what changed, who made the change, when it occurred, and the specific values before and after the adjustment.

​
What Are Service Adjustments?

A Service Adjustment is a record created every time a service is modified in any way. These adjustments serve several important purposes:
  • Audit Trail: Maintain a complete history of all service changes
  • Accountability: Track who made each change (system, administrator, or customer)
  • Transparency: Document exact values before and after modifications
  • Troubleshooting: Help diagnose issues by reviewing the chronology of changes
  • Billing Records: Provide references for invoices generated due to adjustments

​
Key Components of a Service Adjustment

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

​
Identifiers and Metadata

FieldDescription
service_adjustment_idUnique identifier for the adjustment record
service_idID of the service that was modified
invoice_idID of any invoice generated by this adjustment
service_adjustment_creation_datetimeWhen the adjustment was created
service_adjustment_last_update_datetimeWhen the adjustment was last updated

​
Type and Status

FieldDescription
service_adjustment_typeThe type of adjustment (see types below)
service_adjustment_statusCurrent status: pending, complete, or failed

​
Source Tracking

FieldDescription
service_adjustment_is_administratorWhether an administrator made the change
service_adjustment_is_automaticWhether the system made the change automatically
service_adjustment_is_customerWhether a customer made the change

​
Change Documentation

FieldDescription
service_adjustment_preJSON snapshot of service state before the adjustment
service_adjustment_postJSON snapshot of service state after the adjustment
service_adjustment_evalSide-by-side comparison of changed values

​
Service Adjustment Types

Service adjustments can be of various types, each representing a different kind of modification:
TypeDescription
ingestionInitial creation of a service
fulfillmentAllocation of proxies to a service
remove_proxyRemoval of proxies from a service
additional_fulfillmentAdding more proxies to an existing service
updateGeneral update to service attributes
proxy_replacementReplacing proxies with new ones
extensionExtending the service period
top_upAdding additional bandwidth to a residential service
top_up_and_extensionBoth extending service and adding bandwidth
cancelCancellation 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.

​
Practical Uses of Service Adjustments

Service adjustments offer valuable data for various stakeholders:
  • For Customers: Understand when and why services changed
  • For Resellers: Track changes to client services
  • For Developers: Debug integration issues by reviewing the chronology of changes
  • For Support Teams: Quickly identify what changed when troubleshooting

​
Reading an Adjustment: Example Scenario

Let’s walk through a practical example of reading a service adjustment: A customer sees that their service was recently modified. They can examine the adjustment to find:
  1. What changed: By looking at the service_adjustment_eval field
  2. When it changed: From the service_adjustment_creation_datetime
  3. Who made the change: By checking the source flags (administrator, automatic, or customer)
  4. Why it changed: By understanding the service_adjustment_type
  5. Complete before/after state: By examining the service_adjustment_pre and service_adjustment_post fields
This comprehensive information helps eliminate guesswork and provides a clear picture of the service’s history.

​
How Adjustments Connect to Other Objects

Service adjustments are connected to several other objects in the Ping Proxies system:
  • Services: Each adjustment belongs to a specific service
  • Invoices: Adjustments that involve billing changes will reference the corresponding invoice
  • Proxy Replacements: When proxies are replaced, the adjustment contains details of each replacement
  • Residential Ledger: For residential services, bandwidth adjustments may be linked to ledger entries