Calling Norce Commerce Query API
Norce Commerce Query is an API based on the OData V4 standard. It enables integrated solutions to fetch data directly from Norce's data layer. This page provides a technical overview, including authentication, usage patterns, and best practices for working with the API.
Norce Commerce Query API Reference
The full API reference documentation is available at:
API Reference: Norce Commerce Query
Example Queries and Tools
Communication Protocols
Norce Commerce Query uses OData v4 over RESTful HTTP. All API calls must use HTTPS to ensure secure communication.
Authentication and Authorization
Norce Commerce Query requires OAuth2 authentication. Credentials are managed in the Norce Admin UI.
For details, see: Accessing APIs with OAuth2 accounts.
Important:
- All API calls must use HTTPS.
- You must include an
applicationId(orapplication-id) header.
Special Headers
applicationId(orapplication-id): Integer. Specifies the application context for the API call. For most queries, the specific application does not affect the data returned.
HTTP Status Codes
The API uses standard HTTP status codes to indicate the result of requests.
API Restrictions
Norce Commerce Query is a read-only API. All OData operations for writing or modifying data are disabled.
Supported Clients and Tools
The OData standard is widely supported. You can access Norce Commerce Query from browsers, code, or third-party tools.
For .NET environments, Norce recommends Simple.OData.Client.
To find a client for your language, search for “OData client <language/environment>”.
Namespaces in Norce Commerce Query
Norce Commerce Query organizes its methods into namespaces. Each namespace groups related data and has its own caching recommendations.
| Namespace | Description | Cache Recommendation |
|---|---|---|
| Core | Master lists shared by all clients (e.g., Countries, Currencies, VatCodes, SalesAreas). | Cache for a long time. |
| Application | Application-specific master data (e.g., suppliers, parametrics, categories). | Cache for a long time. |
| Customers | Customer, company, and account management data. | Cache for a while. |
| Products | Product data, supplier products, prices, inventory. | Cache for a while. |
| Orders | Orders, baskets (quotations), invoices, delivery notes. | Cache for a while. |
| Reporting | Data for reports, including sales and legacy reports. | Cache for a while. |
| Shopping | Recurring orders and delivery methods. | Short cache time. |
Products and Variants: Entity Relationships and $expand
/commerce/query/2.0 (PascalCase properties, e.g. Skus, VariantTypes) is deprecated — End of Support 2026-08-31, End of Life 2026-10-31. /commerce/query/3.0 (camelCase properties, e.g. skus, variant) is the current, supported version and has a different navigation-property model for Products/Variants (see below). New integrations should use v3.0. See Query API v2.0 deprecation notice.
In the Query API's Products namespace, Product is SKU-level data, and Variant is the grouping entity that clusters those SKU-level products together (e.g. the different colors/sizes of one item) — the reverse of how the Commerce Services REST API names things, where a Product JSON object nests a Variants array. A Variant has many Products; each Product references its one Variant.
Product navigation properties (v3.0):
| Property | Expands to | Notes |
|---|---|---|
skus | ClientProductSku | Holds partNo and status — this is where the part number actually lives, not on Product or Variant directly. |
categories | ProductCategory | |
cultures | ProductCulture | |
parametrics / parametricMultiple | ProductParametric / ProductParametricMultiple | |
families | ProductFamily | |
files | ProductFile | |
flags | ClientProductFlag | |
productRelations / productRelationRelatedProduct | ProductRelation | |
supplierSkus | SupplierProductSkuClient | |
variant | Variant (single, not an array) | The variant cluster this product belongs to. |
Product in v3.0 has no variantTypes property — that only exists in v2.0 (Product.VariantTypes, an array of ProductVariantType, distinct from Variant.VariantGroup below). In v3.0, use the singular variant navigation property instead.
Variant navigation properties (v3.0):
| Property | Expands to | Notes |
|---|---|---|
variantGroup | VariantGroup (single) | The variant-defining group (e.g. color/size). This is the correct property — VariantTypes is not a property on Variant. |
products | Product (array) | All SKU-level products in this variant cluster. |
cultures | VariantCulture |
Example — expanding multiple navigation properties in one v3.0 query:
GET /Products/Products?$expand=skus,categories,parametrics,cultures&$top=20$expand accepts a comma-separated list, and each expanded property can itself take $select/$filter/nested $expand — see the Postman Query Examples for worked examples (written against v2.0 PascalCase syntax; apply the same pattern with v3.0's camelCase property names).
Common Practices for Efficient Queries
Avoid N+1 Query Problems
When fetching related data (lookups), avoid querying for each row individually. Instead, fetch lookup data as a single list and perform in-memory lookups.
Use Simple Queries
Avoid complex joins. Instead, split complex queries into multiple simpler queries. For example, to get a price list name for an order item:
- Fetch the order row to get the price list ID.
- Fetch the price list details separately.
- Cache lookup data in memory for performance.
Implement Smart Caching
Cache data from the Application and Core namespaces for longer periods, as this data changes infrequently. Adjust cache duration based on the namespace and data volatility.
Postman Examples
Try out example queries using our Postman Collection.
See How to Use Postman Examples for guidance.