Insider Preview
This feature is in Insider Preview and subject to change. It is available exclusively to select Aviate customers and partners. Join the waitlist →

Introduction

Aviate Contracts bring formal agreement management to Kill Bill. A contract represents a binding commercial agreement between you and your customer, tracking the full lifecycle from initial activation through renewal or termination.

When You Need This

Consider a B2B SaaS company that sells annual platform licenses. Today, a customer’s subscription lives in Kill Bill, but the commercial agreement — the 12-month commitment, the negotiated price, the auto-renewal terms — lives in a spreadsheet or a separate CRM. When renewal season comes, someone has to manually cross-reference systems to figure out which customers are up for renewal, what they were promised, and whether to auto-renew or renegotiate.

With Contracts, the commercial agreement and the billing subscription are linked in one system. You can see that Acme Corp is on a 12-month Enterprise contract that started in March, renews automatically in February, and has a 60-day termination notice period. When the contract approaches its end date, you can trigger renewal workflows, generate renewal quotes, or flag it for renegotiation — all driven by the contract state, not a calendar reminder.

Contracts are created automatically when a quote is converted to an order, or they can be created directly via the API. Each contract maintains a state machine, a billing schedule, and a link to the underlying Kill Bill subscriptions — giving you complete visibility into the commercial relationship.

PENDING ACTIVE suspend SUSPENDED resume PENDING TERMINATION TERMINATED RENEWED renew CANCELLED

Key Concepts

Contract Lifecycle

Every contract moves through a well-defined set of states:

State Transitions Description

PENDING

→ ACTIVE, → CANCELLED

Contract has been created but not yet started. The start date has not arrived, or manual activation is pending.

ACTIVE

→ SUSPENDED, → PENDING_TERMINATION

The contract is live. Subscriptions are active and billing is in progress.

SUSPENDED

→ ACTIVE, → PENDING_TERMINATION

Temporarily paused (e.g., due to payment failure). Billing is on hold; the contract can be resumed.

PENDING_TERMINATION

→ TERMINATED

A termination has been requested. End-of-term obligations are being processed.

TERMINATED

(terminal)

Contract has ended. All subscriptions have been cancelled.

RENEWED

(terminal)

Contract has been replaced by a renewal contract.

CANCELLED

(terminal)

Contract was cancelled before it became active.

Contract Schedules

Each contract contains a billing schedule that defines the key milestones:

  • Start date — when the contract becomes active

  • End date — when the contract term expires

  • Renewal date — when renewal processing begins (typically 30-60 days before end)

  • Billing milestones — periodic billing events aligned with the billing period

The schedule execution engine automatically processes these milestones, triggering the appropriate Kill Bill actions (subscription creation, invoice generation, etc.) at each milestone.

Getting Started with Contracts

Installing the Plugin

Install the Aviate plugin as described in the How to Install the Aviate Plugin guide.

Enabling Contracts

To enable the contract management APIs, start Kill Bill with the following system property:

com.killbill.billing.plugin.aviate.enableContractApis=true

Using Contract APIs

Once enabled, the contract APIs are available at /plugins/aviate-plugin/v1/contracts. Full API documentation is available at our API documentation.

Creating a Contract

Directly via the API

curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/contracts" \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Acme Corp -- Enterprise Agreement",
    "startDate": "2026-03-01",
    "endDate": "2027-02-28",
    "billingPeriod": "MONTHLY",
    "autoRenew": true,
    "items": [
      {
        "productOfferingId": "po-001",
        "quantity": 1
      }
    ]
  }'

Response:

{
  "id": "ctr-001",
  "accountId": "a1b2c3d4-...",
  "name": "Acme Corp -- Enterprise Agreement",
  "status": "PENDING",
  "startDate": "2026-03-01",
  "endDate": "2027-02-28",
  "autoRenew": true,
  "items": [ ... ],
  "schedule": { ... }
}

From a Quote (Recommended)

The most common way to create a contract is through the Quote → Order → Contract flow:

  1. Create a quote with product line items

  2. Submit the quote for approval

  3. Once approved, convert the quote to an order

  4. The order automatically creates a contract with the appropriate schedule

# Convert an approved quote to an order -- contract created automatically
curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/orders" \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "q-001" }'

The resulting contract inherits the products, pricing, and terms from the quote.

Managing Contracts

Viewing Contracts

# List all contracts for an account
curl "${KB_URL}/plugins/aviate-plugin/v1/contracts?accountId=a1b2c3d4-..." \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}"

# Get a specific contract with its schedule
curl "${KB_URL}/plugins/aviate-plugin/v1/contracts/ctr-001" \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}"

Suspending and Resuming

# Suspend a contract
curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/contracts/ctr-001/suspend" \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Payment failure -- 3 consecutive retries exhausted" }'

# Resume a suspended contract
curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/contracts/ctr-001/resume" \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}"

Terminating

curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/contracts/ctr-001/terminate" \
  -H "Authorization: Bearer ${ID_TOKEN}" \
  -H "X-Killbill-ApiKey: ${API_KEY}" \
  -H "X-Killbill-ApiSecret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "terminationDate": "2026-06-30",
    "reason": "Customer requested cancellation"
  }'

Termination cancels all underlying Kill Bill subscriptions effective on the termination date. Any prorated credits are applied to the final invoice.

Schedule Execution

The schedule execution engine runs automatically in the background, processing milestones as they arrive:

  • Subscription creation — when the contract start date arrives, subscriptions are created in Kill Bill

  • Billing events — at each billing milestone, invoices are generated

  • Renewal processing — if autoRenew is true, a new contract is created before the current one expires

  • Termination processing — outstanding obligations are settled and subscriptions are cancelled

You do not need to manually trigger any of these actions — they are handled by the schedule engine.

Quote → Order → Contract Flow

This is the recommended end-to-end flow for enterprise sales:

  1. Quote — a sales rep builds a quote with products, quantities, and pricing. The quote can be versioned and reviewed by multiple parties.

  2. Order — once the customer accepts, the quote is converted to an order. The order captures the customer’s commitment.

  3. Contract — the order automatically creates a contract. The contract manages the ongoing commercial relationship, including billing, renewals, and termination.

Each step in the flow is fully auditable, with state transitions and timestamps recorded for compliance.