Guides

Overwriting or Appending Same Day Usage

Suggest Edits

Understanding how Pax8 processes usage data, especially when multiple lines are posted for the same subscription on the same day, is key to accurate billing. This page details the default behaviors for same-day usage posting and how you can control them using theoverwriteSameDayUsage parameter. Please note that the default behavior for the system is to set overwriteSameDayUsage to true.

Same-Day Posts and summaryKey

The summaryKey is crucial for differentiating usage items when reported on the same day.

  • Different summaryKeys on the Same Day:

    • If you post multiple usage lines on the same day for the same subscription but with different summaryKeys, Pax8 will keep and process all of these lines as distinct usage items. For example, if on 2024-08-01 you post:
      • summaryKey: "users", quantity: 10
      • summaryKey: "storageGB", quantity: 50
        Both lines will be retained as they represent different billable components for 2024-08-01.

  • Same summaryKey, Same Day:

    • When you post usage multiple times on the same day for the same Subscription and the exact same summaryKey, the default behavior is to delete and replace any pre-existing usage lines for that identical usageDate and summaryKey.

Controlling Same-Day Overwrites with overwriteSameDayUsage

The overwriteSameDayUsage flag is an optional boolean query parameter available on the /usage/lines and /usage/aggregate-lines endpoints. It allows you to define how the system should handle new usage lines when there are existing ones for the same summaryKey that were posted earlier in the same day.

Default Behavior: Overwriting Usage (overwriteSameDayUsage=true or parameter omitted)

By default, if you do not include the overwriteSameDayUsage parameter in your request, or if you explicitly set it to true, any new usage lines posted will delete and replace any pre-existing usage lines that were posted on the same day for that identical summaryKey.

  • Scenario: You need to correct a usage quantity reported earlier on the same day, or you are simply sending the latest snapshot of usage for that day.
  • Example:
    1. At 10:00 AM on 2024-08-01, you post: 
      POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08
[
    {
        "summaryKey": "active-users",
        "summaryDisplayName": "users",
        "quantity": 100,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]
    2. At 03:00 PM on the same day (2024-08-01), you realize the correct count is 105 and post again (either omitting overwriteSameDayUsage or setting it to true): 
      POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08&overwriteSameDayUsage=true
[
    {
        "summaryKey": "active-users",
        "summaryDisplayName": "users",
        "quantity": 105,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]
    • Result: The initial usage line (quantity 100) from 10:00 AM is deleted. The system retains only the second usage line (quantity 105) for summaryKey: "active-users" on usageDate: "2024-08-01".

Appending Usage (overwriteSameDayUsage=false)

If you wish to add new usage lines on the same day without deleting existing ones for the same summaryKey, you must set the overwriteSameDayUsage parameter to false.

  • Scenario: You are reporting usage incrementally throughout the same day, and each post represents an additional amount of usage rather than a total replacement for that day.
  • Example:
    1. At 09:00 AM on 2024-08-01, you post processed data indicating 5 units of usage: 
      POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08
[
    {
        "summaryKey": "S456",
        "summaryDisplayName": "transactions",
        "quantity": 5,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]
    2. At 02:00 PM on the same day (2024-08-01), you post another batch of usage line data, adding 3 more units of usage and overwriteSameDayUsage set to false: 
      POST /usage/lines?subscriptionId={subscriptionId}&billingPeriod=2024-08&overwriteSameDayUsage=false
[
    {
        "summaryKey": "S456",
        "summaryDisplayName": "transactions",
        "quantity": 5,
        "productId": "c53df278-d591-427d-8039-1dc5f4dec15e",
        "unitOfMeasurement": "unit"
    }
]
  • Result: Both usage lines for summaryKey: "transactions" on usageDate: "2024-08-01" are kept. The system will have one record for quantity: 5 (from 09:00 AM) and another for quantity: 3 (from 02:00 PM) for that day. Both of these lines would then be saved in the p8p system, and, if no other activity happened for the rest of the billing period, Pax8 would bill out 2 lines for summaryKey: "transactions": One line with quantity: 5 and another with quantity: 3

By understanding and utilizing the summaryKey and the overwriteSameDayUsage parameter effectively, vendors can ensure accurate and flexible usage reporting to Pax8 for same-day postings.

Updated 10 days ago