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

# Overview

> Understand how Fungies API objects relate to each other.

This guide explains how the core API objects in Fungies work together to power your store. Understanding these relationships will help you build integrations and process webhook events effectively.

## Object Relationships

```mermaid theme={null}
flowchart TB
    subgraph Catalog["📦 CATALOG"]
        Product["Product"]
        Offer["Offer"]
        Discount["Discount"]
        Plan["Plan"]
        
        Product -->|has many| Offer
        Product -->|type=Subscription| Plan
        Discount -->|applies to| Offer
    end
    
    subgraph Transactions["💳 TRANSACTIONS"]
        Customer["User"]
        Order["Order"]
        Payment["Payment"]
        Subscription["Subscription"]
        Charge["Charge"]
        
        Customer -->|creates| Order
        Order -->|paid by| Payment
        Payment -->|contains| Charge
        Customer -->|charged via| Subscription
        Subscription <-->|recurring payments| Payment
    end
    
    subgraph Webhooks["🔔 WEBHOOKS"]
        Event["Event"]
    end
    
    Offer -->|purchased via| Order
    Payment -->|triggers| Event
    Subscription -->|triggers| Event
```

***

## Core Objects

<CardGroup cols={2}>
  <Card title="User" icon="user" href="/core-resources/user">
    Customers who purchase from your store. Contains contact and billing information.
  </Card>

  <Card title="Product" icon="box" href="/core-resources/product">
    Items you sell - games, subscriptions, digital downloads, etc.
  </Card>

  <Card title="Offer" icon="tag" href="/core-resources/offer">
    Pricing configurations for products with region/currency support.
  </Card>

  <Card title="Discount" icon="percent" href="/core-resources/discount">
    Price reductions via coupon codes or automatic sales.
  </Card>

  <Card title="Order" icon="receipt" href="/core-resources/order">
    Purchase transactions containing items, totals, and status.
  </Card>

  <Card title="Payment" icon="credit-card" href="/core-resources/payment">
    Financial transactions with charges and payment method details.
  </Card>

  <Card title="Subscription" icon="rotate" href="/core-resources/subscription">
    Recurring billing relationships for subscription products.
  </Card>

  <Card title="Event" icon="bell" href="/core-resources/event">
    Webhook notifications about activity in your store.
  </Card>
</CardGroup>

***

## Common Flows

### One-Time Purchase Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant S as Store
    participant O as Order
    participant P as Payment
    participant W as Webhook

    C->>S: Select Offer & Checkout
    S->>O: Create Order (PENDING)
    S->>P: Create Payment (PENDING)
    P->>P: Process Payment
    P->>P: Update to PAID
    P->>O: Update Order to PAID
    P->>W: Send payment_success Event
    W->>C: Deliver Product
```

### Subscription Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant O as Order
    participant P as Payment
    participant Sub as Subscription
    participant W as Webhook

    C->>O: Purchase Subscription
    O->>P: Initial Payment (subscription_initial)
    P->>Sub: Create Subscription
    Sub->>W: subscription_created Event
    Note over W: May show PENDING — not for fulfillment
    P->>P: Payment confirmed (PAID)
    P->>W: payment_success Event
    Note over W: Fulfill on this event
    
    loop Every Billing Interval
        Sub->>P: Create Payment (subscription_interval)
        P->>W: subscription_interval Event
    end
    
    C->>Sub: Cancel Subscription
    Sub->>W: subscription_cancelled Event
```

### Refund Flow

```mermaid theme={null}
flowchart LR
    A["Payment (PAID)"] --> B{Refund Type}
    B -->|Full| C["Payment (REFUNDED)"]
    B -->|Partial| D["Payment (PARTIALLY_REFUNDED)"]
    B -->|Failed| E["No Change"]
    
    C --> F["Order (REFUNDED)"]
    D --> G["Order (PARTIALLY_REFUNDED)"]
    
    F --> H["Event: payment_refunded"]
    G --> H
```

***

## Subscription Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> incomplete: Initial payment pending
    incomplete --> active: Payment successful
    incomplete --> incomplete_expired: Payment expired
    
    active --> past_due: Payment failed
    active --> canceled: User cancels
    active --> paused: Pause requested
    
    past_due --> active: Retry successful
    past_due --> unpaid: All retries failed
    past_due --> canceled: User cancels
    
    paused --> active: Resume
    paused --> canceled: User cancels
    
    unpaid --> canceled: Auto-cancel
    incomplete_expired --> [*]
    canceled --> [*]
```

***

## Object Hierarchy

### Catalog Structure

A [Product](/core-resources/product) is the top-level catalog item. Products can have:

* **Variants** - Different versions (Standard, Deluxe, Ultimate editions)
* **Plans** - Subscription billing options (Monthly, Annual)
* **Offers** - Pricing per region/currency

```mermaid theme={null}
flowchart TB
    Prod["🎮 Product: Pro Software"]
    
    Prod --> V1["Variant: Standard Edition"]
    Prod --> V2["Variant: Pro Edition"]
    Prod --> Plan["Plan: Monthly Subscription"]
    
    V1 --> O1["Offer: US $49.99"]
    V1 --> O2["Offer: EU €44.99"]
    V1 --> O3["Offer: UK £39.99"]
    
    V2 --> O4["Offer: US $99.99"]
    V2 --> O5["Offer: EU €89.99"]
    
    Plan --> O6["Offer: $9.99/month"]
    Plan --> O7["Offer: $99/year"]
```

### Transaction Hierarchy

Each customer action creates linked transaction objects:

```mermaid theme={null}
flowchart TB
    Customer["👤 User: john&#64;example.com"]
    
    Customer --> Order1["📦 Order #ABC123"]
    Customer --> Order2["📦 Order #DEF456"]
    
    Order1 --> Pay1["💳 Payment #PAY001 - one_time, PAID"]
    Pay1 --> Charge1["Charge: Visa ••4242"]
    
    Order2 --> Pay2["💳 Payment #PAY002 - subscription_initial"]
    Order2 --> Sub["🔄 Subscription #SUB789"]
    
    Sub --> Pay3["💳 Payment #PAY003 - subscription_interval"]
    Sub --> Pay4["💳 Payment #PAY004 - subscription_interval"]
```

***

## ID Formats

| Object       | Format | Example                                    |
| ------------ | ------ | ------------------------------------------ |
| User         | UUID   | `123e4567-e89b-12d3-a456-426614174000`     |
| Product      | UUID   | `bb0e8400-e29b-41d4-a716-446655440006`     |
| Offer        | UUID   | `990e8400-e29b-41d4-a716-446655440004`     |
| Discount     | UUID   | `880e8400-e29b-41d4-a716-446655440003`     |
| Order        | UUID   | `550e8400-e29b-41d4-a716-446655440000`     |
| Order Number | String | `#ABC123DEF456`                            |
| Payment      | UUID   | `660e8400-e29b-41d4-a716-446655440001`     |
| Subscription | String | `#SUB123DEF456` (based on order number)    |
| Event        | UUID   | `evt_123e4567-e89b-12d3-a456-426614174000` |

<Note>
  Order numbers and subscription IDs are human-readable strings prefixed with `#`. These can be used interchangeably with UUIDs in most API endpoints.
</Note>

***

## Webhook Events by Object

| Object                                       | Events                                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Payment](/core-resources/payment)           | `payment_success`, `payment_failed`, `payment_refunded`                                           |
| [Subscription](/core-resources/subscription) | `subscription_created`, `subscription_updated`, `subscription_interval`, `subscription_cancelled` |

Each [Event](/core-resources/event) includes the related objects in its `data` payload:

* `data.order` - The [Order](/core-resources/order)
* `data.payment` - The [Payment](/core-resources/payment)
* `data.customer` - The [User](/core-resources/user)
* `data.items` - Array of purchased items with [Product](/core-resources/product) and [Offer](/core-resources/offer) references

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks Setup" icon="webhook" href="/developers/webhooks/setup">
    Configure endpoints to receive events
  </Card>

  <Card title="API Authentication" icon="key" href="/api-reference/authentication">
    Get your API keys and authenticate
  </Card>
</CardGroup>