Younium Developer Portal

You can access the Portal itself here: https://developer.younium.com/

Below, you will find an overview of some of the key developer documentation.

Younium Developer Documentation

Younium offers a set of APIs and integration tools that let developers connect external systems, automate workflows, and build on top of the Younium platform. This page gives an overview of how authentication works, what APIs are available, and how to work with key features like webhooks, subscriptions, products, and invoices.

Getting Started: Authentication

Every request to the Younium API requires a JWT access token. Here is how to get one.

Step 1 — Generate credentials

Open the User Profile Menu in the top-right corner of the Younium app, go to Privacy & Security, and select Personal Tokens in the left-hand panel. Click Generate Token, give it a name, and click Create. You will be shown a Client ID and a Secret Key. Copy both immediately — they are only shown once.

Step 2 — Request a JWT token

Send a POST request to the auth endpoint with your Client ID and Secret Key in the request body. Tokens are valid for 24 hours. Younium has separate endpoints for production and sandbox environments, as well as US-region variants.

Step 3 — Include the token in API requests

Add the token to the Authorization header of every request as a Bearer token. You should also include a Content-Type of application/json, specify an api-version (2.1 is the current recommended version), and provide a legal-entity header if your tenant has more than one legal entity. Omitting or misspelling the legal entity will result in a 403 Forbidden response.

Common errors

A 401 Unauthorized response means the token is missing, expired, or invalid. A 403 Forbidden response means the request was authenticated but access was blocked — usually due to a missing or incorrect legal-entity header, insufficient user permissions, or restricted integration access.

The Three Younium APIs

API v2 — Transactional

The main REST API for integrations that need to create, read, update, and delete data in Younium. It covers accounts, products, subscriptions, invoices, payments, and more. This is the right choice for operational integrations where your system needs to interact with Younium in real time.

Data Export API

Designed for syncing Younium data into data warehouses and BI platforms. It is optimized for high-volume retrieval, fetching records entity by entity. Related entities with one-to-many relationships are excluded from the main response and must be fetched via separate nested URL paths included in the response.

Insights API

An OData v4 interface for querying KPI and revenue metrics — including recurring revenue, ARR, and revenue changes — grouped by account, charge, and month. This is a pre-release API. It does not support legacy authentication methods.

API v2: Key Concepts

Null values

Fields with no value are omitted from responses. Only populated fields appear in the JSON.

No records found

If a GET request returns no matches, the API responds with a 400 Bad Request rather than an empty list.

Pagination

Results are paginated using the pageNumber and pageSize query parameters, with a maximum of 100 records per page. The Data Export API supports up to 5,000 records per page on some endpoints.

Sorting

Results can be ordered by one or more fields in ascending or descending order using the orderby parameter.

Filtering

Filters can be applied to most endpoints using field names, operators, and values. Supported operators include equality checks, range comparisons, and logical operators like AND and OR. String fields support startswith, endswith, and substringof functions. DateTime and GUID fields need to be typed explicitly in the filter value.

Filtering on nested fields is supported using a slash notation, but does not work on calculated fields, null fields, lists, or custom fields.

modifiedAfter and modifiedBefore

These are special parameters that apply a date filter across all sub-levels of an entity, not just the top level. This is useful when a subscription's charges or custom fields have changed but the subscription record itself has not been directly modified.

LookupKey identifiers

When creating or updating records that reference related entities — such as setting the account on a subscription — you can identify that entity by its UUID, by a string like its account number, or by specifying a key-value pair to match against any property. If no match is found, or if multiple matches are found, a 400 Bad Request is returned. Custom fields can also be used as lookup keys.

Webhooks

Webhooks let you receive real-time notifications whenever a business event occurs in Younium. When an event is triggered — whether from an API call, a user action in the UI, or another integration — Younium sends an HTTP POST request to your registered endpoint with details about the event.

Subscribing

You can subscribe to webhook events in the Younium app under Settings → Webhooks, or by calling the webhooks API endpoint with your target URL and a list of event tags. The response includes a verification token that will be included in every subsequent webhook request.

Request payload

Each webhook request includes the event type, a timestamp, the legal entity involved, the ID of the user or process that triggered it, and a correlation ID that links related events from the same transaction. The Data field contains entity-specific information for the event.

Delivery and retries

A webhook attempt is considered successful when your endpoint returns a 2xx status code. If the request fails or times out after 60 seconds, Younium automatically retries every three hours, up to ten attempts. After that, retries can be triggered manually via the UI. Webhook attempt logs are available in the app for the past 15 days. You can also enable email or in-app notifications when a webhook fails.

Available events

Younium fires webhook events for the following entities: subscriptions (activated, changed, updated, cancelled, renewed, reverted, deleted), sales orders (activated, updated, deleted), invoices (posted, updated), invoice batches (created, posted, cancelled), journals (posted), accounts (created, changed), quotes (created, edited, converted), payments (created, posted), and products (created, updated, deleted).

Paywall webhooks

If you use the Younium Paywall for automated online subscription sales, set up a webhook with the AccountCreated, InvoicePosted, PaymentPosted, and SubscriptionActivated events. All paywall-triggered events include a shared correlation ID linking them to the same checkout transaction, and a Source field set to "Paywall".

Working with Subscriptions

Subscriptions are the core entity in Younium. They require an account reference, a status, a start date, and — if set to active — at least one product. Currency defaults to the account's currency if not specified.

Creating a subscription

You can create a draft subscription with just an account reference, or create an active subscription immediately by including products in the request. Products reference entries from the product catalog and can specify a charge plan and individual charges with quantities and pricing. If you do not specify pricing, the defaults from the product are used.

Price details

When you need to override a charge's default pricing, you can define price details explicitly in the request. For tiered pricing models, every tier must be specified — tier indexes start at zero and must be consecutive, each tier's upper quantity must exceed the previous tier's, and the final tier can be set as infinite.

Discounts can be applied to all charges on a subscription or to specific charges only. You specify a percentage, optional start and end dates, and the list of affected charges.

Changing a subscription

Changing a subscription creates a new version. Only the components you include in the request are updated — everything else is carried forward unchanged. Each change requires an effective date and an operation type for each product: create to add a new product from the catalog, change to modify an existing order product, or cancel to end an existing order product. Discounts can also be added, modified, or removed as part of a change.

Working with Products

Every product in Younium must have at least one charge plan, and every charge plan must have at least one charge. The product type defines the structure: Simple products have one charge plan with one charge, MultipleCharges products have one charge plan with multiple charges, MultipleChargePlans products have multiple charge plans each with one charge, and Full products have multiple charge plans each with multiple charges.

Charges

Charges are the most important part of a product. They define the charge type (recurring, one-off, usage, or measured), the pricing model (flat, quantity, volume, or tiered), and the financial behavior — billing period, billing timing, tax settings, and revenue recognition accounts. Default values for charges can be set globally in the Younium UI under Settings → Products → Product settings.

Every charge except rated usage requires at least one price detail, which defines the price per currency. For tiered models, multiple price detail tiers per currency are supported.

Creating products

Products are created by posting the full product structure — name, type, category, charge plans, charges, and price details — in a single request.

Updating products

Products are updated using a PATCH request. You can add, modify, or remove charge plans, charges, and price details in one call. Each entity can include an operation field specifying whether it should be created, changed, or removed. Price details are identified by their tier index and currency rather than a lookup key. Note that updates are irreversible — deleted charges and charge plans cannot be recovered, and entities already in use on an active subscription or sales order cannot be removed.

Idempotent Requests

All POST endpoints support idempotency. This means that if you retry a request with the same idempotency key, Younium returns the original stored response instead of re-executing the operation. This prevents duplicate records from being created due to network failures or retry logic.

To use idempotency, include a unique key in the request header. A UUID is recommended. The same key can be reused across different endpoints since uniqueness is scoped per endpoint. You can also specify how long the response should be stored, up to a maximum of one week. The default is 24 hours.

If two requests with the same key arrive simultaneously, the second waits for the first to complete. If it cannot wait, a 409 Conflict is returned. If the request body differs from the original request with the same key, a 400 Bad Request is returned. Requests that fail before reaching the endpoint — such as authentication failures — are never treated as idempotent.

Invoice Operations

Some invoice endpoints use an operation response pattern rather than standard REST semantics. Instead of returning a 400 error on failure, these endpoints return a successful HTTP status with a "successful" field in the body indicating whether the operation actually completed. Validation errors in the request itself still return 400 as usual.

When generating invoices, the invoiceAction field controls the behavior. The default creates a draft only. You can also request that the draft be posted immediately in the same call, with the option to either keep the draft if posting fails or automatically cancel it.

For full API references, endpoint schemas, and changelogs, visit developer.younium.com.