> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rabot.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Offer Order Contract Lifecycle

### Overview

This documentation package contains two complementary diagrams that illustrate the complete customer lifecycle when using the RABOT Partner API for electricity tariff contract processing.

***

## Diagram 1: Customer Lifecycle Swim-lane Diagram

### Purpose

Shows the **optimal happy path** flow across all actors (Partner, Customer, RABOT, Market Communication Partner) from initial offer generation through to contract activation.

### Key Features

* **Swim-lanes** represent each actor's responsibilities
* **Sequential flow** shows the chronological progression
* **Data requirements** are annotated at each stage
* **Optimal approach** assumes all contract data is collected upfront during quote preparation

### How to Read

1. Follow the flow from top to bottom
2. Each colored section represents a major phase
3. Arrows show interactions between systems
4. Notes indicate critical data requirements and decision points

### Important Note

**This diagram shows the STREAMLINED flow for a Telesales operating partner.** Partners can alternatively collect order data AFTER offer acceptance, but this approach lengthens deal velocity and is not recommended.

```mermaid placement="top-left" theme={null}
sequenceDiagram
    participant Partner as Partner System
    participant Customer as Customer
    participant RABOT as RABOT API
    participant Market Communication Provider as Market Communication Provider

    Note over Partner, Market Communication: OPTIMAL FLOW: All order data collected upfront during quote preparation

    rect rgb(240, 248, 255)
        Note over Partner,Customer: 1. OFFER GENERATION & SEND
        Partner->>Partner: Sales rep collects tariff details and contract data
        Partner->>Partner: Generate price quote
        Partner->>Customer: Send offer email with acceptance CTA link
    end

    rect rgb(245, 255, 250)
        Note over Customer,RABOT: 2. OFFER ACCEPTANCE & ORDER SUBMISSION
        Customer->>Partner: Click CTA in offer email (confirms acceptance)
        Partner->>Partner: Track acceptance confirmation
        Partner->>RABOT: POST /orders (submit complete contract data)
        RABOT->>RABOT: Create contractDraft - State: Open
    end

    rect rgb(255, 250, 240)
        Note over RABOT: 3. PRE-VALIDATION
        RABOT->>RABOT: Run pre-validation checks
        alt Pre-validation PASS
            RABOT->>RABOT: Update state: Open to Processing
        else Pre-validation FAIL
            RABOT->>RABOT: State remains Open - Support ticket raised
            Note over RABOT: Support team resolves issue (may contact customer)
        end
    end

    rect rgb(255, 245, 245)
        Note over RABOT,Market Communication Partner: 4. CHANGE PROCESS INITIATION
        RABOT->>Market Communication Partner: Transmit order data (tariff + contract + delivery info)
        Market Communication Partner->>Market Communication Partner: Initiate supplier change process
    end

    rect rgb(250, 240, 255)
        Note over Market Communication Partner,Customer: 5. CHANGE PROCESS EXECUTION
        Market Communication Partner->>Market Communication Partner: Execute market location transfer
        alt Change Process SUCCESS
            Market Communication Partner->>RABOT: Confirm successful completion + deliveryStart date
            RABOT->>RABOT: Update: contractDraft to contract
            RABOT->>Partner: Webhook/API notification: Contract activated
        else Change Process ISSUES
            Market Communication Partner->>RABOT: State: Processing - deliveryState: Denied + issue message
            Note over RABOT: Support team resolves issue (may contact customer)
        end
    end

    rect rgb(240, 255, 240)
        Note over Partner,Customer: 6. CONTRACT ACTIVE
        Partner->>Customer: Contract confirmation with delivery start date
        Note over Customer: Electricity supply begins on delivery start date
    end

    Note over Partner,Market Communication Partner: This is the streamlined flow. Partners can collect order data AFTER acceptance, but this lengthens deal velocity.
```

***

## Diagram 2: Contract State Transition Diagram

### Purpose

Shows **all possible states** a contractDraft can transition through, including error states and terminal conditions.

### States Explained

| State          | Type        | Description                                           | Action Required      |
| -------------- | ----------- | ----------------------------------------------------- | -------------------- |
| **Open**       | Initial     | ContractDraft created, awaiting pre-validation        | None (automated)     |
| **Processing** | Active      | Pre-validation passed, transmitted to Market Partners | None (automated)     |
| **Denied**     | Recoverable | Issue during change process                           | Support intervention |
| **Rejected**   | Terminal    | Order rejected (insolvency/timing)                    | None                 |
| **Revoked**    | Terminal    | Customer cancelled during change                      | None                 |
| **Contract**   | Success     | Change process completed successfully                 | None                 |
| **Cancelled**  | Terminal    | Customer cancelled after delivery started             | Optional: Winback    |

### Transition Triggers

* **Solid arrows:** Standard transitions
* **Notes:** Explain trigger conditions and required actions
* **Return paths:** Show recoverable error states (e.g., Denied → Processing)

```mermaid placement="top-left" theme={null}
stateDiagram-v2
    [*] --> Open: Partner submits POST /orders (contractDraft created)
    
    Open --> Processing: Pre-validation PASSED
    
    Open --> Open: Pre-validation FAILED (Support ticket raised)
    
    Processing --> Contract: Change process SUCCESSFUL (deliveryStart date received)
    
    Processing --> Denied: Change process ISSUE (deliveryState Denied - Support required)
    
    Processing --> Rejected: Order REJECTED by market (Insolvency or contract timing)
    
    Processing --> Revoked: Customer REVOKED order during change process
    
    Denied --> Processing: Issue RESOLVED by support team
    
    Contract --> Cancelled: Customer CANCELLED contract (After delivery started)
    
    Contract --> [*]: Contract lifecycle complete
    Cancelled --> [*]
    Rejected --> [*]
    Revoked --> [*]

    note right of Open
        Initial state after order submission.
        Remains here until pre-validation passes.
    end note
    
    note right of Processing
        Order cleared and transmitted to Market Communication Partner.
        Awaiting change process completion.
    end note
    
    note right of Contract
        Active contract with confirmed delivery date.
        Electricity supply begins on deliveryStart.
    end note
    
    note right of Denied
        Temporary issue during change process.
        Support team works to resolve.
        Can return to Processing after resolution.
    end note
    
    note right of Rejected
        Terminal state - order cannot proceed.
        Common reasons: insolvency, contract timing.
    end note
    
    note right of Revoked
        Terminal state - customer withdrew.
        No further action possible.
    end note
    
    note right of Cancelled
        Terminal state - post-contract cancellation.
        Partner may attempt to win back customer.
    end note
```

***

## Key Integration Points for Partners

### 1. Order Submission (POST /orders)

**When:** After customer accepts offer\
**Requirements:**

* Email address (verified)
* Delivery address (must be findable in RABOT database)
* Meter number
* Tariff details (working price, base price)
* Personal details (userAccount DTO)
* Previous supplier (for supplier changes)
* Move-in date (for new move-ins)
* Bank details
* Invoice address (if different from delivery address)

**Best Practice:** Collect ALL data during initial quote preparation to minimize delays.

### 2. Pre-validation Checks

**What RABOT validates:**

* Email address format and validity
* Delivery address exists in database
* Meter number is present

**Partner Recommendation:** Perform these checks BEFORE submitting to RABOT to reduce support overhead and accelerate processing.

### 3. State Monitoring

Partners should monitor contract states via:

* API polling

**Critical states to monitor:**

* `Open` → no change after 24 hours? Check support tickets
* `Denied` → review issue message, customer support will contact customer
* `Contract` → celebrate! Inform customer of delivery start date

***

## For Energy Market Newcomers

### What is the "Change Process"?

When a customer switches electricity suppliers, a formal market process coordinates:

1. The customer's current supplier
2. The new supplier (you/RABOT)
3. The grid operator
4. The metering company

RABOT utilises a service provider for managing this communication, ensuring all market partners are synchronized.

### Typical Timeline

* **Offer to Acceptance:** Hours to days (partner-dependent)
* **Acceptance to Processing:** Minutes (if data complete)
* **Processing to Contract:** Weeks (market-dependent, typically 2-6 weeks)

***

## Common Failure Scenarios

### Scenario 1: Pre-validation Failure (State: Open)

**Common causes:**

* Invalid email format
* Delivery address not in database
* Missing meter number

**Resolution:** RABOT Customer Support team contacts customer or partner to collect missing data.

### Scenario 2: Denied During Change Process

**Common causes:**

* Market Location cannot be identified
* Existing contract end date is too far in future
* Data mismatches with existing supplier

**Resolution:** RABOT Customer Support investigates and may contact customer.

### Scenario 3: Rejected Order

**Common causes:**

* Customer has insolvency proceedings
* Existing contract end date is too far in future

**Resolution:** No action possible. Order cannot proceed.

***

## Optimization Tips for Partners

1. **Collect Complete Data Upfront**
   * Gather ALL order data during quote preparation
   * Validate email, address, and meter number before submission
   * Reduces processing time from weeks to days
2. **Automate Offer Acceptance Tracking**
   * Use unique CTA links with order identifiers
   * Trigger POST /orders automatically upon acceptance
   * Minimize manual intervention
3. **Monitor State Transitions**
   * Set up alerts for `Denied` states
   * Track time-in-state metrics
   * Identify bottlenecks in your process

***

## Questions or Concerns?

Feel free to speak with our [Integration Management Team](mailto:j.ohara@rabot.energy) or alternatively, ask our built-in AI assistant, Rabotini 🤖 (several languages supported).