Undo and Backout Activity

Situation 1—Price Correction

A pricing error was found after billing completed. This applies to two types of corrections:

• Usage price offer correction—The wrong rate or usage price plan was applied to your customers. All usage records must be discarded and re-rated under the corrected pricing.
• Commitment price offer correction—The commitment contract value (Quantity/Amount Commitment) was set incorrectly. Because the commitment value drives the true-up calculation, the entire billing batch must be reversed and re-run against the corrected contract.

Use Situation 1 when:

• A usage rate plan or price offer was incorrectly configured and has since been corrected.
• A customer's commitment contract value was wrong and has since been corrected.
• All usage records for the affected period must be discarded and re-rated under the corrected pricing or commitment value.

Complete the following steps before submitting the undo request:

Situation 2—Missed Usage or Wrong True-Up

Usage records were not processed before billing ran. As a result, the true-up amount (the end-of-period adjustment for commitment-based customers) was calculated incorrectly. Only the billing output needs to be reversed—the usage records are correct and do not need to be discarded.

Use Situation 2 when:

• Usage files or feeds were delayed and missed the billing window.
• The billing job ran but true-up values are wrong because not all usage was accounted for.
• You want to preserve existing usage and re-run billing with the complete set of usage records.

undoJobSchedule—Reverse a Billing Run

Type: Mutation

Submits an undo request for a completed billing run. The operation runs in the background and returns immediately with a tracking ID (<undoBatchId>).

Input Parameters

Response Fields

getUndoJobScheduleStatus—Check the Outcome

Type: Query

Retrieves the current status of a previously submitted undo request using the <undoBatchId> returned by undoJobSchedule.

Input Parameters

Response Fields

Step 1: Submit the Undo Request

The undo runs in the background. You receive an immediate response containing a <undoBatchId> and status PROCESSING.

Situation 1—Price correction (discard usage):

mutation {
  undoJobSchedule(undoJobScheduleInput: {
    billingDate: "2026-04-01 00:00:00"
    clientId: 1001
    discardUsage: true
    userId: "ops.admin"
  }) {
    undoBatchId
    status
    errorCode
    errorMessage
    clientId
  }
}

Situation 2—Missed usage or wrong true-up (keep usage):

mutation {
  undoJobSchedule(undoJobScheduleInput: {
    billingDate: "2026-04-01 00:00:00"
    clientId: 1001
    discardUsage: false
    userId: "ops.admin"
  }) {
    undoBatchId
    status
    errorCode
    errorMessage
    clientId
  }
}

Example successful response:

{
  "data": {
    "undoJobSchedule": {
      "undoBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "status": "PROCESSING",
      "errorCode": null,
      "errorMessage": null,
      "clientId": 1001
    }
  }
}

Step 2: Check the Status

Use the <undoBatchId> from Step 1 to poll for the result. The background process typically completes within a few seconds to a few minutes depending on data volume.

query {
  getUndoJobScheduleStatus(
    batchId: "a3f1c2d4-89ab-4c56-a012-b4567890cdef"
    clientId: 1001
  ) {
    undoBatchId
    status
    totalCount
    errorCode
    errorMessage
    clientId
  }
}

Example response—still running:

{
  "data": {
    "getUndoJobScheduleStatus": {
      "undoBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "status": "PROCESSING",
      "totalCount": 0,
      "errorCode": null,
      "errorMessage": null,
      "clientId": 1001
    }
  }
}

Example response—completed successfully:

{
  "data": {
    "getUndoJobScheduleStatus": {
      "undoBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "status": "COMPLETED",
      "totalCount": 842,
      "errorCode": null,
      "errorMessage": null,
      "clientId": 1001
    }
  }
}

Example response—failed:

{
  "data": {
    "getUndoJobScheduleStatus": {
      "undoBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "status": "ERROR",
      "totalCount": 0,
      "errorCode": "SYSTEM_ERROR",
      "errorMessage": "No billing batch found for the given billing date",
      "clientId": 1001
    }
  }
}

Step 3: Re-run Billing

Once the status is COMPLETED, the billing cycle for the given date has been fully reset. Re-trigger the billing job for that date through the normal job scheduling process.

Situation 1—File Processed in Error, Billing Has Not Yet Run

A usage file was ingested and rated that should not have been—for example, a duplicate file, a test file submitted to production, the wrong file for the wrong client, or a file with incorrect data. The billing cycle for the affected period has not yet completed.

Use Situation 1 when:

• A usage file was processed that should not have been ingested.
• Transactions from the file are contaminating accumulator, allowance, or balance buckets.
• Billing has not yet run for the affected billing period.
• You want to remove the file’s impact entirely so usage can be resubmitted correctly.

Situation 2—File Processed in Error and Billing Has Already Run

A usage file was ingested and rated incorrectly, and the billing cycle that covered that usage period has already completed. The incorrect usage records contributed to the true-up calculations for commitment-based customers, meaning the billing output is also affected.

Use Situation 2 when:

• A usage file was processed in error and the billing job for that period has already run.
• True-up billing amounts for commitment-based customers are incorrect because the bad usage was included.
• You need to reverse both the usage transactions and the completed billing cycle so billing can re-run against corrected usage.

backoutUsageFileTransactions—Reverse Usage File Transactions

Type: Mutation

Submits a backout request for one or more usage files. The operation runs in the background and returns immediately with a tracking ID (<backoutBatchId>).

Input Parameters

Response Fields

getUsageFileTxnsBackoutStatus—Check the Outcome

Type: Query

Retrieves the current status of a previously submitted backout request using the <backoutBatchId> returned by backoutUsageFileTransactions.

Input Parameters

Response Fields

Step 1: Submit the Backout Request

The backout runs in the background. You receive an immediate response containing a <backoutBatchId> and status PROCESSING.

Situation 1—File processed in error, billing not yet run (usage reversal only):

mutation {
  backoutUsageFileTransactions(input: {
    fileNames: "usage_file_001.csv,usage_file_002.csv"
    clientId: 1001
    userId: "ops.admin"
    undoBilling: false
  }) {
    backoutBatchId
    fileNames
    clientId
    status
    errorMessage
  }
}

Situation 2—File processed in error, billing has already run (full reversal including billing):

mutation {
  backoutUsageFileTransactions(input: {
    fileNames: "usage_file_001.csv,usage_file_002.csv"
    clientId: 1001
    userId: "ops.admin"
    undoBilling: true
  }) {
    backoutBatchId
    fileNames
    clientId
    status
    errorMessage
  }
}

Example successful response:

{
  "data": {
    "backoutUsageFileTransactions": {
      "backoutBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "fileNames": "usage_file_001.csv,usage_file_002.csv",
      "clientId": 1001,
      "status": "PROCESSING",
      "errorMessage": null
    }
  }
}

Step 2: Check the Status

Use the <backoutBatchId> from Step 1 to poll for the result. The background process typically completes within a few seconds to a few minutes depending on transaction volume.

query {
  getUsageFileTxnsBackoutStatus(
    backoutBatchId: "a3f1c2d4-89ab-4c56-a012-b4567890cdef"
    clientId: 1001
  ) {
    backoutBatchId
    fileNames
    clientId
    userId
    status
    transactionsDeleted
    cdrStatsDeleted
    createDate
    updateDate
  }
}

Example response—still running:

{
  "data": {
    "getUsageFileTxnsBackoutStatus": {
      "backoutBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "fileNames": "usage_file_001.csv,usage_file_002.csv",
      "clientId": 1001,
      "userId": "ops.admin",
      "status": "PROCESSING",
      "transactionsDeleted": 0,
      "cdrStatsDeleted": 0,
      "createDate": "2026-06-01 10:00:00.0",
      "updateDate": null
    }
  }
}

Example response—completed successfully:

{
  "data": {
    "getUsageFileTxnsBackoutStatus": {
      "backoutBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "fileNames": "usage_file_001.csv,usage_file_002.csv",
      "clientId": 1001,
      "userId": "ops.admin",
      "status": "COMPLETED",
      "transactionsDeleted": 4250,
      "cdrStatsDeleted": 2,
      "createDate": "2026-06-01 10:00:00.0",
      "updateDate": "2026-06-01 10:00:43.0"
    }
  }
}

Example response—failed:

{
  "data": {
    "getUsageFileTxnsBackoutStatus": {
      "backoutBatchId": "a3f1c2d4-89ab-4c56-a012-b4567890cdef",
      "fileNames": "usage_file_001.csv,usage_file_002.csv",
      "clientId": 1001,
      "userId": "ops.admin",
      "status": "ERROR",
      "transactionsDeleted": 0,
      "cdrStatsDeleted": 0,
      "createDate": "2026-06-01 10:00:00.0",
      "updateDate": "2026-06-01 10:00:05.0"
    }
  }
}

Step 3: Complete Post-Backout Actions

Once the status is COMPLETED, the file’s impact has been fully reversed. Next steps depend on the situation:

Situation 1 (usage reversal only): Correct or replace the usage file and resubmit it through normal usage processing. All CDR stats were deleted, so the system accepts the file as a fresh submission.

Situation 2 (full reversal including billing):

1. Process the corrected usage file through normal usage processing.
2. Re-trigger the billing job for the same billing date through the normal job scheduling process. The billing cycle pointers have been rolled back so billing will re-run for the correct period.

clearJobSchedule—Clear Job Schedule Records for a Date

Type: Mutation

Deletes all job schedule records—including work items and job schedule list entries—for the specified schedule date and client. This operation is synchronous and returns the final status immediately.

Input Parameters

Response Fields

Step 1: Submit the Clear Job Schedule Request

This call runs synchronously. The result—COMPLETED or ERROR—is returned in the same response. No polling is required.

mutation {
  clearJobSchedule(
    clientId: 1001
    scheduleDate: "2026-04-01 00:00:00"
  ) {
    status
    errorCode
    errorMessage
    clientId
  }
}

Example response—completed successfully:

{
  "data": {
    "clearJobSchedule": {
      "status": "COMPLETED",
      "errorCode": null,
      "errorMessage": null,
      "clientId": 1001
    }
  }
}

Example response—failed:

{
  "data": {
    "clearJobSchedule": {
      "status": "ERROR",
      "errorCode": "SYSTEM_ERROR",
      "errorMessage": "clientid is required",
      "clientId": 1001
    }
  }
}

Step 2: Re-trigger the Billing Job

Once you receive COMPLETED, re-trigger the billing job for that date through the normal job scheduling process. The new accounts will be included in the fresh run.