The Phone Number object is used in the Marketplace APIs to represent a phone number. This object contains two fields:

The Error object represents an error response returned by the Marketplace API when it encounters a non-2xx HTTP response code. This object includes the following fields:

All errors reported by the REST API have an and follow the standard format.

When an error occurs, the response body usually contains a JSON object with the following fields:

• type - [string] A URI reference that identifies the error type, providing a consistent way to categorize errors across different API implementations.

• title - [string] A human-readable title or summary of the error.

The Message object indicates the error or the reason for the order failure. This object contains the following attributes:

The Marketplace Platform provides two main entry points for interacting with your data:

• Portal (Web UI) – https://portal.platform.softwareone.com/

• API – https://api.platform.softwareone.com/public/v1/

While both the Portal and API operate on the same underlying objects, their URL structures differ slightly due to usability requirements. This topic explains how you can map between portal URLs and API endpoints to:

• Generate deep links to specific objects in the portal.

• Determine which API endpoint to call based on a portal URL.

• Build integrations that navigate between UI and API resources.

• Enable LLM agents to translate between human-readable links and API calls.

The base endpoint for the Marketplace Platform API is:

All API requests start from that base URL. For example, if you have an endpoint like:

The fully qualified URL that you need to use is:

Use this base endpoint with specific API paths to access the resources and services provided by the Marketplace Platform.

Every object in the Marketplace Platform has a unique identifier with a prefix that indicates the object type. For details on all such objects, see .

The following tables show how Portal URLs map to API endpoints for each category of objects.

The notifications module is primarily accessed through the API for webhook management and programmatic notification handling.

Where:

• {module} is one of: administration/settings, commerce, billing, catalog, program

• {resource} is the plural resource name (for example, agreements

The API follows the same structure, with /public/v1/ added after the base domain.

When you retrieve an object from the API, you can construct a Portal link using the object's id:

When you have a Portal URL and need to call the corresponding API:

You can determine the object type from the ID prefix:

When working with Marketplace Platform URLs, follow these guidelines:

1. Use the correct portal URL - Always use https://portal.platform.softwareone.com/ for Portal links. The legacy URL https://portal.softwareone.com/ is kept for backwards compatibility only and should not be used for new requests. Always route new links to portal.platform.softwareone.com.

2. ID recognition - Object IDs always follow the pattern {PREFIX}-{segments} where the prefix is 3 letters (for example, AGR, ORD

The Price object is a sub-object that represents sales and purchase prices, markup, margin, and other relevant financial data. The visibility of the Price object is determined by the context in which it is included. However, certain fields are always hidden from specific users. For example, clients cannot see purchase prices.

This page expands on the Resource Query Language with patterns and pitfalls learned from building integrations against the Marketplace Platform REST API. Use it when you need to write correct, efficient RQL and avoid common errors.

Discover fields before writing RQL

RQL filter and sort expressions only work with fields that exist on the resource. The API returns errors (for example, 'Unknown expression group' or 400 Bad Request) if you use a field name that does not exist or is not exposed for filtering.

What to do

• Use the resource schema (OpenAPI or your API documentation) to see the exact property names and types for each resource.

• Do not invent field names. For example, there is no generic subscriptionsCount field on agreements; the number of subscriptions is not a filterable RQL field. To get 'agreements with more than N subscriptions' you must either:

  • Query the child resource (for example, subscriptions) and filter by parent (for example, agreement.id).

  • Fetch agreements with select=+id,+name,+subscriptions.id,+subscriptions.name and compute or filter in your application.

A very common source of 400 errors is sending RQL as a single query parameter.

Many clients send this when given a params object like { "rql": "eq(status,Published)" }. The API typically responds with 400 Bad Request or 'Invalid equals shortcut expression' because it does not treat rql as a parameter whose value is the expression.

Append the RQL expression as the query string (or as the first part of it):

When you have both RQL and other parameters (like, limit, offset), combine them with &:

So in code: build the URL so that the RQL string is the first query segment; then append &limit=...&offset=... (and &select=..., &order=...) as needed. Do not put the whole RQL inside a single rql= parameter.

Wrong: rql="ilike(name,*Microsoft*) limit=20" or rql="eq(status,Active)&order=-created" — limit and order are not part of RQL; they are separate query parameters.

Correct: Send RQL as the filter only (example, ilike(name,*Microsoft*) or eq(status,Active)), and pass limit, offset, select, and order as separate parameters. The final URL will combine them: ?eq(status,Active)&limit=20&order=-audit.created.at.

ID values (such as, ACC-1234-5678, PRD-xxx, BUY-xxx, USR-xxx) must be in double quotes in RQL. Example: eq(client.id,"ACC-4402-5918"), eq(buyer.id,"BUY-1234-5678"). Unquoted IDs can return zero results.

Special characters (spaces, &, ?) in string values must be enclosed in double or single quotes: eq(firstName,"Buzz !!!").

To use a literal asterisk inside an ilike pattern, escape it: ilike(name,"The\**").

Date and audit metadata (created, updated) live under the audit object. The API behavior is:

Filtering or sorting by audit fields (such as audit.created.at, audit.updated.at) only works if the audit data is in scope for the response. That means you must include audit in the select parameter when you filter or sort by it.

If you omit select=audit (or equivalent), the API may ignore the filter or return 400.

Filter by creation date:

Sort by most recently updated:

Dates must be UTC with 3-digit millisecond precision: YYYY-MM-DDTHH:mm:ss.sssZ (for example, 2026-01-31T23:00:00.000Z). Prefer the full timestamp for precise filters; date-only (YYYY-MM-DD) may not behave as expected when comparing timestamps.

Other formats may not filter or sort correctly.

To get only the total count of resources matching a filter (such as, how many subscriptions does this agreement have?):

1. Call the child resource endpoint (for example, subscriptions).

2. Apply the filter (for example, by agreement ID via RQL or a direct filter like agreement.id=AGR-XXX if supported).

3. Set limit=0.

The response will have an empty data array but the correct total. This avoids transferring full payloads when you only need the number.

Example:

Response:

• select=+id,+name,+status - Include only these fields in addition to the default set. Use this to keep payloads small when you know what you need.

• Many resources omit large or sensitive fields by default. The response includes $meta.omitted listing properties that were not returned (for example, ["lines", "parameters", "subscriptions"]). To include one of them, add it with select=+field (for exampple, select=+lines,+parameters).

select=-metadata - Exclude a field.

Some integrations use select=-*,+id,+name,+field (exclude all, then add back only what is needed). Not all endpoints support the subtractive form; if you get 400, retry with additive only (for example, select=+id,+name,+field).

• +subscriptions - Return the full nested representation of the collection.

• +subscriptions.id,+subscriptions.name - Return only id and name for each nested item. Prefer this when you only need to list or count related items; it keeps responses smaller.

Many resources omit certain fields by default for performance.

They are listed in $meta.omitted in the response. Common examples: lines (order line items), parameters, subscriptions, assets, termsAndConditions, certificates, audit.

To include them, use select=+field (for example, select=+lines,+parameters).

• Default limit - If you omit limit, the API may apply a large default (like, 1000). For most use cases, set an explicit limit (such as, 20–50) to avoid oversized responses and timeouts.

• Maximum - The platform caps limit (often at 100). Values above the cap are treated as the cap.

• Count-only - Use limit=0 to get only

When you need both the total count and a list of items, use a single request with a reasonable limit (for example, 20–50):

• $meta.pagination.total gives the total count.

• data gives the first page of items.

Avoid running a second request with limit=0 just to get the count if the first request already returns the total in metadata.

Sort order is specified as part of the query string, not as a separate body or header:

• Ascending - order=+property or order=+audit.created.at

• Descending - order=-property or order=-audit.updated.at

Example:

If you filter or sort by an audit field, include select=audit (see ).

Always use field names that exist on the resource (see section 1).

In the API, Buyer and Client have distinct meanings and ID formats:

• Buyer - Legal entity; ID format BUY-xxxx-xxx. Core for billing and legal.

• Client - One or more Buyers in the Client Portal; ID format ACC-xxxx-xxxx.

Filtering by Client or Buyer: To filter by Client (ACC- IDs), use client.id in RQL on resources that expose it (for example, commerce.orders, commerce.agreements): eq(client.id,"ACC-1234-5678"). To filter by Buyer (BUY- IDs), use buyer.id: eq(buyer.id,"BUY-1234-5678"). Check the resource schema to see which relationship field exists (client.id, buyer.id, etc.).

Many resources also expose externalIds (vendor, client, operations), identifiers from actors outside the marketplace. Use them to filter by external references (for example, eq(externalIds.vendor,"Microsoft-account-123") or eq(externalIds.client,"my-order-ref")) when the resource schema includes these fields. See for semantics and typical usage.

Price objects typically expose SPxM / SPxY (sales/sell price) and currency. Include currency when stating amounts. See for full field semantics and visibility rules.

For "expiring", "renewal", or "commitment end" questions, key fields are: commitmentDate (ISO 8601 UTC), terms.commitment (for example, 1y, 1m), terms.period (billing period), and autoRenew (boolean).

Filter by commitmentDate in RQL for date ranges; include select=+commitmentDate,+autoRenew,+terms (or +terms.commitment) when you need to interpret renewal vs expiry in the response.

Some resources have endpoints that require path parameters (for example, get product by id: /catalog/products/{id}).

RQL applies to list endpoints; when you need a single item by ID, use the appropriate by-id endpoint and supply the path parameter (e.g. id=PRD-1234-5678). The resource schema or API docs will indicate when path parameters are required.

If the API returns 400 or "Unknown expression" (or "Unknown expression group"):

1. Re-check the resource schema - The field path you used may not exist or may be nested differently (e.g. seller.country vs seller.address.country).

2. Quote ID values - use eq(client.id,"ACC-1234-5678") not eq(client.id,ACC-1234-5678).

3. Include select=audit

• - Core operators and syntax.

• - C# implementation reference.

The Address object indicates a postal address. It contains the following fields:

Resource Query Language (RQL) is a query language used by the Marketplace Platform in its REST API. It's used for querying and manipulating resources in the Marketplace APIs.

With RQL, you can filter, sort, paginate, and project data. It's simple to use but flexible enough to handle complex scenarios.

Using RQL

RQL consists of a set of operators that can be classified into three main categories:

• Comparison operators – These operators perform comparisons like equals, greater than, and so on.

• Logical operators – These operators combine multiple conditions.

• Algorithmic operators – These operators handle functionalities, like sorting and pagination.

Operators are formatted as operator(arg1,arg2,...). Complex expressions can be created by nesting these operators.

Let's say you want to list all users with a specific domain. Implementing filtering is essential, and this is where RQL comes in.

To display all users with the first name 'Buzz', your GET request will look like this:

The same expression can be written as:

To sort users based on their first name, your GET request will look like this:

To sort in the opposite direction, the '-' operator can be used:

To paginate your results with a limit of 10 users and to retrieve the third page (offset 20):

• The first parameter limit=10 expresses the number of users to return.

• The second parameter offset=20 offsets the starting position in the result set. The first 20 users will be skipped.

To request specific fields, such as firstName, lastName, and email to be included, the select=+ operator can be used:

To request certain fields to be excluded, the select=- operator can be used:

To search for all users with the first name starting with 'Bu', the following query can be used:

the operator ilike performs a case-insensitive search.

Logical operators can be used to combine multiple operators. For example, to filter users with first name 'Buzz' and last name 'Astral':

In simple cases, a combined expression can also be written in the following form:

To pass special characters (like &^$?) or whitespaces as values to RQL operators, enclose them in either double quotes (") or single quotes (') as shown in the following example:

If you need to include a quotation mark within the value, you can do so by enclosing it with a different type of quotation mark, as shown in the following example:

Allowing you to pass these special symbols as values.

The asterisk (*) character has a special meaning in the ilike operator, matching zero or more characters in its place from the parameter value. For example, the "*dog" pattern will match strings like "big dog" and "dog," but it will not match "big dog!" because of the exclamation mark.

If you need to use the asterisk (*) character itself in the pattern, you can escape it as '*', as shown in the following example:

The ilike operator in this case will be searching for the literal value “The*” at the beginning of the firstName property.

Before writing RQL, keep these in mind:

For more details and advanced patterns, see .

This section documents key findings and best practices for interacting with the SoftwareOne Platform API, derived from real-world integration and debugging experience.

The API supports standard Bearer token authentication.

• Header: Authorization: Bearer <token>

One of the most critical findings is how RQL filters must be passed to the API.

• Do not pass RQL as a query parameter value (like, ?rql=and(...)). This often results in 400 Bad Request , or an Invalid equals shortcut expression.

• Append the RQL string directly to the URL query string.

Incorrect

Correct

You can mix RQL with standard parameters like limit and offset.

To get the count of related resources (example, "How many subscriptions does this agreement have?") without fetching all the data:

1. Query the Child Resource – Target the specific resource endpoint (example, /commerce/subscriptions).

2. Filter by Parent ID – Use a direct filter parameter if available, or RQL.

   • Finding: The API often accepts direct property filters like ?agreement.id=AGR-XXX.

Example Request

Response Structure

When requesting large datasets, such as full collections, the API might respond with a 302 Redirect to a file download URL (often for application/json format).

• Finding – Clients must handle redirects and potentially download from a secondary URL, for example, AWS S3.

• Header – Accept: application/jsonl is often used for these bulk operations.

You can filter by date ranges using ISO 8601 strings.

The any() operator is powerful for filtering based on properties of nested objects, such as, finding users in a specific group.

Be aware of metadata fields that affect data processing.

• $meta.pagination.total – The total number of records matching the query (useful when limit=0).

• $meta.omitted – A list of properties excluded from the response payload for security or performance reasons (like, ["credits"]).

Date fields like created and updated are typically nested within the audit object.

• Finding – To filter by these dates OR see them in the response, you must explicitly select the audit object. The API will not filter by fields that are not selected/visible in the response context.

• Example – ?select=audit&and(gt(audit.created.at,"2024-01-01..."))

In the API, Buyer and Client have distinct meanings and ID formats:

• Buyer represents a legal entity on the platform. This is the core entity for billing and legal purposes.

  • ID Format – BUY-xxxx-xxx

• Client represents one or multiple Buyers activated in the self-service part of the platform (Client Portal).

When filtering by Client (ACC- IDs), use client.id in RQL on resources that expose it (such as commerce.orders, commerce.agreements): eq(client.id,"ACC-1234-5678").

When filtering by Buyer (BUY- IDs), use buyer.id. Check the resource schema to see which relationship field exists.

For a C# reference implementation of RQL for .NET applications, see the GitHub repository at .

This topic lists all business objects available in the SoftwareOne Marketplace REST API and the corresponding API collection endpoints used to access them.

Use this page as a centralized reference to identify the correct object types and endpoints when designing integrations or reviewing platform capabilities.

Object ID prefixes

Every object in the Marketplace Platform has a unique identifier with a prefix that indicates the object type. Use these prefixes to quickly identify what kind of object you are working with:

Accounts

Use these guides and reference materials to build integrations. This section contains key patterns, behaviors, and shared structures used across all APIs.

This section contains a list of objects used across Marketplace APIs, along with their corresponding fields.

• Address

• Audit

• Date

The External IDs object contains a set of external identifiers.

External IDs are assigned during a PUT (update) or POST (create) request. Clients can update only their own external IDs, vendors can update only their own external IDs, and SoftwareOne Operations can update only the ID related to their specific operation.

Many resources (agreements, orders, subscriptions, etc.) expose a externalIds property. It stores key identifiers from actors that interact with the object but are not part of the marketplace (vendor, client, operations). Each actor can set and see only their own key; the meaning of each key depends on the resource and the actor.

• externalIds.vendor - On agreements and related resources, the vendor often stores the external unique identifier of the contract in their system (for example, Microsoft account ID, Adobe client ID). Use it to correlate platform objects with vendor-side contracts or systems.

• externalIds.client - The client can use this for programmatic access or to store a reference that matters on their side (for example, blanket order ID, open order ID, or an internal reference). Useful when looking up an order or agreement "by our reference" or "by our ID".

• externalIds.operations

Which keys exist and who can read/write them depends on the resource and the caller; check the resource schema and visibility rules. To filter by an external ID in RQL, use the field path (for example) eq(externalIds.vendor,"ABC-123") or eq(externalIds.client,"my-ref-456")) when the resource exposes it.

Parameter object

The Parameter object contains the value of the given parameter along with additional information, such as constraints and validation errors.

Parameter Constraints define the overridden behavior of a parameter.

Parameter Group is used to visually split different types of parameters.

View state diagrams for Marketplace Platform objects.

These objects support workflows between , such as clients, partners, and vendors.

This page includes objects that move through statuses during their lifecycle. Objects without statuses, such as audit records and spotlight resources, are not included.

Open a section to view the available diagrams for each API.