View Categories
Create or edit a Client Billing Agreement

Create or edit a Client Billing Agreement #

Menu path: Core > Partners > select a Client > Billing Agreements

Client Billing Agreements are the “contract rules” the system uses to calculate what to bill a client and when to bill them. You set up the agreement once, then add one or more Revisions to define the actual prices (and any changes over time). When you process a billing period, the system looks for the signed revision(s) that apply and calculates charges automatically based on your settings.

When would you use this? #

  • You want the system to calculate invoices from warehouse activity instead of doing manual calculations.
  • A client has a specific charging model (fixed monthly fee, per service, per receipt/issue, or storage/holding).
  • You expect rates to change over time and want invoices to remain correct historically (use Revisions with start dates).

Before you start (important) #

A Billing Agreement describes what to bill and how to measure it. The prices themselves live in the Agreement’s Revisions, and only Signed revisions are used for billing. If you create an agreement but don’t add a signed revision, the billing period will fail validation.

Create a new Billing Agreement #

  1. Go to Core > Partners and open the client you want to bill.
  2. Open Billing Agreements and click Add New.
  3. Complete the agreement fields (type, quantum, frequency, and any scope fields like cargo type/service/document type).
  4. Add at least one Revision, set its start date, pricing structure, and prices, then mark it Signed when ready.
  5. Save.

Edit an existing Billing Agreement #

  1. Go to Core > Partners and open the client.
  2. Open Billing Agreements and select the agreement to update.
  3. Update the agreement fields as needed (e.g., end date, frequency, scope).
  4. If pricing changes, add a new Revision with a start date and sign it (do not overwrite old pricing).
  5. Save.

Field reference (what each field is for) #

Agreement details #

  • Partner: The client you are billing (selected from your partners list).
  • Code / Name / Invoicing Name: Identifiers for the agreement; invoicing name is what appears on invoices.
  • End: When the agreement stops being valid (leave blank if ongoing).

What you bill for #

  • Type (PartnerBillingAgreementType): Defines what activity is billed:
    • Lump Sum: fixed amount per period
    • Services: bill for service events (e.g., unloading, inspection)
    • Documents: bill per document processed (e.g., receipts/issues)
    • Holding: bill for items held in storage

How the system measures what to charge #

  • Quantum (PartnerBillingAgreementQuantum): Defines what is measured to calculate billable units:
    • Count (number of items/events)
    • Actual Units (units you specify)
    • Volume (CBM)
    • Weight
    • Line (per document line)
    • Days in Holding
    • Remaining Units

What the agreement applies to (scope) #

Use these to limit the agreement so it only bills the right things:

  • Cargo Type / Additional Service / Document Type: Restricts the agreement to a specific cargo, service, or document type.
  • Document Line Level / Metric: Adds more detail for document-based agreements (e.g., per item/per pallet).

Billing schedule #

  • Repeats Every: The number part of the interval (e.g., every 1 month, every 3 months).
  • Billing Frequency: The unit for the interval: Days, Months, Years, or OnActionOn (bill on an event/action date).

Billing date rules (for monthly/period billing) #

  • Date Type (BillingFrequencyDateType): How the billing date is chosen within the period: First day, Last day, or Specific date.
  • Specific Day (BillingFrequencySpecificDay): The day number (1–31) if you choose specific date.
  • Date Exception Default (BillingFrequencyDateExceptionDefault): What happens if the chosen day doesn’t exist in a month (e.g., 31st in February):
    • FirstDateAvailableBefore (use last day of that month)
    • FirstDateAvailableAfter (use first day of next month)

What happens next (Revisions and prices) #

After creating the agreement, you typically:

  • add a Revision for the prices and rules (flat rate or quantity-based with price scales),
  • optionally add minimum/maximum line charges and grouping rules,
  • and mark the revision Signed so it becomes active for billing.