Migrating from Norce Commerce Query v2 to v3

Last changed: 2026-03-20

Target audience: Developers and integration engineers maintaining services that consume the Norce Commerce Query API.
Applies to: All integrations using /commerce/query/2.0

Background

Norce Commerce Query v3.0 is a modernised rebuild of the Query API. The underlying OData V4 contract is preserved, but the new version introduces a cleaner data model aligned with the current Norce Commerce data layer, removes several deprecated entities, and fixes a number of long-standing inconsistencies in the v2 contract.

Most integrations will require only minor updates. This page documents the key differences between v2 and v3 so you can assess impact and plan your migration.

Base URL change

The version segment in the base URL changes from 2.0 to 3.0. Update all hardcoded base URLs and configuration values accordingly.

Example — Products namespace:

# Before
GET https://customer.api-se.norce.tech/commerce/query/2.0/Products/ProductSkus

# After
GET https://customer.api-se.norce.tech/commerce/query/3.0/Products/ProductSkus

Authentication and the applicationId header requirement are unchanged.

General contract changes

These changes affect all namespaces and may impact any integration that processes OData metadata or inspects type information at runtime.

OData namespace renamed

The OData service namespace has changed. If your integration reads or validates the $metadata document, update accordingly.

This affects the $metadata endpoint for all namespaces. It does not affect the shape of entity responses.

EntityType names simplified

EntityType names in the $metadata document have changed. The JSON response contract is unaffected, but if you are generating client code from metadata (e.g. using an OData client generator), regenerate your client models against the v3 $metadata endpoint before deploying.

ClientId removed from entity keys

ClientId has been removed as a property on all entities where it was previously part of the composite key. Queries that explicitly filter or expand on ClientId as a key field will need to be updated.

Numeric scale casing

Numeric properties are now tagged with Scale="variable" (lowercase v) instead of Scale="Variable". This is a metadata-level change only and does not affect query results.

Navigation property referential constraints

Navigation properties that were missing ReferentialConstraint declarations in v2 now have them in v3. This improves metadata correctness and is non-breaking for most clients.

Nullable column alignment

Some properties that were non-nullable in the v2 contract are now correctly marked nullable in v3, reflecting the actual database column definition. If your code assumes these fields are always present, add null checks.

Changes to Core namespace

Cultures navigation properties removed

The unnecessary Cultures navigation property has been removed from the following entities:

• Country
• Currency
• SalesArea
• File
• SkuStatus
• VatCode
• ProductInfoTypeGroup

If your integration expands Cultures on any of these entities, remove those $expand clauses.

Recurring order entities removed

The following entities have been removed from the Core namespace. Recurring order functionality is deprecated in Norce Commerce.

• RecurringOrderStatus
• RecurringOrderStatusCulture
• RecurringOrderScheduleFrequency
• RecurringOrderScheduleFrequencyCulture
• RecurringOrderScheduleMonthlyInterval
• RecurringOrderScheduleMonthlyIntervalCulture
• RecurringOrderScheduleMonthlyIntervalValue
• RecurringOrderScheduleMonthlyIntervalValueCulture

Applications filtered to active only

Applications now returns only active applications. In v2 it returned all applications regardless of status. If your integration relies on retrieving inactive applications (deleted), this will require a process change.

Changes to Application namespace

ClientWarehouseLocation.ValueBT renamed to ValueBt

The property ValueBT on ClientWarehouseLocation has been renamed to ValueBt (lowercase t). Update any $select or property access using the old name.

# Before
$select=ValueBT

# After
$select=ValueBt

ApplicationCurrency — CurrencyId added as key

ApplicationCurrency now includes CurrencyId as part of its composite key, consistent with other application-scoped entities. Review any queries that address ApplicationCurrency entities by key.

ClientSupplierInfo — Id removed from properties

Id has been removed from the property list on ClientSupplierInfo since it is already part of the entity key. This is a cleanup change and does not affect the data returned.

ApplicationSalesAreas scoped to the application

ApplicationSalesAreas now correctly returns only sales areas belonging to the queried application similar to the other application lookups.

In v2, this was a bug that caused all sales areas to be returned regardless of application context. Update any logic that assumed the full unfiltered list.

Changes to Products namespace

Navigation properties removed from Product

The following navigation properties have been removed from the Product entity:

• Accessories
• Upsell
• CrossSell
• VariantTypes

If you expand these on Product, remove the $expand clauses. ProductRelations are used instead of the older properties (accessories, upsell, cross-sell) which is a deprecated functionality.

ProductVariantType and ProductVariantTypeCulture removed

These entities are deprecated in Norce Commerce. Use ProductParametrics and variant-type parametrics instead (parametrics where IsVariantType = true).

ClientProductSkuPriceListInfo — Id added as key

Id has been added as a key field on ClientProductSkuPriceListInfo. Either include Id in your $select clauses or be aware it is now part of the key.

ClientProductSkuBestPrice — Id added as key

Id has been added as a key field on ClientProductSkuBestPrice. Include Id in your $select clauses or be aware it is now part of the key.

SupplierProductSkuInfo removed

This entity is deprecated in Norce Commerce and has been removed. If your integration reads supplier product data through this entity, migrate to the Connect API or the Management API.

ProductParametricCulture — CultureCode added as key

CultureCode is now part of the composite key on ProductParametricCulture. Queries addressing these entities by key need to include CultureCode.

ProductPopularity — Id added as key

Id is now part of the entity key on ProductPopularity.

VariantCulture — ClientId removed from key

ClientId has been removed from the key on VariantCulture. This corrects an error in the v2 contract where ClientId was incorrectly included as a key field.

Changes to Reporting namespace

The Reporting namespace has been removed in v3 and the functionality has for a long time been deprecated.

Changes to Shopping namespace

ApplicationPaymentMethod — PaymentServiceId added as key

PaymentServiceId is now an additional key field on ApplicationPaymentMethod. If this key field is not included in your query, PaymentServiceId will not be present in the response. Update queries that address payment methods by key.

Recurring order entities removed

RecurringOrder has been removed from the Shopping namespace, consistent with the removal of recurring order support across the platform.

Changes to Orders namespace

WarehouseTransaction and WarehouseTransactionItem removed

These entities have been removed from the Orders namespace.

Order.TmsReference added

A new property, TmsReference, has been added to the Order entity. This field supports transport management system (TMS) reference data.

PurchaseOrder and PurchaseOrderItem removed

PurchaseOrder and PurchaseOrderItem have been removed from the Orders namespace.

Changes to Customers namespace

CustomerCompanies removed

The CustomerCompanies endpoint (/Customers/CustomerCompanies) has been removed from the Customers namespace in Query API v3. Use the Companies endpoint instead.

Migration checklist

Use this pane when you want a migration checklist that can be copied directly into a local repository, ticket, or AI agent prompt.

# Query API v2 to v3 upgrade checklist

Use this checklist when upgrading an integration from `/commerce/query/2.0` to `/commerce/query/3.0`.

## Base URL

- [ ] Update the base URL from `/commerce/query/2.0` to `/commerce/query/3.0` in all configuration files and hardcoded values.

## Client code and metadata

- [ ] Regenerate client models if the integration generates code from the `$metadata` endpoint.
- [ ] Update OData namespace references from `Enferno.Storm.Query.Api.DataContexts` to `Norce.Infrastructure.Data`.
- [ ] Validate metadata consumers against simplified `EntityType` names in Query API v3.
- [ ] Validate metadata consumers that depend on exact scale casing or referential constraint declarations in the `$metadata` document.

## General model changes

- [ ] Remove filters, key lookups, or expands that treat `ClientId` as part of the entity key.
- [ ] Add null checks for fields that are now correctly marked nullable in Query API v3.

## Core namespace

- [ ] Remove `$expand=Cultures` from queries against `Country`, `Currency`, `SalesArea`, `File`, `SkuStatus`, `VatCode`, and `ProductInfoTypeGroup`.
- [ ] Remove queries against recurring order entities in the `Core` namespace.
- [ ] Review logic that depends on inactive applications being returned by `Applications`.

## Application namespace

- [ ] Rename `ValueBT` to `ValueBt` in `ClientWarehouseLocation` queries and response handling.
- [ ] Update `ApplicationCurrency` key handling to include `CurrencyId`.
- [ ] Review `ClientSupplierInfo` consumers if they rely on `Id` being present in the property list instead of only in the entity key.
- [ ] Verify that `ApplicationSalesAreas` logic still works now that the result is scoped to the requested application.

## Products namespace

- [ ] Remove `$expand=Accessories`, `Upsell`, `CrossSell`, and `VariantTypes` from `Product` queries.
- [ ] Replace usage of `ProductVariantType` and `ProductVariantTypeCulture` with `ProductParametrics` where `IsVariantType = true`.
- [ ] Remove or replace integrations that query `SupplierProductSkuInfo`.
- [ ] Update `ClientProductSkuPriceListInfo` key handling to include `Id`.
- [ ] Update `ClientProductSkuBestPrice` key handling to include `Id`.
- [ ] Update `ProductParametricCulture` key handling to include `CultureCode`.
- [ ] Update `ProductPopularity` key handling to include `Id`.
- [ ] Remove any `VariantCulture` key handling that still treats `ClientId` as part of the key.

## Reporting namespace

- [ ] Identify any usage of the removed `Reporting` namespace and define a replacement approach.

## Shopping namespace

- [ ] Update `ApplicationPaymentMethod` key handling to include `PaymentServiceId`.
- [ ] Remove queries against `RecurringOrder` in the `Shopping` namespace.

## Orders namespace

- [ ] Remove queries against `WarehouseTransaction` and `WarehouseTransactionItem`.
- [ ] Remove queries against `PurchaseOrder` and `PurchaseOrderItem`.
- [ ] Adopt `Order.TmsReference` if the integration needs transport management system reference data.

## Customers namespace

- [ ] Remove queries against `CustomerCompanies` in the `Customers` namespace. Use `Companies` instead.

Further reading

• Calling the Norce Commerce Query API
• Norce Commerce Query API Reference
• Norce Commerce Query API Reference v 3.0 (link not yet provided)