# Fungies

- API v0 Reference

  - **API v0 Documentation**
  - [Introduction](/api-reference/introduction): Learn how to integrate with the Fungies API to manage products, process payments, and handle subscriptions.
  - [Authentication](/api-reference/authentication): Learn how to authenticate your API requests using public and secret keys.
  - Discounts
    - [List discounts](/api-reference/discounts/list-discounts): Retrieve a paginated list of discounts with powerful filtering options.
    
    Discounts can be coupon codes that customers enter at checkout, or automatic sale discounts applied based on conditions.
    Results are sorted by creation date (newest first) by default.
    - [Create a new discount](/api-reference/discounts/create-a-new-discount): Create a new discount with the specified details.
    
    Discounts can be either:
    - Coupon codes: Customers enter a code at checkout to receive the discount
    - Sale discounts: Automatically applied based on conditions
    
    Both fixed amount and percentage-based discounts are supported.
    - [Get discount details](/api-reference/discounts/get-discount-details): Retrieve detailed information about a specific discount by its ID.
    
    Returns the full discount object including usage statistics and associated products/offers.
    - [Update a discount](/api-reference/discounts/update-a-discount): Update an existing discount's details.
    
    You can modify the name, amount, expiration, and other properties. 
    Note: Changing the discount code may affect customers who have saved the old code.
    - [Archive a discount](/api-reference/discounts/archive-a-discount): Archive (soft delete) a discount by its ID.
    
    Archived discounts can no longer be used at checkout but remain in the system for reporting purposes.
    This action is reversible.
  - Elements
    - [Create a new Checkout Element](/api-reference/elements/create-a-new-checkout-element): Create a new Checkout Element with specified offers.
      
      Checkout Elements are embeddable or hosted checkout experiences that can be 
      integrated into your website or application. They handle the entire checkout 
      flow including payment collection, tax calculation, and order creation.
      
      Supported configurations:
      - Single one-time purchase: One offer for a standard product
      - Multiple one-time purchases: Multiple offers in a cart
      - Subscription: One subscription offer (cannot be combined with other offers)
    - [List checkout elements](/api-reference/elements/list-checkout-elements): Retrieve a paginated list of checkout elements.
      
      Returns all checkout elements created for your workspace, including their 
      associated offers and configuration settings.
      Results are sorted by creation date (newest first).
  - Offers
    - [List offers](/api-reference/offers/list-offers): Retrieve a paginated list of offers with powerful filtering options.
    
    Offers represent purchasable configurations of products, including pricing, currency, 
    and subscription settings. A single product can have multiple offers for different 
    pricing tiers or billing intervals.
    Results are sorted by creation date (newest first) by default.
    - [Create a new offer](/api-reference/offers/create-a-new-offer): Create a new offer for a product.
    
    Offers define how a product can be purchased:
    - One-time purchase: Set price and currency, leave recurring fields empty
    - Subscription: Set price, currency, and recurring interval
    - Free: Set price to 0
    
    For subscription offers, you can optionally configure trial periods.
    - [Get offer details](/api-reference/offers/get-offer-details): Retrieve detailed information about a specific offer by its ID.
    
    Returns the full offer object including product reference, variant details, 
    pricing, subscription settings, and inventory status for key-based products.
    - [Update an offer](/api-reference/offers/update-an-offer): Update an existing offer's details.
    
    Can modify name, price, and settings. Note that changing pricing on an active 
    offer may affect existing subscription customers depending on your configuration.
    - [Archive an offer](/api-reference/offers/archive-an-offer): Archive (soft delete) an offer by its ID.
    
    Archived offers can no longer be purchased but existing subscriptions continue.
    This action is reversible.
    - [Add product keys](/api-reference/offers/add-product-keys): Add product keys (license keys, game keys, etc.) to an offer.
    
    Keys are automatically assigned to customers upon successful purchase.
    Each key can only be used once.
    - [Remove unsold keys](/api-reference/offers/remove-unsold-keys): Remove all unsold keys from an offer.
    
    This action permanently deletes keys that have not been assigned to customers.
    Sold keys are preserved for record-keeping.
    - [Remove specific unsold key](/api-reference/offers/remove-specific-unsold-key): Remove a specific unsold key from an offer by its ID.
    
    Only unsold keys can be removed. Sold keys cannot be deleted.
  - Orders
    - [List orders](/api-reference/orders/list-orders): Retrieve a paginated list of orders with powerful filtering options.
    
    Orders represent purchases made by customers, including one-time purchases, subscription initiation, and free product claims.
    Subscription renewal payments are tracked as separate payment objects, not orders.
    Results are sorted by creation date (newest first) by default.
    - [Get order details](/api-reference/orders/get-order-details): Retrieve detailed information about a specific order by its ID or order number.
    
    Returns the full order object including associated user, cart items, subscription (if applicable), and payment details.
    For subscription orders, also returns the current subscription status.
    - [Update order](/api-reference/orders/update-order): Modify an existing order's details.
    
    Can update status, value, fee, tax, and currency. Requires write access.
    
    Note: Use with caution as this directly modifies order records. For most cases, 
    use the refund or cancel endpoints instead.
    - [Cancel order](/api-reference/orders/cancel-order): Cancel a specific order by changing its status to CANCELLED.
    
    This action does not automatically process refunds. To refund a paid order, 
    use the refund endpoint or process through your payment provider.
    Requires write access.
    - [Refund order payment](/api-reference/orders/refund-order-payment): Refund a paid order via Stripe. Supports full and partial refunds.

    Requires write access, and refunds must be enabled for your workspace and on the platform — the endpoint returns 404 while refunds are not enabled; contact support to enable them.
    The customer is refunded first; the platform fee is adjusted for the refunded amount.

    Idempotency: when `idempotencyKey` is omitted, a key is derived from the request (amount, reason, metadata) and the order's refund state at request time. That protects true retries of an identical request, but a keyless retry after a lost response can be treated as a new request (and refund twice) once the first refund has applied — always send a stable `idempotencyKey` for retries. Repeating a non-exhausting partial refund with the same `idempotencyKey` returns the original refund and makes no further changes (no duplicate refund, status change, or notification). A repeat that would now be rejected by a fresh eligibility check — a full refund, an exhausting partial, or one exceeding the currently refundable amount — returns 400 instead; retry with a smaller/different request, or contact support to confirm the original refund's status.
  - Payments
    - [List payments](/api-reference/payments/list-payments): Retrieve a paginated list of payments with powerful filtering options.
    
    Payments represent individual transactions including one-time purchases, subscription payments, and refunds.
    Results are sorted by creation date (newest first) by default.
    - [Get payment details](/api-reference/payments/get-payment-details): Retrieve detailed information about a specific payment by its ID.

    Returns the full payment object including associated user, order, subscription, charges, and invoice details.
    - [Cancel a pending payment](/api-reference/payments/cancel-a-pending-payment): Request cancellation of a payment that is still pending — for example to abort an in-progress checkout before it completes.

    Only payments with status PENDING are eligible; any other status (including PAID, FAILED, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, UNPAID, and EXPIRED) returns an error. Currently only Stripe-processed payments are supported — PayPal payments and subscription plan-change payments cannot be cancelled through this endpoint.

    This only requests cancellation from the payment processor; it does not mark the payment as cancelled immediately. The payment's status updates to CANCELLED once the processor confirms the cancellation asynchronously.
  - Products
    - [List products](/api-reference/products/list-products): Retrieve a paginated list of products with powerful filtering options.
    
    Products are the core items available for sale. Each product can have multiple 
    variants (different configurations) and offers (different pricing options).
    Results are sorted by creation date (newest first) by default.
    - [Create a new product](/api-reference/products/create-a-new-product): Create a new product with the specified details.
    
    Products can be one of several types:
    - OneTimePayment: Standard products purchased once
    - Subscription: Products with recurring billing
    - Membership: Access-based products
    - GameKey: Digital key distribution
    
    After creation, add offers to make the product purchasable.
    - [Get product details](/api-reference/products/get-product-details): Retrieve detailed information about a specific product by its ID.
    
    Returns the full product object including variants, media, and associated offers.
    - [Archive a product](/api-reference/products/archive-a-product): Archive (soft delete) a product by its ID.
    
    Archived products are hidden from the store and cannot be purchased.
    Associated offers are also archived. Existing subscriptions continue.
    This action is reversible.
    - [Update a product](/api-reference/products/update-a-product): Update an existing product's details.
    
    Can modify name, description, media, and other properties.
    Note: The product slug cannot be changed after creation to prevent broken URLs.
    - [Duplicate a product](/api-reference/products/duplicate-a-product): Create a copy of an existing product with all its variants.
    
    The duplicated product will have a new ID and slug. Offers are not duplicated.
    - [Add a variant to a product](/api-reference/products/add-a-variant-to-a-product): Add a new variant (configuration option) to an existing product.
    
    Variants allow the same product to have different configurations, such as 
    different durations, tiers, or sizes. Each variant can have its own offers.
    - [Update a variant](/api-reference/products/update-a-variant): Update an existing variant's details.
    - [Archive a variant](/api-reference/products/archive-a-variant): Archive (soft delete) a variant by its ID.
    
    Associated offers are also affected. This action is reversible.
    - [Add a plan to a product](/api-reference/products/add-a-plan-to-a-product): Add a new subscription plan to an existing product.
    
    Plans are variants specifically for subscription products, typically 
    representing different billing intervals or tiers.
    - [Update a plan](/api-reference/products/update-a-plan): Update an existing plan's details.
    - [Archive a plan](/api-reference/products/archive-a-plan): Archive (soft delete) a plan by its ID.
    
    Existing subscriptions on this plan continue. This action is reversible.
  - Subscriptions
    - [List Subscriptions](/api-reference/subscriptions/list-subscriptions): Search and filter Subscriptions with pagination.
    Results are sorted by creation date (newest first) by default.
    - [Create Subscription](/api-reference/subscriptions/create-subscription): Create a new Subscription for a User.
    User must have a valid customer ID of Payment Provider set.
    Requires billing details with at least a country code and postal code if country is one of US, CA, UA, IN.

    Multiple items (up to 20) can be billed on a single Subscription — for
    example a base plan plus add-ons — and each line is preserved on the invoice and outbound
    webhooks. Because one Subscription maps to a single billing arrangement, every item must be on the
    same cadence:
    - Currency: all items must resolve to the same currency (from the item or its Offer).
    - Billing period: all Offers must share the same recurring interval and interval count (e.g. all
      monthly); mixing intervals (monthly + yearly) returns a 400.
    - Every item must reference a recurring Offer via offerId.
    - Trial: a trial (trialEnd / the Offer trial) is only applied to single-item Subscriptions.
      Multi-item Subscriptions start billing immediately (no trial).
    - Discount codes are not supported for multi-item Subscriptions.

    Note: User must have a valid customer ID of Payment Provider set and this customer must have a valid default payment method set (Payment Provider dashboard).
    - [Get Subscription](/api-reference/subscriptions/get-subscription): Retrieve detailed information about a specific Subscription.
    - [Get Upcoming Subscription Payment](/api-reference/subscriptions/get-upcoming-subscription-payment): Preview the amount and date of the Subscription's next renewal charge.

    Returns null when the Subscription is not active or is set to cancel at the end of the current
    interval — in both cases there is no upcoming charge to preview.

    The amount reflects Stripe's live invoice preview at request time and can still change before the
    charge actually happens (e.g. proration from a mid-cycle plan change, a coupon expiring, or tax
    recalculation) — it is a forecast, not a guarantee.
    - [Update Subscription](/api-reference/subscriptions/update-subscription): Update Subscription items and handle proration behavior.
    Can modify prices, quantities, and add/remove items.

    The items array is the desired end state of the Subscription: items are paired to existing lines
    by offerId, missing ones are removed, and new ones are added (up to 20
    total). All resulting items must share the same currency and billing period (recurring interval +
    interval count); otherwise the request is rejected with a 400.
    - [Charge Subscription](/api-reference/subscriptions/charge-subscription): Charge an additional one-off amount to an active Subscription.
    Creates a new Invoice and handles payment processing.

    Multiple items (up to 20) can be charged in a single call; each becomes its
    own Invoice line. All items must share the same currency, and that currency must match the
    Subscription's currency. Tax is calculated on the total and distributed proportionally across the
    lines.
    - [Cancel Subscription](/api-reference/subscriptions/cancel-subscription): Cancel a Subscription with specified options for timing and refunds.
    - [Pause Subscription Collection](/api-reference/subscriptions/pause-subscription-collection): Pause a Subscription's payment collection temporarily with options for handling payments.
    During the pause period:
    - No charges will be made
    - Access to subscription benefits will be maintained
    - Can be resumed manually or automatically at a specified time
    - [End Subscription Trial](/api-reference/subscriptions/end-subscription-trial): End a Subscription's trial immediately and start the paid subscription.
    The Subscription must be in trialing status.
    The first Invoice is created and charged right away using the payment method on file.
    The outcome (emails, webhooks, orders) is identical to the trial ending naturally.
  - Tax
    - [Calculate product price including tax](/api-reference/tax/calculate-product-price-including-tax): Return an indicative price for an offer including the tax that applies to a
    customer in the given country.

    Intended for storefront display (e.g. showing gross prices on a product page).
    The result is a **quote**, not a settled charge: the authoritative tax is always
    recomputed at checkout from full billing details. Amounts are returned in the smallest
    currency unit (e.g. 1099 = 10.99 in a 2-decimal currency).

    For business (B2B) buyers, pass customerType=company with taxId + taxNumber. The quote
    always returns the standard destination rate; if the buyer is eligible for reverse charge,
    reverseChargeEligible is true, but the 0% rate is only applied at checkout once the VAT-ID
    is validated.
  - Users
    - [List and filter Users](/api-reference/users/list-and-filter-users): Retrieve a paginated list of Users with powerful filtering options.
    Results are sorted by creation date (newest first) by default.
    
    Note: Timestamps can be provided in either seconds or milliseconds since Unix epoch.
    - [Create a new User account](/api-reference/users/create-a-new-user-account): Creates a new User account in the system. The email must be unique across all Users.
    Returns the created User object with all fields except the password.
    
    Note: If billingDetails are provided, ensure the countryCode is valid and postalCode is included for required countries.
    - [Get User object](/api-reference/users/get-user-object): Get detailed information about a specific User.
    - [Update User details](/api-reference/users/update-user-details): Update an existing User's data and billing details.
    - [Archive User](/api-reference/users/archive-user): Soft delete (archive) a User account. This action is reversible.
    - [Unarchive User](/api-reference/users/unarchive-user): Restore a User account that has been previously archived.
    - [Get User's inventory items](/api-reference/users/get-users-inventory-items): Retrieve a complete list of items in the User's inventory with filtering options.
    This includes:
    - All purchased products
    - Subscription items
    - Limited-time access items
    
    Use filters to narrow down results by product type.
  - Webhooks
    - [List webhooks](/api-reference/webhooks/list-webhooks): Retrieve all configured webhooks for the workspace, newest first.

    A workspace may have at most a small, fixed number of webhooks configured at once — see the
    create endpoint's error if that limit is reached.
    - [Create a webhook](/api-reference/webhooks/create-a-webhook): Register a new webhook endpoint and subscribe it to one or more event types.
    - [Send a test event](/api-reference/webhooks/send-a-test-event): Fire a synthetic event of the given type. It is delivered to every active webhook
    currently subscribed to that event type — not just one — the same way a real event would be,
    including retries on failure. Useful for verifying a receiving endpoint without a real purchase.
    - [Get webhook details](/api-reference/webhooks/get-webhook-details): Retrieve a specific webhook by its ID, including its subscribed event types.
    - [Update a webhook](/api-reference/webhooks/update-a-webhook): Update a webhook's URL, status, secret, or subscribed events.

    Any field omitted from the request is left unchanged. Passing 'events' replaces the full set
    of subscribed event types.
    - [Archive a webhook](/api-reference/webhooks/archive-a-webhook): Archive (soft delete) a webhook by its ID. It stops receiving deliveries but its
    delivery history remains available.
    - [List a webhook's delivery attempts](/api-reference/webhooks/list-a-webhooks-delivery-attempts): Retrieve delivery attempt history for a specific webhook, newest first — whether an
    event was delivered, the HTTP response received, and how many retries occurred.
- Core Resources

  - **Getting Started**
  - [Overview](/core-resources/overview): Understand how Fungies API objects relate to each other.

  - **Customers**
  - [User](/core-resources/user): The User object represents a customer in your Fungies store.

  - **Commerce**
  - [Product](/core-resources/product): The Product object represents a sellable item in your Fungies store.
  - [Offer](/core-resources/offer): The Offer object represents a purchasable pricing option for a product.
  - [Discount](/core-resources/discount): The Discount object represents a price reduction that can be applied to purchases.

  - **Transactions**
  - [Order](/core-resources/order): The Order object represents a purchase transaction in your Fungies store.
  - [Payment](/core-resources/payment): The Payment object represents a financial transaction in your Fungies store.
  - [Subscription](/core-resources/subscription): The Subscription object represents a recurring billing relationship with a customer.

  - **Webhooks**
  - [Webhook](/core-resources/webhook): The Webhook object represents an endpoint configured to receive Event notifications.
  - [Event](/core-resources/event): The Event object represents a webhook notification about activity in your Fungies store.
- Guides

  - **Your workspace**
  - [Workspace lifecycle](/guides/workspace-lifecycle): How Fungies keeps your workspace active, what happens if it goes inactive, and how to bring it back.
- Developers
  - Checkout Elements
    - [Checkout Elements Overview](/developers/checkout-elements/overview): Embed checkout experiences directly in your website or redirect customers to hosted checkout pages.
    - [JavaScript SDK](/developers/checkout-elements/sdk): Integrate Fungies checkout using the JavaScript SDK.
    - [HTML Data Attributes](/developers/checkout-elements/html-attributes): Add checkout buttons to your website using simple HTML data attributes.
    - [Billing Data Prefill](/developers/checkout-elements/billing-data): Prefill customer billing information in checkout to streamline purchases.
  - Webhooks
    - [Webhooks Overview](/developers/webhooks/overview): Receive real-time event notifications from Fungies in your application.
    - [Set Up Webhooks](/developers/webhooks/setup): Create and configure a webhook endpoint to receive Fungies events.
    - [Test Webhooks](/developers/webhooks/test): Test your webhook integration locally before deploying to production.
  - Customer Data
    - [Custom Fields Overview](/developers/customer-data/overview): Collect additional customer data during checkout to identify users in your system.
    - [Set Up Custom Fields](/developers/customer-data/setup): Create custom fields in the Fungies Dashboard to collect customer data during checkout.
    - [Validate Customer Data](/developers/customer-data/validate): Ensure data quality with regex patterns or custom validation endpoints.
  - Custom Domain
    - [Custom Domain Setup](/developers/custom-domain/overview): Connect your own domain to your Fungies storefront for a seamless brand experience.
- [Changelog](/changelog): New features and improvements in Fungies