# Subscription API

This guide provides a high-level overview of the **Gen Partner Managed Subscription Service Platform** and the **Subscription API** used by partners to initiate, change, and cancel subscriptions for Gen consumer security and identity products. It is intentionally non-sensitive and omits internal environment URLs, credentials, detailed schemas, and error code lists so it can be shared externally without a non-disclosure agreement (NDA).

***

## 1. What is the Subscription API?

The **Subscription API** is part of Gen's Partner Managed Subscription Service Platform. It exposes network APIs that allow partner systems to:

* **Create subscriptions** when a customer purchases an eligible Gen product through a partner channel.
* **Change subscriptions** over time (for example, upgrades/downgrades, prolonging a fixed-term plan, or updating subscription attributes).
* **Retrieve subscription information** so partner systems can display current status, entitlements, and key lifecycle dates to end users or internal agents.

The platform is responsible for enforcing subscription rules, license terms, and product relationships across Gen's Cyber Safety portfolio; partner systems focus on customer experience, billing, and local business logic.

***

## 2. Who Can Use the Subscription API?

The Subscription API is designed for approved partners that have completed commercial and technical onboarding with Gen. Typical categories include:

* **PMSS (Partner Managed Subscription Service) partners** – Manage **user billing and subscription lifecycle** while Gen continues to host the underlying Cyber Safety and identity services.
  * Partners orchestrate sign-up, renewal, and cancellation flows in their own environment.
  * The Subscription API keeps Gen's entitlement system synchronized with the partner's subscription system.
* **SDK partners** – Integrate Gen-hosted user experiences (e.g., security clients, embedded SDKs) and use the Subscription API to keep Gen's subscription state aligned with partner billing and offering lifecycle.

Access to the API, including credentials and rate limits, is granted only after a partner has been onboarded and approved through Gen's partner integration process.

***

## 3. Partner Data Models and PII Responsibility

Different product families use different data patterns. At a high level:

### 3.1 Partners Not Sending PII in API Calls

For many **security and privacy products** (e.g., antivirus, VPN, scam protection), partners typically **do not send sensitive personal identifiers** such as government IDs or full address data to Gen in the Subscription API calls.

In these integrations:

* Requests usually reference:
  * A **partner user identifier** (opaque ID in the partner system).
  * One or more **product identifiers** (such as product SKUs or subscription plans) that define the agreed-upon featureset.
* Gen manages the internal mapping from subscription identifiers to product licenses and devices.
* Any customer identity, profile, or billing data that stays solely in the partner's environment is governed by the partner's own compliance and privacy controls.

### 3.2 Partners Sending PII (Identity / LifeLock-type Use Cases)

For **identity protection and credit-related services**, enrollment requires additional **personally identifiable information (PII)** so Gen can perform fraud checks, identity verification, and regulatory compliance. In these integrations:

If Partners are responsible for:

* Collecting PII lawfully and with appropriate user consents
* Meeting applicable privacy and data-protection requirements in their own environments.
* Transmitting it only over secure, mutually agreed channels.

The **detailed PII schemas, validation rules, and error codes are provided only in NDA-protected specifications** and are intentionally **not** included in this guide.

***

## 4. Core Concepts

While the underlying technical format (REST/JSON) is defined elsewhere, several core business concepts are shared across partner integrations:

* **Subscription** – Represents the customer's entitlement to one or more Gen products under a specific plan, term, and configuration.
* **Fulfillment order** – A request from the partner to **create or renew** one or more subscriptions based on a purchase or plan change.
* **Subscription change** – A request to **modify an existing subscription**, such as:
  * Upgrades/downgrades between eligible plans.
  * Changing end dates for fixed-term subscriptions where allowed.
  * Updating activation state (e.g., cancel, restart in supported security contexts).
* **Account / partner customer identifiers** – Stable references that let Gen associate subscriptions with the correct end customer and partner record, without requiring the partner to expose their internal data model.

The exact field names and schema details for these concepts are documented in the full technical specifications and are not reproduced here.

***

## 5. High-Level API Operations

The Subscription API exposes operations grouped along three main capability areas:

1. **Fulfillment orders (Create / Renew)**
   * Used when a customer purchases a new subscription or when a fixed-term subscription is renewed through the partner's billing system.
   * The request references one or more product offerings and the target customer account; the response returns subscription identifiers that should be stored for subsequent operations.
2. **Subscription changes (Modify / Cancel / Update)**
   * Used to:
     * Activate or deactivate subscriptions associated with a point-of-sale event.
     * Adjust subscription metadata such as purchase country or certain end dates, where allowed by product rules.
     * Cancel or restart supported security subscriptions (identity-protection features follow separate rules).
   * Changes are typically driven by customer actions (e.g., upgrade, downgrade, cancel) or lifecycle events in the partner's own systems.
3. **Subscription queries (Get / Search)**
   * Allow partners to:
     * Retrieve a specific subscription by its unique identifier.
     * Search for subscriptions by partner-side account or customer reference, subject to access controls.
   * Common uses include customer-service tools, billing reconciliation, and eligibility checks before presenting offers.

The precise HTTP methods, paths, and response formats are defined in the official Swagger/OpenAPI documents that partners receive during onboarding; they are not repeated here.

***

## 6. Versioning and Environments (Conceptual Overview)

### 6.1 API Versioning

The Subscription API supports **explicit versioning** so that new capabilities can be introduced without breaking existing clients.

Key ideas:

* Each request targets a **specific API version**.
* Version selection can be conveyed either:
  * Through **content negotiation** (for example, using versioned media types in request/response headers), or
  * Through **version query parameters** in the request URL, depending on the agreed pattern for your integration.
* Partners should:
  * Treat the chosen version as part of their integration contract.
  * Plan for controlled migrations when Gen announces new versions they want partners to adopt.

Concrete header names, media type patterns, and version identifiers are considered implementation details and are provided only in the full technical specification.

### 6.2 Integration and Production Environments

To support safe rollout, Gen operates **separate environments** for testing and live traffic:

* **Integration / sandbox environment**
  * Used for initial development, QA, and partner acceptance testing.
  * Provides non-production data and configuration aligned with the partner's products and test scenarios.
* **Production environment**
  * Used for live customer traffic once the integration is approved.
  * Subject to Gen's production change, monitoring, and incident-management processes.

For each environment, Gen provides:

* A set of **base URLs** and **authentication credentials** specific to that environment.
* Configuration such as enabled products, supported regions, and data retention behavior.

Environment URLs, IP allow-lists, and credential formats are **not** included here because they are classified as internal/partner-confidential implementation details; they are delivered directly to onboarded partners.

***

## 7. Typical Integration Flow

This section outlines how partners generally work with Gen to integrate the Subscription API. Exact steps and milestones may vary by partner and product line.

{% stepper %}
{% step %}

### Engage With Gen's Partner Integration Team

* Confirm the **business model**:
  * SDK vs PMSS.
  * Whether the partner will send **no PII**, **basic contact data only**, or **full identity data** (the latter uses additional APIs and requires higher compliance obligations).
* Define **products and offers** to be sold through the partner channel and map them to Gen product identifiers.
* Identify which subscription lifecycle events (sign-up, trial conversion, renewals, upgrades, downgrades, cancellations, restarts) will be controlled by the partner vs by Gen.
  {% endstep %}

{% step %}

### Receive Configuration and Technical Assets

Once the initial design is agreed, Gen provides:

* Environment details (integration and production).
* Partner identifiers and access credentials for API authentication.
* Product mappings and configuration relevant to the integration.
* Links to **formal technical specifications** (Swagger/OpenAPI) that describe request/response schemas, status codes, and edge-case behaviors.

All of these materials are treated as confidential and shared via secure channels.
{% endstep %}

{% step %}

### Implement API Client Logic

At a high level, partners should:

* Use a **standards-based HTTP client** with TLS enabled for all calls.
* Implement the agreed **authentication mechanism** (for example, API keys, OAuth-style bearer tokens, or vendor credentials) exactly as described in the technical specification.
* Handle:
  * **Network-level errors** with appropriate retry and backoff logic.
  * **Application-level errors** by:
    * Persisting request identifiers on the partner side.
    * Surfacing clear customer messaging based on high-level error categories (e.g., invalid input, business rule violations, temporary system issues).
* Ensure all logging and monitoring in the partner environment avoids writing sensitive data (such as secrets or full PII payloads) to plain-text logs.

The detailed authentication scheme, header names, and full error-code catalog are intentionally omitted here and are covered by the formal specifications.
{% endstep %}

{% step %}

### Map Business Flows to API Calls

Partners typically implement the following flows:

1. **New subscription sign-up**
   * Trigger: customer completes purchase or opt-in flow in the partner UI.
   * Action: partner sends a **fulfillment order** request to create one or more subscriptions.
   * Store: subscription identifiers, any partner-to-Gen correlation keys returned.
2. **Subscription change (upgrade/downgrade or configuration change)**
   * Trigger: customer changes their plan, adds/removes options, or moves between regions/products where supported.
   * Action: partner sends a **subscription change** request reflecting the requested operation, ensuring it respects allowed transitions.
3. **Cancellation**
   * Trigger: customer cancels through the partner's billing or account UI, or a partner-driven business event (e.g., end of a bundled offer).
   * Action: partner calls the appropriate cancellation or deactivation operation on the Subscription API.
   * Result: Gen updates entitlement so product clients eventually reflect the cancelled state.
4. **Status and support queries**
   * Trigger: customer-service agents or automated systems need to know if a user is currently entitled to a product, how many devices are active, or why access changed.
   * Action: partner calls **subscription query** operations using partner-side account references or known subscription identifiers.

For identity-protection products that require PII, additional enrollment and consent flows are handled via separate APIs and legal documents; partners should follow those product-specific guides.
{% endstep %}

{% step %}

### Testing and Go-Live

Before going live, partners generally:

* Validate **happy paths** for:
  * New sign-ups.
  * Renewals (for fixed-term products).
  * Upgrades/downgrades where offered.
  * Cancellations and restarts in eligible cases.
* Exercise **negative scenarios** to ensure:
  * Input validation errors are handled gracefully.
  * Subscription rules (for example, products that cannot be restarted) are enforced with appropriate messaging.
* Align monitoring and alerting so both partner and Gen have visibility into integration health.

Go-live approvals and cutover plans are coordinated jointly between the partner and Gen's integration and operations teams.
{% endstep %}
{% endstepper %}

***

## 8. Security and Compliance Considerations (High Level)

While this guide avoids implementation details, the following principles apply to all integrations:

* All calls must use **encrypted network connections** (HTTPS over approved TLS configurations).
* API credentials, tokens, and any secrets must be **stored and rotated securely** in accordance with each party's security policies.
* Partners must:
  * Only send PII where strictly required and as described in product-specific documentation.
  * Ensure that data collection, consent, and retention align with applicable laws and Gen's contractual requirements.
* Detailed security obligations, including data classification, retention, and incident response processes, are defined in the underlying commercial and legal agreements and in NDA-protected technical and security documentation.

***

## 9. Where to Go Next

This overview is intended to help technical and business teams understand **what the Subscription API does and how it fits into partner integrations**, without exposing sensitive internal implementation details.

For an active or prospective partnership, your Gen contact can provide:

* The latest **Subscription API Swagger/OpenAPI definition**.
* Product-specific enrollment and PII-handling guides for identity and credit-related services.
* Environment configuration, credentials, and test data.
* Access to Gen's partner integration team for solution design, onboarding, and troubleshooting.

All such materials are shared through secure channels and may be subject to separate confidentiality terms.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://even-financial.gitbook.io/developer-center/cyber-safety-and-identity-solutions/subscription-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.