Subsidy Applications

Overview

A subsidy application applies for the government subsidy (Zulage) of a customer's retirement product. By creating it, the customer gives lemon.markets the authorization (Vollmacht) to apply for the subsidy.

A product's subsidy application has versions. Every time the customer's situation changes, you create a new version; lemon.markets keeps the previous versions, so you can always see what was applied for and when. See the API reference for the request and response fields.

Sequence

The retirement product must exist before you create a subsidy application. If the application includes a spouse or children, create them as persons first, with the role subsidy_application.spouse or subsidy_application.child.

sequenceDiagram
    participant Partner
    participant API as lemon.markets API

    Note over Partner,API: Prerequisite: a retirement product (POST /accounts/{account_id}/products)

    opt Spouse (indirectly eligible customers only)
        Partner->>API: POST /persons with roles [subsidy_application.spouse]
        API-->>Partner: 201 person
    end

    loop For each child
        Partner->>API: POST /persons with roles [subsidy_application.child]
        API-->>Partner: 201 person
    end

    Partner->>API: POST /accounts/{account_id}/subsidy_applications
    API-->>Partner: 201 version with status created
    API-)Partner: event subsidy_application.created

    alt Application accepted
        API-)Partner: event subsidy_application.activated
    else Application rejected
        API-)Partner: event subsidy_application.rejected
    end

    opt Situation changes (e.g. a new child)
        Partner->>API: POST /accounts/{account_id}/subsidy_applications
        API-->>Partner: 201 new version with status created
        API-)Partner: event subsidy_application.superseded (for the version it replaces)
    end

    opt Customer revokes the authorization
        Partner->>API: POST /accounts/{account_id}/subsidy_applications/{subsidy_application_id}/cancel
        API-->>Partner: 200 version with status canceled
        API-)Partner: event subsidy_application.canceled
    end

To read the versions of a product, use GET /accounts/{account_id}/subsidy_applications?product={product_id}, or GET /accounts/{account_id}/subsidy_applications/{subsidy_application_id} for one version. To follow status changes, subscribe to the subsidy_application.* events, or filter GET /events by context.subsidy_application.

Statuses

stateDiagram-v2
    [*] --> created: POST /accounts/{account_id}/subsidy_applications
    created --> active: accepted for the subsidy
    created --> rejected: rejected
    created --> superseded: a newer version is created
    active --> superseded: a newer version becomes active
    created --> canceled: POST .../cancel
    active --> canceled: POST .../cancel
    superseded --> [*]
    canceled --> [*]
    rejected --> [*]

• created: the version was created and is not accepted for the subsidy yet.
• active: the version was accepted for the subsidy. A product has at most one active version.
• superseded: a newer version replaced this one. Final.
• canceled: the customer revoked the authorization (Vollmacht). Final.
• rejected: the application was rejected. Final.

How versions replace each other

• Creating a new version supersedes the previous created version right away.
• An active version stays active until the newer version is accepted. Then the newer version becomes active and the previous one becomes superseded.
• Only created and active versions can be canceled. Canceling a superseded version returns a 422; canceling an already canceled version returns it unchanged and creates no event.
• After a cancellation, the customer can authorize again by creating a new version.