diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp index a66e0501d..590a5b819 100644 --- a/specification/attributes/attributes.mdpp +++ b/specification/attributes/attributes.mdpp @@ -1,8 +1,10 @@ !INCLUDE "attributes_overview.md",0 !INCLUDE "column_handling.md",1 +!INCLUDE "correction_handling.md",1 !INCLUDE "currency_format.md",1 !INCLUDE "data_generator_calculated_split_cost_allocation_handling.md",1 !INCLUDE "datetime_format.md",1 +!INCLUDE "delivery_handling.md",1 !INCLUDE "discount_handling.md",1 !INCLUDE "json_object_format.md",1 !INCLUDE "invoice_handling.md",1 diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md new file mode 100644 index 000000000..969b0a573 --- /dev/null +++ b/specification/attributes/correction_handling.md @@ -0,0 +1,99 @@ +# Correction Handling + +## Overview + +The Correction Handling attribute defines how [*corrections*](#glossary:correction) to a previously delivered FOCUS [*dataset artifact*](#glossary:dataset-artifact) are represented in a subsequently delivered *dataset artifact*. + +Corrections may include some combination of added, updated, or removed *rows*. Corrections may address a variety of operational or technical causes, such as refunds, late-arriving data, rounding errors, delivery errors, and other post-processing adjustments. + +Accurate correction handling is essential for a range of business-critical processes, including but not limited to: + +* Temporal accuracy - capturing both when the [*charge*](#glossary:charge) was incurred (reflected in [*charge period*](glossary:chargeperiod) columns, i.e., [Charge Period Start](#chargeperiodstart) and [Charge Period End](#chargeperiodend)) and when the correction was invoiced (reflected in [*billing period*](#glossary:billing-period) columns, i.e., [Billing Period Start](#billingperiodstart) and [Billing Period End](#billingperiodend)). +* Financial and legal integrity - ensuring that data presented on [*issued invoices*](#glossary:issued-invoice) remains unchanged and aligned with associated underlying charges provided in the FOCUS dataset artifacts, while any related corrections do not compromise [*invoice reconciliation*](#glossary:invoice-reconciliation). +* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., [*Billing Account ID*](#billingaccountid), [*Sub Account ID*](#subaccountid), [*SKU ID*](#skuid), [*SKU Price ID*](#skupriceid), [*Resource ID*](#resourceid)) to ensure accurate downstream processing. +* Auditability - tracing the full lifecycle of a *charge* from the original record through all subsequent corrections. + +### Correction Styles + +FOCUS supports three styles for correcting original records: + +| Correction Style | Delivery Mechanism | Correction Style Description | +| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | +| Replacement | Overwrite | Original records are ignored and replaced by correction records. | +| Delta | Append | Original records are preserved and modified by correction records. | +| Ledger | Append | Original records are preserved and decremented/incremented by correction records. | + +For more information on delivery mechanisms for *dataset artifacts*, see the [Delivery Handling attribute](#deliveryhandling). + +#### Replacement Corrections + +In the Replacement correction style, a given *dataset artifact* uses the Overwrite delivery mechanism to provide a complete snapshot of data for a *billing period*, based on the data available at the time of delivery. + +Any given *dataset artifact* completely replaces all previous *dataset artifacts* to reflect updates, additions, or omissions relative to the previous snapshot. Therefore, the practitioner only needs to reference the most recent *dataset artifact* for a given *billing period* in order to tell a complete story of *charges*; all previous dataset artifacts for that *billing period* are considered obsolete and can be safely ignored. + +Given that changes are not presented as separate entries, this style lacks inherent auditability. + +#### Delta Corrections + +In the Delta correction style, a given *dataset artifact* uses the Append delivery mechanism to add records that revise or supplement previous *dataset artifacts* within a *billing period*. + +In some cases, the correction consists of a new record representing a previously omitted cost. Explicit reversal is not commonly performed, but may be used if the correction itself represents a reversal. + +Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. Therefore, the practitioner must combine all *dataset artifacts* for a given *billing period* in order to tell a complete story of *charges*. + +Given that only net changes are presented, this style offers limited inherent auditability. + +#### Ledger Corrections + +In the Ledger correction style, a given *dataset artifact* uses the Append delivery mechanism in combination with a double-entry bookkeeping method of decrements and increments to represent changes within a *billing period*. Depending on the nature of the correction, either or both of the following steps may be required: (1) reversal of the original record using a charge in which cost- and quantity-related columns carry values with the opposite sign, while all other columns match the original; and (2) a new record with corrected values. + +Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. Therefore, the practitioner must combine all *dataset artifacts* for a given *billing period* in order to tell a complete story of *charges*. + +Given that the entire change history is presented, this style offers full inherent auditability. + +### Corrections to Issued Charges + +A charge is considered issued when it is associated with an [*issued invoice*](#glossary:issued-invoice). + +While corrections to the [*issued charges*](#glossary:issued-charge) (including updates, additions, or omissions) may be permitted, they must not compromise the integrity of the associated *issued invoice*. Only corrections that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior *invoice reconciliation* and undermine the invoice's financial validity. + +Corrections to the underlying *issued charges* that do not impact data presented on the associated *issued invoice* are allowed. However, although these corrections do not affect *invoice reconciliation*, they can still result in loss of auditability and traceability, which in turn complicates modifications and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such corrections are not preferred and should only be applied when explicitly requested by the end-user. + +### Corrections to Closed Billing Periods + +A billing period is considered closed when all expected invoices for that timeframe have been issued. + +Any necessary corrections to a previously *closed billing period* that require issuing additional invoices are associated with a subsequent *open billing period*, with the charge period indicating when the cost was incurred. This approach establishes a clear temporal boundary between billing cycles, preserving the historical financial accuracy and integrity of closed billing periods while enabling transparent and auditable tracking of corrections in future periods. + +## Attribute ID + +CorrectionHandling + +## Attribute Name + +Correction Handling + +## Description + +Defines how *corrections* to a previously delivered FOCUS *dataset artifact* are represented in a subsequently delivered *dataset artifact*. + +## Requirements + +All corrections adhere to the following requirements: + +* The correction style(s) used to correct FOCUS *dataset artifacts* MUST be documented by the data generator. +* Correction MUST NOT introduce a discrepancy between an *issued invoice* and its associated FOCUS *dataset artifacts*. +* Correction to a previously *closed billing period* that requires issuing additional invoices MUST result in additional charge(s) associated with a subsequent *open billing period*, with the charge period indicating when the cost was incurred. +* Correction delivered using the Append delivery mechanism adheres to the following additional requirements: + * Correction MUST include exclusively additional charges. + * Correction MUST NOT include updates or omissions of previously delivered charges. + +## Exceptions + +* Exceptions to the restrictions on *issued charges*, *issued invoices*, and *closed billing periods* and MAY apply in the following cases: + * Upon explicit request from the end-user (subject to validation and approval processes). + * Due to technical issues encountered during or after invoice issuance or billing period closure. + +## Introduced (version) + +1.3 diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md new file mode 100644 index 000000000..dc6bad38a --- /dev/null +++ b/specification/attributes/delivery_handling.md @@ -0,0 +1,64 @@ +# Delivery Handling + +## Overview + +The Delivery Handling attribute defines how a data generator delivers a *dataset artifact* to a customer. + +### Delivery Mechanisms + +FOCUS supports two delivery mechanisms: + +* Overwrite. Existing rows are replaced. +* Append. Existing rows are preserved. + +These mechanisms are not mutually exclusive, and hybrid implementations are common, allowing data generators to meet specific technical and auditability requirements. + +For more information on corrections, see the [Correction Handling attribute](*correctionhandling). + +#### Overwrite Delivery + +In the Overwrite delivery mechanism, each *dataset artifact* provides a complete snapshot of data for a given [*billing period*](#glossary:billing-period), based on the data available at the time of delivery. Subsequent *dataset artifacts* typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism provides delivery simplicity, but it lacks inherent auditability. + +Subsequent *dataset artifacts* using the Overwrite mechanism may include the following: + +* Unchanged records are carried over. +* Updated records overwrite previous values. +* Additional records supplement previously delivered data. +* Omitted records are removed if no longer applicable. + +#### Append Delivery + +In the Append delivery mechanism, a subsequent *dataset artifact* appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. + +Subsequent *dataset artifacts* using the Append mechanism may include the following: + +* Unchanged recorded are not included. +* Updated records are recorded as new entries, representing the difference. +* Additional records supplement previously delivered data. +* Omitted records are recorded as new entries, representing the reversal. + +## Attribute ID + +DeliveryHandling + +## Attribute Name + +Delivery Handling + +## Description + +Defines how a data generator delivers a *dataset artifact* to a customer. + +## Requirements + +The delivery of a *dataset artifact* adheres to the following requirements: + +* The delivery mechanism(s) used to deliver FOCUS *dataset artifacts* MUST be documented by the data generator. + +## Exceptions + +None + +## Introduced (version) + +1.3 diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index f3ef2ce79..a8e1c4257 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -1,8 +1,39 @@ # Invoice Handling -FinOps practitioners must be able to reconcile FOCUS datasets with the corresponding invoices and usage statements they receive from [*Invoice Issuers*](#glossary:InvoiceIssuer). In practice, this means ensuring that all monetary [*charges*](#glossary:charge) that appear on an invoice or usage statement — including those not tied to metered usage — are represented in the [*FOCUS dataset*](#glossary:FOCUS-dataset). Without this alignment, it becomes difficult to perform accurate invoice reconciliation, financial reporting, and chargeback. +## Overview -This attribute introduces requirements for how charges such as usage, taxes, credits, refunds, etc, inclusive of support, training, and marketplace transactions, and any other type of charge should be captured and categorized. It also defines expectations around the completeness and consistency of invoice-level totals within the dataset, enabling FOCUS datasets to be used in a system of record for all invoiced costs. +The Invoice Handling attribute defines how a [*FOCUS dataset*](#glossary:FOCUS-dataset) should reflect details for the information presented on an [*invoice*](#glossary:invoice). + +This attribute introduces requirements for how monetary [*charges*](#glossary:charge) such as usage, taxes, credits, refunds, etc, inclusive of support, training, and marketplace transactions, and any other type of charge should be captured and categorized. It also defines expectations around the completeness and consistency of invoice-level totals within a FOCUS dataset, enabling FOCUS [*dataset artifacts*](#glossary:dataset-artifact) to be used in a system of record for all invoiced costs. + +FinOps practitioners must be able to reconcile *FOCUS datasets* with the corresponding invoices and usage statements they receive from [*invoice issuers*](#invoiceissuername). In practice, this means ensuring that all *charges* that appear on an invoice or usage statement, including those not tied to metered usage, are represented in a *FOCUS dataset*. Without this alignment, it becomes difficult to perform accurate [*invoice reconciliation*](#glossary:invoice-reconciliation), financial reporting, and chargeback. + +### Invoice Reconciliation and Issuance + +Prior to [*invoice issuance*](#glossary:issued-invoice), the invoice must undergo a reconciliation process. In this process, the *invoice issuer* ensures that the aggregated cost and usage information presented on the *invoice* matches the detailed cost and usage *charges* presented in a *FOCUS dataset*. + +At the conclusion of this process, the total monetary value presented on an invoice must match the total monetary value presented in the [Billed Cost](#billedcost) metric of a FOCUS dataset. Further, the detail presented on an invoice must match the values of Billed Cost when aggregated by the related combination of the following FOCUS dataset dimensions: + +* [Billing Account ID](#billingaccountid) +* [Billing Currency](#billingcurrency) +* [Billing Period Start](#billingperiodstart) +* [Billing Period End](#billingperiodend) +* [Invoice ID](#invoiceid) +* [Invoice Issuer Name](#invoiceissuername) + +Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions. + +Once an invoice is issued, it becomes an authoritative financial document, and the information it contains is expected not to change. [*Corrections*](#glossary:correction) to *issued charges* (including updates, additions, or omissions) may be permitted under certain conditions. However, such corrections must not compromise the integrity of the associated *issued invoice*. For more information on *corrections* to *issued charges*, refer to the [Correction Handling attribute](#correctionhandling). + +This information then allows FinOps practitioners to perform their own *invoice reconciliation* process, in order to ensure that the costs reflected on an invoice are commensurate with the usage they have observed. + +### Open and Closed Billing Periods + +While a billing period is open, one or more FOCUS dataset artifacts may be generated to represent that timeframe. At some point, the billing period will be closed. + +A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all expected invoices have been successfully issued by an invoice issuer. Once a billing period is financially closed, no additional invoices are expected to be associated with that timeframe. + +The ability to determine whether a billing period is "open" or "closed" is typically documented by the invoice issuer and made accessible to customers. There is typically a documented date and time by which all FOCUS dataset artifacts associated with a previous billing period will be generated, and no further artifacts will be expected. At that time, the data presented in the FOCUS dataset artifacts associated with a closed billing period is considered final, though corrections can be made in subsequent billing periods. For information on *corrections* to *closed billing periods*, refer to the [Correction Handling attribute](#correctionhandling). ## Attribute ID @@ -14,12 +45,18 @@ Invoice Handling ## Description -Indicates how invoice-level *charges*, including those not directly tied to usage, should be represented in a FOCUS Cost and Usage dataset. +Defines how a *FOCUS dataset* should reflect details for the information presented on an *invoice*. ## Requirements -* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the *FOCUS dataset*. -* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, data generators MUST include provider-defined columns (e.g., x_ChargeSubType) to capture the non-FOCUS-defined details needed to support invoice *charges* reconciliation using the *FOCUS dataset*. +* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in one or more FOCUS Cost and Usage *dataset artifacts*. +* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, data generators MUST include custom columns (e.g., x_ChargeSubType) to capture the non-FOCUS-defined details needed to support invoice *charges* reconciliation using the FOCUS Cost and Usage *dataset artifacts*. +* *Invoice reconciliation* adheres to the following additional requirements: + * Invoice issuer MUST perform *Invoice reconciliation* between an *invoice* and its associated FOCUS *dataset artifacts* before issuing the invoice. + * *Invoice reconciliation* process MUST include (but is not limited to) the following metric and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuerName, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. + * Invoice issuer MUST document which FOCUS dataset columns are included in the *invoice reconciliation* process. +* The data generator MUST notify the customer if the contents of a *dataset artifact* associated with an *issued invoice* are altered after final delivery. +* The *billing period* (i.e., the timeframe from BillingPeriodStart to BillingPeriodEnd) of a charge MUST match the *billing period* of its associated [*InvoiceId*](#invoiceid). ## Exceptions @@ -28,8 +65,6 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * SLA credit details when the credit is already applied to the charged amount * If such informational items are excluded, data generators MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. -None - ## Introduced (version) 1.3 diff --git a/specification/datasets/cost_and_usage/columns/chargeclass.md b/specification/datasets/cost_and_usage/columns/chargeclass.md index 7cd7fde95..4bacec85d 100644 --- a/specification/datasets/cost_and_usage/columns/chargeclass.md +++ b/specification/datasets/cost_and_usage/columns/chargeclass.md @@ -1,6 +1,6 @@ # Charge Class -Charge Class indicates whether the [*row*](#glossary:row) represents a correction to a previously invoiced [*billing period*](#glossary:billing-period). Charge Class is commonly used to differentiate [*corrections](#glossary:correction) from regularly incurred [*charges*](#glossary:charge). +Charge Class indicates whether a [*charge*](#glossary:charge) represents a [*correction](#glossary:correction) to a previously [*closed billing period*](#glossary:closed-billing-period). Charge Class is commonly used to differentiate such corrections from all other charges, including both regularly incurred *charges* and *corrections* to [*open billing periods*](#glossary:open-billing-period). ## Requirements @@ -9,8 +9,8 @@ ChargeClass adheres to the following requirements: * ChargeClass MUST be present in a Cost and Usage [*FOCUS dataset*](#glossary:FOCUS-dataset). * ChargeClass MUST be of type String. * ChargeClass nullability is defined as follows: - * ChargeClass MUST be null when the *row* does not represent a correction or when it represents a correction within the current *billing period*. - * ChargeClass MUST NOT be null when the *row* represents a correction to a previously invoiced *billing period*. + * ChargeClass MUST be null when the *charge* does not represent a correction to a previously *closed billing period*. + * ChargeClass MUST NOT be null when the *charge* represents a correction to a previously *closed billing period*. * ChargeClass MUST be "Correction" when ChargeClass is not null. ## Column ID @@ -23,7 +23,7 @@ Charge Class ## Description -Indicates whether the *row* represents a correction to a previously invoiced *billing period*. +Indicates whether a *charge* represents a correction to a previously *closed billing period*. ## Content Constraints @@ -39,7 +39,7 @@ Allowed values: | Value | Description | | :--------- | :----------------------------------------------------------------------------------------------| -| Correction | Correction to a previously invoiced *billing period* (e.g., refunds and credit modifications). | +| Correction | Correction to a previously *closed billing period* (e.g., refunds and credit modifications). | ## Introduced (version) diff --git a/specification/datasets/cost_and_usage/dataset.md b/specification/datasets/cost_and_usage/dataset.md index 55c66a854..32ce6db48 100644 --- a/specification/datasets/cost_and_usage/dataset.md +++ b/specification/datasets/cost_and_usage/dataset.md @@ -91,6 +91,8 @@ CostAndUsage adheres to the following requirements: * CostAndUsage MUST be present. * CostAndUsage MUST conform to [ColumnHandling](#columnhandling) requirements. +* CostAndUsage MUST conform to [CorrectionHandling](#correctionhandling) requirements. +* CostAndUsage MUST conform to [DeliveryHandling](#deliveryhandling) requirements. * CostAndUsage MUST conform to [NullHandling](#nullhandling) requirements. * CostAndUsage MUST conform to [DiscountHandling](#discounthandling) requirements. * CostAndUsage MUST conform to [InvoiceHandling](#invoicehandling) requirements. diff --git a/specification/glossary.md b/specification/glossary.md index 08c85e9fe..398e0d333 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -52,6 +52,10 @@ A row in a FOCUS-compatible cost and usage dataset. The time window for which a charge is effective, inclusive of the start date and exclusive of the end date. The charge period for continuous usage should match the time granularity of the dataset (e.g., 1 hour for hourly, 1 day for daily). The charge period for a non-usage charge with time boundaries should match the period of eligibility. +Closed Billing Period + +A [*billing period*](glossary:billing-period) that has been financially closed following the successful issuance of all planned invoices by the designated Invoice Issuer for that period. Upon assigning the "closed" status, the responsible Invoice Issuer entity confirms that no additional invoices will be associated with this period. Exceptionally, additional invoices may be associated with a closed billing period if explicitly requested by the end-user. + Cloud Service Provider (CSP) A company or organization that provides remote access to computing resources, infrastructure, or applications for a fee. @@ -82,7 +86,9 @@ The agreed-upon unit price for a single [Pricing Unit](#pricingunit) of the asso Correction -A charge to correct cost or usage data in a previously invoiced [*billing period*](#glossary:billing-period). +Any modification (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period). A correction may consist of multiple simultaneous modifications, each representing an update or omission of a previously delivered charge, or the addition of a new charge, collectively forming the correction. + +The term "Correction" (capitalized) refers specifically to an allowed value in the [Charge Class](#chargeclass) column, designating charges used to correct cost or usage data from a previously closed billing period. In contrast, the broader concept of "corrections" (lowercase) includes all types of modifications, regardless of the [*billing period*](#glossary:billing-period) status. Credit @@ -100,6 +106,10 @@ A specific implementation of a [*FOCUS dataset*](#glossary:FOCUS-dataset) provid A physical representation of a specific [*dataset instance*](#glossary:dataset-instance) delivered by a [data generator](#datagenerator). +Dataset Artifact + +A physical representation of a [*FOCUS dataset*](#glossary:FOCUS-dataset) delivered by a data generator. + Dimension A specification-defined categorical attribute that provides context or categorization to billing data. @@ -132,10 +142,26 @@ The collection of datasets are designed to provide billing insight, additional c A Date/Time Format value that is contained within the beginning bound of a time period. +Invoice + +A document that summarizes the charges for resources or services consumed by a customer. + +Invoice Reconciliation + +The process of ensuring that the aggregated cost and usage information presented on an [*invoice*](#glossary:invoice) matches the detailed cost and usage [*charges*](#glossary:charge) presented in a [*FOCUS dataset*](#glossary:FOCUS-dataset). + Interruptible A category of compute resources that can be paused or terminated by the CSP within certain criteria, often advertised at reduced unit pricing when compared to the equivalent non-interruptible resource. +Issued Invoice + +An invoice that has been formally generated and released by the designated invoice issuer. Prior to issuance, the invoice must be reconciled with the underlying [*charges*](#glossary:charge) provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and the financial data presented on the invoice must not be altered. While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. + +Issued Charge + +A [*charge*](#glossary:charge) associated with an [*issued invoice*](glossary:issued-invoice). + JSON A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. @@ -164,6 +190,10 @@ A contractual agreement where a customer commits to specific spend or usage goal A service that is available and provided immediately or as needed, without requiring a pre-scheduled appointment or prior arrangement. In cloud computing, virtual machines can be created and terminated as needed, i.e., on demand. +Open Billing Period + +A [*billing period*](glossary:billing-period) that has not yet been financially closed, regardless of whether it refers to the current or a past timeframe. The "open" status indicates that billing activities are ongoing and the period remains subject to updates until formally closed. + Origin Charge The [charge](#glossary:charge) that existed prior to an operation. This is used in the context of [Data Generator-Calculated Split Cost Allocation](#datagenerator-calculatedsplitcostallocation) to identify the charge that existed prior to the application of Data Generator-Calculated Split Cost Allocation to produce [allocated charges](#glossary:allocated-charge). diff --git a/supporting_content/attributes/correction_handling.md b/supporting_content/attributes/correction_handling.md new file mode 100644 index 000000000..2d5c2337e --- /dev/null +++ b/supporting_content/attributes/correction_handling.md @@ -0,0 +1,66 @@ +# Correction handling + +## Prevent Replacement After Invoice Finalization (and Billing Period Closure) + +***Note:*** *See S-1: Itemized Correction Scenarios with Cost Calculation Integrity Respected - S-1.1 and S-1.2 in particular* + +We should prevent the use of the Replacement provisioning style once an invoice has been finalized and the corresponding billing period closed. + +Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections - and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: + +- A finalized invoice is considered legally issued and immutable. +- The associated billing period is closed, prohibiting any modifications or overwriting of previously delivered records. + +Therefore, only append-only provisioning styles (such as ledger-style increments/decrements or accounting-style reversals followed by corrected entries) should be permitted for handling Post-Invoice Finalization Corrections. + +**Exceptions:** + +- Contributors are encouraged to document any exception to the general rule. + +- Should we allow restating in cases where corrections apply to dimensions that were not included in the original invoice? + *Note: Personally, I would prefer not to allow this.* +- Technical issues mentioned by Riley. +- Explicitly specified by the end-user. + +### Normative Requirements for Post-Invoice Finalization Corrections + +> Shawn has added numbers to the statements that would become normative requirements in the attribute + +The following applies to all corrections to a previously closed billing period, i.e., correction charge records provisioned after invoice finalization and billing period closure, but which pertain to activity that occurred during that already invoiced and closed period: + +- **Legal and Procedural Perspective:** + - <<1>> The invoice is considered legally issued and immutable. + - The billing period is considered closed, thereby prohibiting any modifications to or overwriting of the originally invoiced records. + +- **Provisioning perspective**: `x_ExportDateTime = T2` (i.e., the date it became available to the consumer) + +- **Operational Perspective**: All Correction records (Increments and Decrements in case of the Ledger style, Negations and Corrected records in case of Accounting style) pertain to activity that occurred in **May**, so in case of Usage records <<2>> `ChargePeriodStart`/`ChargePeriodEnd` **must reflect the actual usage period** (e.g., `ChargePeriodStart = 2025-05-01`) + +- **Financial Perspective**: The original invoice (e.g., `INV-20250501-20250601`) has already been finalized (issued and sent e.g., as PDF). The May billing period is **considered closed** therefore + - <<3>> `BillingPeriodStart`/`BillingPeriodEnd` **must be equal to or later than** the first **open** billing period (i.e., June 2025 or later) + - <<4>> `InvoiceId` must not match the original invoice (e.g., `INV-20250501-20250601`). + +- **Charge Class:** <<5>> ChargeClass must be set to "Correction". + +## Cost and Usage data Provisioning Styles + +Data Generators typically use two main provisioning styles/mechanisms when delivering cost and usage data: + +- **Replacement:** Overwrites previously delivered records with updated ones. This approach ensures data accuracy by reflecting corrections directly in place. + +- **Append-only:** Delivers only new records without modifying previously sent data. This approach can be further divided into two subtypes: + - **Ledger-style:** Adds incremental (or decremental) records over time. Corrections are reflected as additional entries where the cost or quantity metrics are adjusted (+/-), while all other dimensions remain identical to the original record. This supports an append-only model but offers limited auditability, as there is typically no explicit reversal. + - **Accounting-style:** Tracks changes explicitly via negative (reversal) entries followed by corrected records. This ensures full auditability and provides a clear historical trail of adjustments. + +## Finalized Invoice and Closed Billing Period + +> See [FR #Add invoice-level correction handling rules](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/issues/1013) + +While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **"closed"** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. + +To address these **gaps** in this scenario, we assume the following: + +- Data Generator (Providers) finalize invoices at some point, marking them as ready for invoice reconciliation. +- A billing period is considered closed once all invoices for that period are finalized. + +***Note:** These information are assumed to be provided not within the cost and usage dataset itself, but in separate, adjacent datasets (e.g., invoice-related datasets). diff --git a/supporting_content/datasets/cost_and_usage/columns/chargeclass.md b/supporting_content/datasets/cost_and_usage/columns/chargeclass.md index 4297801d7..6e2261941 100644 --- a/supporting_content/datasets/cost_and_usage/columns/chargeclass.md +++ b/supporting_content/datasets/cost_and_usage/columns/chargeclass.md @@ -6,7 +6,7 @@ * Initially, ChargeClass was defined as a non-nullable column with two allowed values: Regular and Correction. * Various alternative names for Regular charges were discussed, including Regular, Standard, Original, and Direct. -* Eventually, the team decided on a nullable column approach, where Correction is the sole allowed value, representing corrections to a previously invoiced billing period. +* Eventually, the team decided on a nullable column approach, where Correction is the sole allowed value, representing corrections to a previously closed billing period. ### Impacts of 1.0 ChargeCategory and ChargeClass cleanup