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
Core Objects
User
Customers who purchase from your store. Contains contact and billing information.
Product
Items you sell - games, subscriptions, digital downloads, etc.
Offer
Pricing configurations for products with region/currency support.
Discount
Price reductions via coupon codes or automatic sales.
Order
Purchase transactions containing items, totals, and status.
Payment
Financial transactions with charges and payment method details.
Subscription
Recurring billing relationships for subscription products.
Event
Webhook notifications about activity in your store.
Common Flows
One-Time Purchase Flow
Subscription Flow
Refund Flow
Subscription Lifecycle
Object Hierarchy
Catalog Structure
A 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
Transaction Hierarchy
Each customer action creates linked transaction objects:
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 | Alphanumeric string | L8VQK3N2M7KpQ9nR |
| Payment | UUID | 660e8400-e29b-41d4-a716-446655440001 |
| Payment Number | Alphanumeric string | L8VQK3N2M7KpQ9nR-0003 (renewals add a 4-digit cycle suffix) |
| Subscription | Alphanumeric string | L8VQK3N2M7KpQ9nR (the initial order number) |
| Event | UUID | 770e8400-e29b-41d4-a716-446655440010 |
The # prefix
The dashboard displays order and payment numbers with a leading #. That # is a display
convention only — the API never returns it, so store and send the value exactly as it appears in
order.number, payment.number, or subscription.id.
Order endpoints (/v0/orders/{orderIdOrNumber}/...) accept a #-prefixed number and strip it.
Subscription endpoints do not: #L8VQK3N2M7KpQ9nR passes validation, matches no subscription,
and comes back as a 404. Always strip the # before calling the API.
Order endpoints take either the order UUID or the order number in the same path segment. Subscription endpoints take the subscription ID (which is the initial order number) — not a UUID, and not a payment-provider subscription ID.
Webhook Events by Object
| Object | Events |
|---|---|
| Payment | payment_success, payment_failed, payment_refunded |
| Subscription | subscription_created, subscription_updated, subscription_interval, subscription_cancelled |
Each Event includes the related objects in its data payload, but the
keys differ by event family:
- Both —
data.items(purchased items with Product and Offer references) anddata.user(the User) - Payment events only —
data.order,data.payment, anddata.customer(an alias ofdata.user) - Subscription events only —
data.lastPaymentanddata.subscription
See Payload shape by event for the full table.
Next Steps
Last updated