• Internal Usage Metrics enhancements

• Infrastructure enhancements

• Issue related to anonymous tokens

• Resolved loophole that allowed a Subscription Integration and OrderCheckout Integration to be used on the same API client

• Resolved issue resulting in 500s related to requesting refresh tokens

• Performance enhancements for product sync

Fixed

• Intermittent 500 on updating a payment on a Subscription

• Group Ordering capabilities are now in beta

  • Allow multiple people to add items to a single order using order invitations to generate tokens

  • Subject to change based on customer feedback

• HTTP Delivery Targets now support custom headers

Fixed

• Payments on Subscriptions can now be updated

• MeSubscriptionAdmin is no longer required to view Subscription Items

• OrderReturnResponse now accepts xp. If you need to update OrderReturn.xp based on your calculations in middleware, send the entire xp object back to OrderCloud to be updated.

• Minor additions to the OpenAPI spec

Fixed

• Unhandled error when attempting to delete a Subscription Order

• Defining a custom authorization header is now supported on Webhooks, Promotion Integration and Subscription Integration

  • New Properties: CustomAuthHeaderName and CustomAuthHeaderValue

  • The header can be used as an alternative to HMAC validation (using the HashKey) in the event your consumer only supports authorization header validation

  • Used to to verify that any request sent to your webhook can be trusted and is from OrderCloud

Fixed

• Unexpected error related to deleting a lineitem on a submitted order

• Indexing issue with child products when unassigning a parent product from a catalog

• Integration event PATCH causing authorization header to be removed

• Unexpected error related to deleting a bundle item on an order

• Performance enhancements to product sync

• Defining a custom authorization header is now supported on Integration Events (OrderCheckout, OpenIDConnect, OrderReturn, AddToCart)

  • New Properties: CustomAuthHeaderName and CustomAuthHeaderValue

  • The header can be used as an alternative to HMAC validation (using the HashKey) in the event your consumer only supports authorization header validation

  • Used to to verify that any request sent to your webhook can be trusted and is from OrderCloud

  • Custom authorization headers on webhooks and other outbound events coming soon

Fixed

• Erroneous UserID Properties removed from OpenAPI spec assignment models

• Promotion Integration

  • As powerful as the Rules Engine is, you may sometimes have a use case that is too complex to solve using the properties and functions accessible within an expression, enter the new Promotion Integration.

    • Continue to leverage all the flexibility and built in validation of Promotions, such as expiration dates, redemption limits, and eligibility

    • When it comes time to apply the discount, if the order is eligible, OrderCloud will call out to your predefined middleware for discount information.

• Resolved an issue that was intermittently causing stale data on LineItems immediately after order submit

• Ad-hoc Products Expansion. Ad-hoc products can now be used in conjunction with Products in OrderCloud.

  • When you call to add a product to an order, if you have the AddToCart integration event enabled, we will first check to see if the product exists in OrderCloud and add it to the order if so, if not, we will then call out to your middleware for the Product information.

Fixed

• Issue where LineItem.PriceOverriden was being set to true unexpectedly is now resolved.

• Beta flag allowing us to release features for testing and feedback

  • Features in beta will be clearly labeled in the portal and the SDK method descriptions

  • Features in beta will not be available in production, a 403 error will be returned

• Inventory Integration

  • Send Inventory Changes to the Delivery Target(s) of your choice

  • Ability to send every change or only changes where the NotificationPoint is hit

  • QuantityAvailable and PreviousQuantity will be included in the payload

  • Use this feature for things like alerting purchasing managers to re-order a product, or back-in-stock notifications for customers

• New Properties on Product Collection Entries: DateAdded (read-only) and ListOrder

  • Useful for sorting collection entries

  • New endpoint POST v1/productcollections/{productCollectionID}/products

    • Include ProductID and ListOrder (optionally) in the request body

• Performance enhancements to promotion evaluation

Fixed

• Subscription Integrations are now disabled when restored to Staging

• Define multiple cryptographically secure ClientSecrets on a single API Client

  • Existing ClientSecrets will continue to function normally, but we highly encourage transitioning to the new methodology to stay aligned with security best practices

  • New model and endpoints explained in more detail here

Fixed

• Issue has been resolved where InventoryRecords were not found when the user making the API call to add a line item was not the Order.FromUser

• NotificationPoint added to InventoryRecords and Variants to support an upcoming inventory integration feature

• Performance enhancement to listing promotions

• Token Revocation

  • Existing user tokens are now revoked automatically when a user is deactivated or the user's password is reset

  • A user's tokens can now be explicitly revoked through new endpoints for admin, buyer, and supplier users

    • DELETE v1/adminusers/{userID}/tokens

    • DELETE v1/buyers/{buyerID}/users/{userID}/tokens

    • DELETE v1/suppliers/{supplierID}/users/{userID}/tokens

  • Additionally, a user can revoke their own tokens without needing an elevated role by calling DELETE v1/me/tokens, which is functionally equivalent to a "sign me out of all devices" feature

• The maximum duration of the refresh token has been extended from 43200 minutes (30 days) to 524160 minutes (364 days) to accommodate client applications that desire longer periods of inactivity before forced logout (e.g. mobile applications, shopping sites). Use token revocation as described above to require a new login

• EntitySync now has properties, SyncEntityChanged and SyncEntityDeleted, to allow disabling incremental syncs for changes and deletions, while maintaining the ability to run a manual sync (similar to ProductSync)

• Listing Eligible Promotions now returns an Amount, which is the discount amount that would be applicable if the promotion was applied to the order

• Entity Sync now supports Buyer companies and UserGroups

• Password Configuration now supports a LockoutDuration of 0. If a user has exceeded AllowedFailedAttempts and LockoutDuration is 0, a manual intervention via the API will be required in order to allow the user to try again.

  • The new routes each require the Admin role specific to the user type.

    • POST v1/buyers/{buyerID}/users/{userID}/unlock

    • POST v1/adminusers/{userID}/unlock

    • POST v1/suppliers/{supplierID}/users/{userID}/unlock

• Performance enhancements to querying Inventory Records

Fixed

• Promotion calculation bug when multiple promotions applied

• Issue related to child product xp inheritance on the Order Worksheet when certain special characters are present

• Enhancements to internal usage metrics

• Infrastructure clean up

• Updates to internal usage metrics reporting

• Infrastructure changes to support enhanced data security features

• Promotion bug related to items.discountedtotal function released yesterday

• Preventing a bad expression from being used with any() function in a Promotion

• Gratuity has been added the Order model

  • An optional non-negative decimal

  • In addition to gratuities/tips, it can be used for donation based or pay-what-you-wish (PWYW) orders

• A new Rules Engine expression items.discountedtotal was introduced to take into account discounts on already applied promotions when applying a new promotion.

  • This can be useful in scenarios where you allow stacking discounts and want to calculate additional discounts off the discounted price.

Fixed

• Minor ProductSync bugs

• Promotion issue when using the incategory function when multiple promotions were applied

• Product caching issue after an associated PriceSchedule was deleted

• Resolved an issue in ProductSync related to inventory

• QuantityLimitPerOrder added to Promotions. When defined the ValueExpression will be the discount applied to each qualifying quantity of eligible line items. More details here

• EntitySync now includes InventoryRecords that allows you to configure OrderCloud to transmit inventory record updates to your integrations via the delivery target of your choice. For performance reasons, InventoryRecords will not be sent in any newly created ProductSync configurations, existing configurations are not impacted. Product level Inventory (not associated with an InventoryRecord) will still be included in ProductSync

Fixed

• Resolved an bug related to assigning child products to categories

• RedemptionLimitPerUser is now only counted against orders that have been submitted and are in the Open or Completed status.

• Fixed a bug that allowed an ItemLevel promotion to be created without the item token in the EligibleExpression

• Promotions can now be added or removed from orders by users with OrderAdmin after submit

• Subscription NextOrderDate will no longer increment one hour ahead each time it processes

• ApiClients associated with a webhook can now be deleted, was throwing a 500 prior to the fix

• Rules Engine item.incategory() now works for child products assigned to categories that their parent is not assigned to

• Variant information was missing from LineItems if variants had been regenerated, current information will now be populated as long as a variant with a matching ID exists

• Custom pricing (sale, subscription, bundle) was being miscalculated in certain scenarios, including when changes were made to a price schedule after a lineitem had been created.

• Child Products can now be assigned to their own categories.

  • The Parent Product must be assigned to the catalog that the category exists in.

Fixed

• 500 error on PUT v1/cart

• One time Addresses on LineItems were being overwritten on submit in certain cases

• Supplier pricing bug where product price was inaccurate in the cart

• Bidirectional Content Hub Integration

  • Support to sync product data between Content Hub and OrderCloud, see documentation for detailed configuration information.

  • Integration between OrderCloud and Content Hub creates a product shell in Content Hub in your specified schema any time a product is created in OrderCloud. The intent of this integration is to allow seamless editing of product content if you create products in OrderCloud. No additional product changes/updates in OrderCloud will be synced to Content Hub, the integration is only meant to create a record in Content Hub for you.

  • Integration between Content Hub and OrderCloud tracks changes to three properties you define as a unique ID, Name and Description on your Content Hub model. These properties mapped to OrderCloud’s Product.ID, Product.Name, and Product.Description will be kept up to date with the values in Content Hub. The integration will also give you the option of syncing flat properties to OrderCloud’s Product.xp (non multi-language/taxonomy fields), and will also sync Content Hub asset Public Links to OrderCloud’s Product.xp.Images as an array of objects containing URLs for the Original, Thumbnail and Preview - depending on the configuration of the assets' public links.

Fixed

• Fixed an issue with auto apply promotions not being added correctly.

• Two new properties on Promotion:

  • Can only be used on Promotions where LineItemLevel is true.

    • ItemLimitPerOrder

      • Positive integer that defines the maximum number of items a given promotion will be applied to

    • ItemSortBy

      • Comma delimited string of line item properties

      • Sort descending by using !

      • Supports sorting on xp

      • If no value is provided, items will be sorted by the default value which is DateAdded ascending

  • Sample use case: 30% off the least expensive 3 items if a user spends at least $50

{
  "Code": "30OFF",    
  "LineItemLevel": true,
  "ItemLimitPerOrder": 3,
  "ItemSortBy": "LineSubtotal",
  "EligibleExpression": "order.Subtotal >= 50",
  "ValueExpression": "item.LineSubtotal * .3"
}

• New Rules Engine function inparentcategory('{categoryID}')

  • checks the category tree for any products assigned to the category specified or any of it's children, at any depth

Fixed

• Resolved a bug that prevented Subscription Reminders from being sent in the future if a Subscription failed to process

• Throw a helpful error if a webhook URL doesn't begin with HTTP

• Provide more helpful error data on certain promotion errors

• Recipient Locale and BuyerID are now populated in Message Sender payload.

• Order Validate and Submit now throw an error, as expected, when an item that is no longer purchasable is on the order. This includes things like inactive products, products no longer assigned to catalogs, etc..

• Prevent setting IsAnonBuyer = true on an API Client where a Seller User is set as the DefaultContextUserName, and vice versa.

• The delivery configuration flag is now honored when it is disabled. All existing delivery configurations have been enabled when releasing this fix in order not to break any existing functionality.

• Resolved incorrect promotion discount amount when percentage off promotions that include either order.PromotionDiscount or item.PromotionDiscount in the value expression are combined on an order.

New

• Performance enhancement making it less likely for one marketplace's product updates to delay updates performed by other marketplaces.

• The rules engine now supports an ifs() function.

  • This can be used to support evaluation of tiered threshold discounts. For example: spend $10 on Category A get 5% off, spend $30 get 10% off, spend $50 get 15% off would be written like this:

    • EligibleExpression: "items.total(product.incategory('A') >= 10 and item.product.incategory('A')"

    • ValueExpression: "ifs(items.total(product.incategory('A')) >= 50, item.LineSubtotal * .15, items.total(product.incategory('A')) >= 30, item.LineSubtotal * .10, item.LineSubtotal * .05)"

  • The final parameter in the function is the fall back (think of it as default in a switch statement, or an else) that is used if none of the conditions are met, in this case, we included the minimum spend in the eligible expression, so the fall back is a 5% discount.

• The category "active" property was added to the published ProductSync schema.

• The impersonation access token duration has been updated to either 60 minutes, or the length of the token duration of the API Client impersonation is configured with, which ever is greater.

• Delivery configuration introduces a new delivery target for Cosmos DB.

• Promotions owned by the Marketplace Owner can now be applied to orders where a Supplier is the ToCompanyID

Fixed

• Resolved a bug that did not allow an order to be forwarded again after deleting a forwarded order.

• Filters are now being evaluated correctly when calling GET v1/me/products/{productID}/sellers

• Delivery configuration introduces a new delivery target for Azure Tables.

• The AzureBlob delivery configuration target now allows you to override the default container name.

• The OIDC state token is now valid for 15 minutes instead of five

• LineItem.ShipFromAddressID can now be set to a Supplier Address

• EntitySync now supports synching Suppliers to the delivery configuration of your choice.

Fixed

• Prevent a 500 if a null value is passed into the LineItem.Specs array

• EntitySync now supports synching Admin, Buyer and Supplier users.

• Message Senders now have an AllowAllBuyers property which allows you to forgo explicit message sender assignments. Helpful in marketplace with many buyers who all need to receive the same emails

  • defaults to false

Fixed

• Bug that inadvertently removed supplier specific product assignments has been resolved

• Reversed a change made in v1.0.326 that incorrectly limited xp characters on integration event responses

• Child Products

  • Now supported in ProductSync.  IsParent and ParentID properties added to payload.  Children are published with full inheritance.

• DateCreated now available on Subscriptions

Fixed

• IntegrationEventResponse is now enforcing the documented limit of 8000 characters on xp

  • On 03/13/2024 it was determined this limit was not valid, it was removed it in v1.0.327

• EntitySync

  • OrderCloud introduces the ability to publish base entities to the destination of your choice.  You will be notified when the entities are created, updated or deleted via any of the configured delivery targets.

  • The current release allows you to synchronize categories, with many more entities in the near future.  This is just the beginning.

• New endpoint and MessageSender: ForgotUsername

  • POST v1/username/retrieve allows users to retrieve forgotten usernames by providing an email address if the corresponding message sender is setup

  • This addition will result in a breaking change to the SDKs only as we are consolidating forgotten passwords and forgotten usernames under ForgottenCredentials

• Marketplace owners can now create explicit product assignments for suppliers with price schedules they own

  • correct pricing should also now be returned on product list calls when defining a sellerID even when that seller does not own the price schedule

Fixed

• prevent a 500 from occurring when attempting to make a call as a deleted user

• New properties on Lineitem OutgoingOrderID and IncomingOrderID

  • Only populated for Marketplace Owners, filtering is supported

  • This property will allow a marketplace owner to easily determine which orders a given lineitem is associated with

• Child Products now inherit Parent Product properties on Lineitem.Product

Fixed

• Removed an erroneous error when attempting to add a lineitem to an order that had an invalid promotion applied.

  • Validate and Submit will still throw errors for this invalid promotion, we just no longer prevent the new lineitem from being added

• Fix for Message Senders not triggering when Message Sender xp is null

• Added better error responses for OIDC issues

• IsOnSale

  • Now exposed on LineItems. This will allow you to reference the property in rule engine expressions for Promotions and ApprovalRules

  • Can now be filtered on when listing PriceSchedules

• A new ErrorConfig endpoint Validate allows configured error destinations to be tested to ensure they are properly configured. Invoking this endpoint will send a test message to the configured destination.

• Removed RedemptionCode from SpendingAccount model to avoid confusion. This value did not control any behavior in OrderCloud and was not being used by any customers.

Fixed

• Inventory Records now work correctly with variants when VariantLevelTracking is false at the product level

• An error is now thrown if you attempt to apply a promotion to an order that is not awaiting approval or unsubmitted

A Delivery Configuration ID can now be assigned to Message Senders providing you the ability to publish these messages to the destination of your choice.

• Added routes to Cart API for setting and updating one time shipping and billing addresses

Fixed

• Listing promos before cart exists now returns an empty list page instead of null values

• QueryParams object added to all webhook JSON payload bodies

• Error configuration allows you to define a marketplace level delivery configuration which will deliver customer specific errors regarding asynchronous operations (such as Product Sync and post web hooks) to the custom delivery target of your choosing.  A great debugging tool when setting up a marketplace with asynchronous integration endpoints.

• BuyerID is now optional on ImpersonationConfigs. Omitting the BuyerID from the config will allow the impersonating user to impersonate any buyer user within the marketplace.

• customParams passed into ocrplogin endpoint for OIDC will now be persisted through the login process and passed to your SyncUserIntegrationEvent.

• All Webhooks have been migrated to use https if they were not already doing so.

Fixed

• An anon user would receive a 204 response when calling to transfer an order, even though the transfer failed because that is not a supported workflow. The call now returns a 403 as expected.

• Redirects are now disallowed on Webhooks

• Marketplaces with Premium Search for Orders enabled can now reference orderhist and itemhist in Rules Engine expressions on Promotions and Approval Rules

  • Examples
    User has placed more than four orders in the past year
    EligibleExpression: orderhist.count('1Y') > 4
    User has ordered a given product 10 or more times in the past 6 months
    EligibleExpression: itemhist.quantity('6M', 'Product.ID = {productID}') >= 10
    Give 1% of the total value of all orders placed in the past month as a discount
    ValueExpression: orderhist.total('1M') * .01
    

Fixed

• Unsubmitted orders with the status of Canceled were inadvertently being excluded from the nightly Unsubmitted Order Cleanup

• New endpoints to support adding Product Bundles to subscriptions

• Ability to use LineItem.Product.Inventory properties in rule expressions for promotions and approval rules

• We’re excited to present a new, often requested, feature: Product Bundles. This feature can be used in a variety of ways to help customers achieve their ecommerce goals.

  Possible Use Cases

  • I need new employees to purchase uniform bundles, I want to provide the products in the bundle at a discount and ensure they are purchasing a minimum quantity of each item.

  • I want to cross-sell complementary beauty products, so I create a bundle consisting of two or more products that are commonly used together at a slightly reduced price.

  • I know people buying video game consoles also likely need other equipment, to entice them to buy all of the items at once, I need a bundle that includes a console, headset, and choice of game.

Fixed

• Resolved a bug that resulted in a 500 when attempting to PATCH a cart that had not yet been created on the OC side

• Search 2.0 is now supported via the SearchIngestion Delivery Configuration. This can be used in conjunction with Product Synchronization.

• Azure blobs is now supported via the AzureBlob Delivery Configuration.

• PUT v1/me/orders?anonUserToken={anonUserToken} now supports transferring an order to a buyer user belonging to a different buyer than the anonymous user

Fixed

• Resolved a bug caused by attempting to delete a product, or supplier address associated with an InventoryRecord

• Throw a friendly error when ShipEstimates is empty and an attempt to set ship methods is made

• Now populating Variant and Price Schedule information on the lineitem when the item is created after the order has been submitted

• Throw a friendly error when too many concurrent requests are made to an integration event

Order Synchronization allows you to synchronize your orders with the associated Delivery Configuration mechanism of your choice. This way, you will be notified anytime an order is submitted and of any changes it incurs in the future. 

Update

Webhooks can now be optionally configured to use the Delivery Configurations. This allows you to delivery their payloads to the delivery configuration mechanism of your choice.

• Added ParentID to LineItem.Product

  • Please note, this value will not be populated on orders submitted prior to this release.

Fixed

• Removed URL unsafe/reserved characters from password reset verification code

• GET v1/integrations/subscription now returns a 404 response instead of a 204 (No Content) response when the Subscription Integration does not exist for the selected marketplace

Product synchronization allows you to synchronize your catalog content with any system of your choosing using the pre-defined delivery mechanism that best suits your needs.

• The Http delivery target requires that a Secret be passed when it is configured. You should update any existing Http delivery target you have configured. Your existing Http targets will continue working as it is not an internal breaking change. Please refer to the Delivery Configuration for more information on the usage of the secret,

• An endpoint to allow listing product pricing for multiple sellers in a single API call: GET v1/me/products/{productID}/sellers

Fixed

• Buyer ID is now optional when creating a shipment to allow Suppliers to create shipments on AutoForwarded orders when they don't have the Buyer ID

• Added some missing endpoints for variant level inventory records

Delivery Configuration is a new way you configure the location of certain types of messages within the context of OrderCloud. These can include Known and Custom locations.  Custom locations allow you to have 100% control over the integration and allows you to deliver these messages to either an Https endpoint, Event Hub Namespace or a Kafka cluster.

Changed

Currently this new feature is leveraged by Tracking Events which has been modified to leverage Delivery Configurations.

• We first introduced ProductCollections just over a year ago, and we're excited to share we've added new functionality to support additional use cases beyond private lists of products. Adding new endpoints and a new AccessLevel property allows greater flexibility in the implementation of ProductCollections in your marketplace.
  Here are just a few ideas of how you could use the expanded functionality:

  • Marketplace Owners and Suppliers can now view ProductCollections with the ProductCollectionReader role allowing insights into which products customers are saving to their collections.

  • Allow a customer to create a grocery list and invite someone in their household to view and administer the items on it.

  • Encourage customers to make Sharable Holiday Wish lists for family members.

• Read more about the new functionality here.

• As announced last week, we are now enforcing that all Webhook Urls start with HTTPS on POST/PUT/PATCH. This will not impact any existing Webhook Urls unless you attempt to change them. We have communicated with customers who are not using HTTPS to give them an opportunity to update those and make any necessary changes before we begin enforcing the pattern on existing Urls.

Fixed

• Fixed a bug where calling POST v1/orders/{direction}/{orderID}/calculate was causing promotions to be recalculated incorrectly.
  

Please let us know if you have any questions. 

• New in() function added to the Rules Engine

Fixed

• Fixed an issue where auto applying promotions was failing after adding a lineitem.

• Promotions: expression evaluation will now take into account existing discounts when referencing item.LineTotal or Order.Total

• Subscriptions: order worksheet is now updated prior to sending to middleware

• New read only property DateApplied returned on the Promotion resource when listing promotions on an order

• New contains() method added to the Rules Engine

Fixed

• Fixed an issue where incorrect error was returned after attempting to set UnitPrice on subsequent lineitem PUT requests

• Fixed an issue with child/parent product visibility inheritance

This feature changed significantly in v1.0.293. Please see new release notes along with updated documentation.

OrderCloud introduces Tracking Events for commerce solutions, offering analytical insights and infrastructure for targeted systems. For more information, see Tracking Events

New Resource

TrackingEvent

{
  "ID": "",
  "EventType": "UserLoggedIn" | "LineItemAdded" | "LineItemUpdated" | "OrderSubmitted",
  "ClientID": "",
  "Name": "",
  "ConfigData":""
}

New Endpoints

• GET v1/integrations/TrackingEvents

• GET v1/integrations/TrackingEvents/{id}

• POST v1/integrations/TrackingEvents

• PUT v1/integrations/TrackingEvents/{id}

• PATCH v1/integrations/TrackingEvents/{id}

• DELETE v1/integrations/TrackingEvents/{id}

For more information, see Tracking Events API Reference

There were no changes to the OrderCloud API, this was mainly in support of Portal 1.0.35

• Prevent message senders from sending to inactive users

Changes

• Tweaks to checkout integration event (currently used in-house only)

• Buyer and Supplier users will be able to read Seller owned resources (users, addresses, groups) with the proper role(s).

• Buyer and Supplier users will NOT be able to admin Seller owned resources regardless of role(s).

• Buyer and Supplier users will NOT be able to delete or create any Buyer or Supplier orgs regardless of role(s).

• Buyer users will be able to read Supplier orgs, users, addresses, or groups with the proper role(s).

• Buyer users will NOT be able to admin Supplier orgs, users, addresses, or groups regardless of role(s).

• Buyer users will NOT be able to read or admin other Buyer orgs, users, addresses, or groups regardless of role(s).

• Buyer users will be able to read and admin their OWN Buyer (deletion will be prohibited as outlined above) with the proper role(s).

• Supplier users will be able to read Buyer orgs, users, addresses or groups with the proper role(s).

• Supplier users will NOT be able to admin Buyer orgs, users, addresses, or groups regardless of role(s).

• Supplier users will NOT be able to read or admin other Supplier orgs, users, addresses, or groups regardless of role(s).

• Supplier users will be able to read and admin their OWN Supplier (deletion will be prohibited as outlined above) with the proper role(s).

• /v1/integrationevents/*

• /v1/orders/{direction}/{orderID}/estimateshipping

• /v1/orders/{direction}/{orderID}/shipmethods

• /v1/orders/{direction}/{orderID}/worksheet

• /v1/orders/{direction}/{orderID}/calculate

• ApiClient.IntegrationEventID

• OpenIDConnect.IntegrationEventID

/split and /forward both return a response that looks like this:

{
    "OutgoingOrders": [ ... ],
    "RemainingLineItemIDs": [ ... ]
}

Specifically, this release introduces Supplier-Owned Products and Catalogs.

• New property on both Product and Catalog: OwnerID. This is the ID of the organization (Seller or Supplier) that created the Product or Catalog. Read-only. Potentially useful to Sellers as a list filter. NOT visible to Buyers via /me endpoints.

• Sellers can see all Supplier-owned Products and Catalogs in their network, but cannot edit them.

• Sellers can assign Supplier-owned Catalogs to their Buyers in their entirety.

• Sellers can cherry-pick Supplier-owned Products to add to their own (Seller-owned) Catalogs.

Note that this is a redo of release 1.0.99, which included the items above but was rolled back due to performance issues. The cause of those issues has been identified and corrected.

• We had a couple of issues where, if an admin user updated something on the Seller side, the change was not immediately reflected when a buyer user used the buyer (me) endpoints. This has now been resolved.

  • Price Schedules was affected, but prices should be reflected in buyer endpoints much more quickly.

  • Product Inventory Quantity was also affected, but should be fixed.

• The maximum results that List calls can return on one page is 100. (PageSize=100) However, we realized we had a couple endpoints that were allowing 1000 results per page. We have closed this loophole, particularly for GET v1/products/assignments.

Features

• We did some back end refactoring of Search 2.0 to improve performance and reliability, particularly around the use of complicated logic filters for values.

me/products?Description|Name=*vol* will now return products with VOL, Vol, or any other case permutation in the Product Description or Product Name.

As this is a Search 2.0 related item, you will only see a different if your application is using Search 2.0. Search 2.0 is only enabled on the me/products endpoint as well.

Filter names continue to be case-sensitive, as they are properties of the product. Using me/products?description|name=*vol* will return nothing, as those are not properties.

• Added Multi-Field OR filters to me/products endpoint for Search 2.0 enabled orgs.

Updates

Multi-Field OR Filters On Me/Products & Search 2.0 Orgs

Previously, with filters there was no way to specify multiple fields and get results back when any match. This is now supported with syntax like:

me/products?ID|Name|Description=*foo*

This will return any product with foo in the ID, Name, or Description. This functionality is currently limited to the me/products endpoint in orgs with Search 2.0 enabled. We're hoping that this will facilitate ease of transfer to the new search platform.

Note that field names are case sensitive!

Several bug fixes and performance improvements, for apps using both the basic search, and Search 2.0.

Bug Fixes & Performance Improvements

• Previously, the Create/Patch/Update User webhooks were passing the user's password, if present, in the clear. This has now been redacted, as is our policy across the board.

• We have make some changes to our product cache loading in order to improve performance for product listing and related endpoints. This affects non-Search 2.0 enabled buyers only.

• For Search 2.0 enabled buyers, we did some performance improvements around GET me/products, specifically around improving performance on searches that use XP extensively.

Several bug fixes and performance improvements.

Updates

Variants & Variant Inventory

We've expanded Variant functionality! Variants are used to create versions of the same product that have different specs. For example, one product might have three different sizes available, small, medium, or large. Rather than have three different products, variants allows you to have one product with different arrangements of specs. Specs can also be open text entry, or include a markup. We've expanded variants to allow for variant-level inventory tracking.

You can now:

• see variant information for products on a line item or shipment sub-object

• track inventory at a variant level

• write custom variant ids

• write shipping size/weight information at a variant level

Bug Fixes & Performance Improvements

• We've reduced latency around product catalog changes.

• We've fixed an issue where you could have a supplier and a non-supplier user of the same username. All user names should be unique within an organization.

• Setting a product's DefaultSupplierID without an assignment between that product and the supplier is somewhat nonsensical. Now, creating or updating a product's DefaultSupplierID creates an assignment if missing.

Several bug fixes and performance improvements.

Updates

Search 2.0 Beta

We've gotten some more feedback from our beta group about what they want in this new Search, and we've changed some of our search weighting accordingly.

• We have severely reduced fuzziness in an effort to return fewer, more relevant results. Fuzziness is aimed at improving natural language type search queries, and in a B2B context, frequently customers know exactly what they want, rather than a more general query.

• In queries where a user is searching on multiple fields, we were seeing partial matches from fields earlier in the list rising above exact matches from fields later in the list. We've changed up the weighting on these to favor more exact matches.

Bug Fixes & Performance Improvements

• We've reduced latency around product catalog changes.

Several bug fixes and performance improvements.

Updates

ForgottenPassword Message Sender For Supplier Users

What Is It? You can now specify a Supplier in the ForgottenPassword message sender assignments. This allows Supplier Users to reset their passwords using the Forgot Password endpoint. Remember, you also have to make sure that the API Client you want to use allows Supplier Commerce Access!

How Does This Affect Me? This only affects you if you're using the Suppliers feature, and want Supplier Users to be allowed to reset their passwords.

Bug Fixes & Performance Improvements

• We know some of our users have experienced issues Filtering by Date on XP recently. For example, the filter xp.RequestedDeliveryDate>2018-01-19 on a Shipment list call would return an empty list, rather than the expected shipments. This turned out to be related to a Json.NET quirk around date vs. string formatting. We've fixed this going forward, but existing XP indices will not automatically work. If you have an index that is affected by this issue, you will need to drop and recreate the affected XP index. The XP itself saved on whatever product, shipment, etc is fine. Only the XP index will need to be recreated. Remember, you can index XP in the Dashboard, under "Extended Properties" on a Seller Organization detail.

• OrderCloud was experiencing some slowness recently around product-related calls in complex catalogs. We made some improvements around this process.

Release consisted of minor bug fixes and performance tweaks.

Summary

This release consists of both a new API version, v1.0.85, and an update to our DevCenter site. We are reorganizing our conception of what an 'application' is around API Client IDs. This release contains the beginning of that process, supplier-related improvements, and other performance improvements, bug fixes.

Updates

API Client Unification

What Is It?

We've replaced the idea of Buyer Networks, Buyer Apps, Seller Networks, and Seller Apps with, instead, just the API Client ID. Instead of talking about multiple apps with API client IDs attached to a Buyer, we now have multiple API Client IDs with a Buyer Commerce Role.

Why Is It Important?

When you create a Seller API Organization in OrderCloud, you are creating a little world where data like products, users, and other concerns can be shared and configured in various ways. Within this little world, there might be many applications, such as the app where your CSR users log in to manage bulk orders, the app where the general public can buy your most excellent product, or an app where your users can buy things from your company, and you can then buy those products from other supplier companies.

The base unit of this world is the API Client ID. This ID identifies what context a user is authenticating into. For example, Allison may be one of your CSRs, but she also manages your product catalogs in a catalog management application. When she logs in, the different API Client IDs used in her authentication set the context that she is working in, and what data she has access to.

How Does This Affect Me?

This change should not impact your existing API organizations and API Client IDs/apps. All existing applications have been migrated to the new API Client ID + Commerce Role Access schema. The Commerce Roles are made up of the three distinct user types that exist in OrderCloud-- a Buyer User, a Seller User, and a Supplier User.

However, when you log into the OrderCloud Portal, you will immediately notice the difference.

When you go into DevCenter and view one of your Seller Organization, you'll now see API Clients in the side menu rather than seller applications/buyer organizations/buyer networks.

Under API Clients, you'll see all of those applications listed by API Client ID. Each will have the assigned commerce role accesses displayed as well.

What will likely be the most common is having one Commerce Role assigned to an API Client ID. This would be the typical situation of having one application for your admin users to manage orders, catalogs, etc, and one for your buyer users to log in and make orders, etc.

However, perhaps you want to have one web page, one application where both your buyer users and your admin users can go. One API Client can have multiple commerce access roles to accomplish this.

When your admin user authenticates, the front-end application will show the admin different options than your buyer users will see. This puts the onus of separating functionality visibility on the UI, likely checking user security roles to show or hide functionality.

Notably, you can assign all buyers in a Company Organization to an API Client ID, or only specific ones.

Finally, you can assign a Default context user to an API Client ID. This defines a user that acts as a template for client credential access to the site. The template user sets what security profiles and things like addresses, products, etc that an unauthenticated user will have access to. This allows things like anonymous shopping, or a back-end integration to update your product catalog.

Please note, assigning a default context user to an API Client that has multiple buyers, seller, or supplier accesses assigned to it allows access to all assigned seller, buyer, or suppliers. Thus, you can create an API Client ID with a seller, buyer, and supplier access and a default context user, but you really probably shouldn't, unless you really really want that Default Context User to be able to have access, however limited, to all your buyer, supplier and seller information.

Supplier ID on Me Buyer-Endpoint

What Is It?

When a user performs a buyer-endpoint ME GET call, the Supplier that the user has access to will be returned in the response body.

Why Is It Important?

If you use Suppliers within your applications, being able to identify which supplier a user has access to without giving extra permissions to a user is helpful.

How Does This Affect Me?

This will be present on all /me response bodies but will be null unless the user has access to a supplier.

Search 2.0: Faceted Navigation Allowed to Return up to 50 Facets

What Is It?

Pretty much what it says on the tin, the facets returned on a [me/Products]'s response body can number up to 50. If you have more than 50 facets that apply to a user, the first 50 will be returned, based on listing order.

Why Is It Important?

This was requested by several of our Search Beta users, as it allows them to give their users a more detailed faceted navigation filtering experience.

How Does This Affect Me?

This will only affect you if you are using our Search 2.0 beta, and you have a number of facets > 50.

Bug Fixes

• Minor bug fixes.

Performance Improvements

• We included some more aggressive clean up of product caches for searching.

This release consists of performance enhancements and some minor model additions.

Updates

SupplierID added to LineItems

What Is It?

We added a read-only property to LineItems that shows the SupplierID if the LineItem inherits one.

How Does This Affect Me?

If your Product Catalog pre-defines Suppliers that a product comes from, you'll be able to see this information on Order LineItems. This may be useful to visually group or otherwise distinguish line-items by their shipping location.

Add AllowResubmit to Order Approval

What Is It?

We've added the ability to allow users to resubmit an order for approval.

Why Is It Important?

If you use Order Approvals, you can run into situations where if the user just changed one little thing, it'd be an approved order. Maybe the buyer wanted 100 jars of bees by Tuesday, but you won't be able to fulfill the order that quickly. If the user gave you a little more time, they could get all 100 jars, or they could settle for the 60 jars you have in stock right now. With AllowResubmit, you can allow users to resubmit an order after making the necessary changes, rather than make them build up a whole new order and check out again.

How Does This Affect Me?

If you use Order Approval workflows, this could be very handy! As long as the order hasn't been submitted, you can go back and forth as long as you want with a user on an order.

Bug Fixes

• You should see some better performance and reliability around Product Cache rebuilds. Product Cache rebuilds happen the first time a product listing endpoint is hit after Product Catalog changes have occurred, and previously, sometimes concurrent rebuilds could cause a log-jam.

This release consisted of bug fixes for outstanding issues and some performance enhancements.

Bug Fixes

• Anonymous Session Conflicts leading to 404 Order Not Found. This ended up being a tricky timing session bug to pin down, but is now fixed.

This release consisted largely of some enhancements to the Search 2.0 beta, based on internal beta group feedback.

Updates

Search 2.0 Beta: Fuzziness

What Is It?

{{image}}o8B5NqP2y0GyJPbNu3eBmA{{image}}

Haha, no, we did not add adorable soft kittens to the search results. Instead, we added fuzzy matching.

Why Is It Important?

Search 2.0 already looks for natural English-language stemming, but fuzzy search allows for common errors as well. Did your user search for "elctric" when they meant "electric"? Adding fuzzy matches improves the quality of the search results.

How Does This Affect Me?

Search 2.0 enabled applications should see some improved search results, particularly around misspellings and common errors.

Search 2.0 Beta: Changes to Facet Lists' Meta Info

What Is It? We made some changes to the way that Facet Meta information is presented in the resulting JSON object from a me/products call in a Search 2.0 enabled application.

Why Is It Important? These changes were made after some feedback from our internal beta group, who found that Facet.ID was unhelpful, but knowing Facet.XpPath would be helpful when using these results to build Faceted Navigation.

How Does This Affect Me?

You will see the following Meta body if using Facets with Search 2.0 in your application:

{
    "Meta": {
      "Facets": [
        {
          "Name": "colors.spring",
          "XpPath": "colors.spring",
          "Values": [
            {
              "Value": "680947636313",
              "Count": 20
            },
            {
              "Value": "107259688976",
              "Count": 16
            }
          ],
          "xp": {}
        },
        {
          "Name": "job",
          "XpPath": "job",
          "Values": [
            {
              "Value": "107259688976",
              "Count": 16
            }
          ],
          "xp": {}
        }
      ]
    }

Additionally, Facets themselves now carry their own XP information, just in case.

Bug Fixes

• Facets were not showing up in the Swagger Spec

• We now throw a better error if a user attempts to access Search 2.0 endpoints from an application that does not have Search 2.0 enabled.

Updates

TLS 1.2 Enforced On All Traffic

What Is It?

A minimum of TLS 1.2 will be enforced on all inbound traffic to OrderCloud, as well as on all outbound traffic from OrderCloud, such as webhooks.

Why Is It Important?

TLS 1.2 is the latest and most secure standard for the cryptographic protocols that provide widespread communication security over a computer network. PCI compliance requires TLS 1.1 or better encryption, so this is likely something you already support. (1)

How Does This Affect Me?

All modern web browsers use TLS 1.2 which means calls made directly to OrderCloud from your client UIs will not be impacted. In the event that you have any custom middleware, such as Punchout, Back-office integrations, Single Sign-on, etc., please make any relevant changes. Ensure that any integrations you have set up to receive webhook payloads from OC will accept TLS 1.2.

Premium Search

What Is It?

We've added a new type of search that can be used on the platform: Premium Search. This allows for more powerful, natural language search, as well as support for Faceted Navigation natively on the OrderCloud platform. Currently, Premium Search is only available for the me/products endpoint, although we plan on expanding to cover other areas soon.

Why Is It Important?

We know our customers want the most robust, sophisticated search capabilities available natively on the OrderCloud platform. That's why we've chosen ElasticSearch, an industry standard, to provide a powerful premium search experience. Premium Search will allow us to provide you and your users with improved Buyer-side catalog searching, and give you the ability to create faceted navigation natively, without the need to integrate with a third party tool.

How Do I Use This?

Currently this feature is in Beta, and while you may see the related endpoints in the DevCenter Console or API documentation, such as v1/ProductFacets, they will not be active for any organizations outside of our Beta program. We will be inviting some clients to take part in our Beta program in the near future.

We expect Premium Search to be available to the public this Fall -- contact your account rep to discuss getting Premium Search set up.

Changelog

• Premium Search added.

• Outbound HTTP traffic required to use TLS 1.2.

1: Forbes

• Infrastructure improvements

• Release contains a bug fix addressing an admin-visibility issue with buyer user private credit card objects.

• If a buyer user created a credit card that only they can access, and then used that card in a payment on an order, admin users were unable to update the payment at all. Instead, the API would respond with a 404 not found error, because the admin user did not have visibility into that private credit card. This is a particular problem as admin users are generally the ones to update a payment's accepted bool to true once a card payment clears.

• This is now fixed. While an admin user cannot get or otherwise retrieve the buyer user's private card object, the admin user is now able to update the payment that references the private card.

• Release consisted of a performance improvement around Spec Assignment listing.

Previously, if you filtered a list by an xp, it only cared about items in that list that had that xp. This meant that negative filters, such as xp.Color=!Blue, for example, would only return other items with xp.Color but where xp.Color was not blue. If an item didn't have xp.Color at all, it would not be returned in the filtered list.

Now, xp filters don't just look for the specified xp and filter down from there. Instead, a filter of xp.Color=!Blue will return all items with xp.Color where the color isn't blue, but also any items without xp.Color at all.

• We fixed an issue where Admin Address XP were not being correctly indexed retroactively.

• We fixed an issue with filtering a list of Products by the SpecCount field -- the list will now be correctly returned if the SpecCount is 0.

• We have solved an issue with Spending Accounts where duplicate Redemption Codes could be created on different Spending Accounts in the same Buyer. Now Spending Accounts cannot be made with any Redemption Code that is already in use within the Buyer. (Don't worry about existing applications you may have; there were no dupes in our databases at time of the fix.)

• You can no longer accidentally delete a buyer's default catalog! If you attempt to delete a catalog that happens to be the default catalog for one or more buyers, you'll get an error and a list of buyers.

Bug Fixes

• Fixed some character lengths around DevCenter User's Account information. Everything should now politely error should you attempt to insert a small poem rather than your company name.

• We've also improved some of the error handling around object creation with bad datetime strings.

• Minor error handling improvements around attempts at URL unfriendly object IDs.

• We've made some enhancements around our indexing performance.

• Previously, we had some inconsistent logic about when we evaluated Promotions on an order. Sometimes, this would lead to a submitted order suddenly having an invalid promotion, potentially changing the order total. As we want to allow a historical record of promotions at the time of order submit, we have now limited promotion evaluation to only orders whose statuses are unsubmitted or awaiting approval.

• We also fixed a bug around the rules engine for Order Approvals. If a User is in the approving group for an approval rule, any order submitted by that User that meets the approval rule should be auto-approved. Or, stated another way, because the User is an Approving User, their order does not need separate approval.

• Fixed an issue with the Incrementation Config on object PATCH

• Fixed an issue where an Anonymous User would lose access to an order if an Admin User changed that order.

Customized Platform Object ID Generation

A big question we get from clients a lot is "How can I make the OrderCloud API IDs work nicely with the IDs from my ERP or other internal systems?".

Prior to API 1.0.66, you could either set the ID manually (which is a pain if you want incrementation to work well) or you could settle for the default platform random GUID, and keep track of your ERP integration ID in an xp, or some other work around.

We've added a new feature that aims to make this process much, much simpler! Incrementation Config allows you to create a customized pattern for ID generation.

Incrementation Config

{
  "ID": "",
  "Name": "",
  "LastNumber": 0,
  "LeftPaddingCount": 0
}

The important parts here are the LastNumber and the LeftPaddingCount.

Examples:

Objective: Every order from a buyer should start with the buyer company's name, TestCorp, so that it can be differentiated easily by the supplier. The total number of characters for an ID can only be 20 characters long. (ex: TestCorp-00000000001)

1. Create the Incrementor Config

POST /v1/incrementors/

{
  "ID": "config01",
  "Name": "Bob",
  "LastNumber": 0,
  "LeftPaddingCount": 10
}

2. Create the order using the Incrementor Config

POST /v1/orders/outgoing

{
    "ID":"TestCorp-{config01}"
}

returns as:

{
  "ID": "TestCorp-00000000001",
...
}

If you make another order with this Incrementor Config, you'll get TestCorp-00000000002 and so on.

This Incrementor Config can be used for both object creation, and PATCH/PUT updates. Additionally, once created, the Incrementor Config's LastNumber reflects the last number incremented to. So, if the last ID generated by config01 was TestCorp-00000000011, the LastNumber for config01 would be 11 at that moment.

Caveats:

1 - Left-padding does not represent a maximum value for the ID. If you have

{
  "ID": "config01",
  "Name": "Bob",
  "LastNumber": 0,
  "LeftPaddingCount": 1
}

when you get to 99, the ID will continue incrementing. If you're using it as in the above example, where your ERP expects ONLY x number of characters, this is going to cause some problems.

2 - While you can reuse the same incrementator on different endpoints -- such as using config01 for both products and orders, for some reason -- the incrementation will be across both endpoints.

EX:

Order 1 with `config01` - `Order-00000000001`
Product 1 with `config01` - `Product-00000000002`
Order 1 with `config01` - `Order-00000000003`
Order 1 with `config01` - `Order-00000000004`
Order 1 with `config01` - `Order-00000000005`
Product 1 with `config01` - `Product-00000000006`

3 - If you're not careful about how you handle your asynchronous API calls, it's much easier to accidentally try to create duplicate IDs. So be hygienic with your async calls!

4 - If you decide to reset the incrementor's LastNumber, you can end up trying to create duplicate IDs again. Be careful!

Allowing a Buyer User to impersonate a Buyer User from a different company

Now, instead of a Buyer User only being able to impersonate a Buyer User within the same Buyer, a Buyer User can impersonate a Buyer User in a different Buyer, as long as they're within the same Seller organization.

This is useful if you have a customer user that works for multiple of your customers. This allows them to interact within those buyers uniquely, but maintain their user account easily.

Bug Fixes

Duplicate Products returned in ME Product Lists

We've fixed a problem where, sometimes in very large catalogs with complicated category structures, a user using a GET me/products list would return some duplicate products. This fix should also show some minor performance improvements for very large catalog list calls.

Post-Submit Order Changes Triggered Promotion Evaluation

Previously, if you tried to alter an order with a promotion after it had been submitted, and the promotion had expired, your alteration would throw an error. We've fixed this so that promotions are never evaluated after order submit now.

Various performance improvements and other small bug fixes.

What it says on the tin.

• The Me endpoint for categories is an optional ProductID filter. This allows a user to find all the categories assigned to them that have that product in them, removing the need to give a user the CategoryReader role to accomplish this.

Request:

GET https://api.ordercloud.io/v1/me/categories?ProductID=SuperAwesomeProduct

Response:

Status Code = 200

{
  "Meta": {
    "Page": 1,
    "PageSize": 20,
    "TotalCount": 25,
    "TotalPages": 2,
    "ItemRange": [
      1,
      20
    ]
  },
  "Items": [
    {
      "ID": "SuperAwesomeCategory",
      "Name": "I Contain the SuperAwesomeProduct",
      "Description": "",
      "ListOrder": 1,
      "Active": true,
      "ParentID": "",
      "ChildCount": 0,
      "xp": {}
    }
  ]
}

• We also added a Me route for GETing a single category! DOCS

  GET https://api.ordercloud.io/v1/me/categories/{categoryID}

Bug Fixes

• Previously, if you attempted to submit an order that had a lineitem with a product that had specs and options, it would fail. Fixed now!

  • need a refresher on product specs and spec options?

  • api reference for product specs

• On OrderSubmitted Message Sender Mandrill Templates, the order total merge variable was not accurately reflecting order total, leaving out promotion discount. This is now fixed. (The API model was never affected, only the Message Sender merge variable.)

• We fixed a bad index that was causing massive performance problems for DELETEing a Security Profile assignment. You should be able to go forth and delete to your hearts content now with no fear of the angry spinner!

• We now allow lineitems of unsubmitted Orders to be added to a Shipment. This does not apply to the ship all endpoint.

• There is a new endpoint that allows a buyer user to be transferred from one buyer to another, within the same organization. Please check out the documentation for further details.

  • please note, this should only be attempted by an admin user in a seller application. If a buyer user, even one with Full Access, tries this, it will not work as expected.

• Payments: Payment with Type SpendingAccount must have SpendingAccountID

• Unable to use PUT to create new UserGroup

• Orders: order.Total not updated when ShippingCost is updated via PATCH

New Features

• Added transactional email support for guest checkout (documentation)

`PATCH` `v1/orders/{direction}/{orderID}/fromuser`
{"FirstName": "", "LastName": "", "Email": ""}

• Products: Allow negation of all filters on admin Product List (catalogID, categoryID, supplierID)

• Upgraded to latest Flurl

• Several tweaks to improve API logging and Documentation generation.

Bug Fixes

• Previously, if you transferred an anon user's order to a profiled user, the prices would not update to reflect the profiled user's price assignments. This is now fixed.

• We've added a description field to Message Senders.

• We moved the platform Message Sender code to a public repo, so that developers can use it to create custom Message Senders. Message Sender on GitHub

  • Please note, we have not yet enabled custom message senders in DevCenter. You can start to develop one but can't configure one just yet to be used. This will be available in DevCenter in the near future.

• We've improved logging around Message Senders.

Bugs Fixed

• We fixed an issue that was blocking New User Invite emails.

• We've added the Billing Information Name to Customer Profile on our Authorize.Net integration.

Bugs Fixed

• We have added better error handling for API calls that include .NET reserved keywords in the route (typically in a buyer ID, etc.)

• You should no longer ever receive a 409 duplicate error on a GET call. Instead this will properly return a 500 error, as this is a bug.

• Various performance improvements

• Previously, if you created or patched a Shipment's ToAddressId, the response body would show NULL. This is now fixed.

• If you had a Shipment's ToAddressId set to NULL, and attempted to trigger a shipment notification through Message Senders, it would not get sent.

New Features

• When you add a new xp value to be indexed, previous xp with that value will now be retroactively indexed.

• Performance improvement around logging.

• Fixed an issue where a second approval or decline of an order would return a 409 error

New Features

• If a default ShipFrom address exists on a product, the shipFromAddress on a line item containing that product is now inherited on line item create, not order submit. This allows shipping to be more easily calculated.

• You can now filter lists with comparative operands >= and =<, as well as >, <, =, and !

• All approvals are now listed in an order's approval history, not just the final one.

• We added two new Mandrill template variables: ShipmentItems and DateShipped

Bug Fixes

• We fixed an issue where some list endpoints would fail intermittently with a 409 error. This included Me Categories, and Me Products, among others.

• We fixed an issue where the Rules Engine was throwing a 500 if you tried to create a rule with order.xp in either of the expressions.

• Now when you PATCH the LineItem.UnitPrice, the LineItem Total will update as well!

• We've improved our error handling for invalid rules engine expressions, so you find out if it's an invalid rule when you try to create it, not when you try to submit an order.

• Fixed a race condition where adding the same product to multiple categories sometimes resulted in a 409 error.

New Feature

• We improved performance for admin category lists substantially.

• We now return a Buyer subobject on the me/user model

• Buyer Users with the ShipmentAdmin role can now properly create shipments.

• We now properly throw a 409 error if you try to delete an admin user who is being used as the DefaultUserContextID for an org.

• Listing me/Shipments performance should be noticeably improved on large lists.

• Initial emails for Approvals message senders were not being sent.

New Features

• Developers who use the OIDC flow for authentication will now be able to dynamically route their users to specific parts of their app after authentication. To do so, add appstartpath=<extrapath> to the query on ocrplogin.

  • Example: https://nodomain.com/myapp{2}?token={0}&idt={1}

  • The {2} can go anywhere in the appstart url.

• Improved performance for seller-side /orders lists

Bug Fixes

• Now, a buyer user with CatalogAdmin should be able to:

  • Patch any catalog assigned to their buyer

  • Update any catalog assigned to their buyer

  • SaveProductAssignments for any catalog assigned to their buyer

  • ListProductAssignments for any catalog assigned to their buyer

  • DeleteProductAssignments for any catalog assigned to their buyer

• A buyer user with CatalogAdmin should not have the ability to:

  • Assign catalogs to other buyers

  • List catalog assignments of other buyers

  • Delete catalog assignments (even those for their own buyer)

  • Delete catalogs (even those assigned to their buyer)

• Removed invalid parameters previously documented on list endpoints

• Improved performance for me/categories and me/product lists.

• We've added some more debug information to OpenConnectID errors.

Bug Fixes

• Previously, we required CatalogAdmin and ProductAdmin to list Catalog and Product assignments, respectively. This is now changed to be consistent with other assignment listing role checks so that the user only needs CatalogReader / ProductReader.

• Now, if you patch a line item unit price with either null or an empty string, the price will be recalculated.

• No more 500 error when you try to delete a category with children.

• Generating variant IDs for Spec Option IDs that have blank spaces in their values will no longer result in IDs with spaces. Now all spaces are translated as -.

• Trying to patch ShipWeight/Height/Width/Length with a string no longer throws an error.

• Trying to patch a spec option with an invalid ID returns a 404 now.

You can access the staging environment using your production data and the following:

api: https://stagingapi.ordercloud.io

auth: https://stagingauth.ordercloud.io

devcenter: https://portal-staging.ordercloud.io

Production data will be copied down to the Staging environment weekly, on Sundays. In Staging, all webhooks will have their assignments deleted to disable them initially. Please update your webhooks and integrations in Staging to point somewhere other than Production ASAP. On the production release, no staging data will be transferred to production.

This was released to Production on May 4th at 8:00 PM Central.

New Features

• Payments have a new boolean field, Accepted. PUT has been removed from Payments, and PATCH can never edit Type, CreditCardID, and SpendingAccountID.

  • Only users with OrderAdmin or FullAccess roles will be able to create or update the Accepted property.

  • If the Accepted property is true AND the order has been submitted, a Shopper cannot patch the payment but a user with OrderAdmin or FullAccess can.

  • If the Accepted property is true AND the payment type is a credit card, a Shopper cannot patch the payment but a user with OrderAdmin or FullAccess can.

  • If the Accepted property is true, the order has not been submitted, and the payment type is not a credit card, either a Shopper or OrderAdmin CAN patch the payment.

  • If Accepted is false, any user with either role can patch all other fields except the 3 listed above.

• As part of the data conversion for existing payments, Accepted will be set to true for the following:

  • All non-credit card payments (spending accounts, POs)

  • All orders that were ever submitted (open, completed, seller-canceled)

  • All payments containing a successful PaymentTransaction

• PUT has been removed from payments. PATCH is allowed, but only to patch the Accepted property, and only if the user has OrderAdmin or FullAccess.

• Order submit logic will validate Payment.Accepted=true and an error will be thrown if an order with an unaccepted payment is submitted.

• Previously, any admin user could impersonate any buyer user. Going forward, an admin user must have the BuyerImpersonation role in their security profile to impersonate buyer users and request the role when impersonating a user.

• Due to refactoring around our password hash algorithm, and since we do not store users' passwords ourselves, but simply a hash of the password, users will need to reset their passwords before they can log into the OrderCloud DevCenter or any OrderCloud apps. When you authenticate to the Ordercloud API initially after this release, the only role your user will have is the PasswordReset role, and after you've reset your password, you'll need to re-authenticate to get your full array of roles.

  • If you provide an application to users, we recommend have the application redirect any user who authenticates and only has the PasswordReset role to be redirected to a different view, where their password can be reset using the new /me/password endpoint.

  • Alternately, any user can trigger an email-based password reset, using the Forgotten Password endpoint.

• Due to the aforementioned password changes, DevCenter users will need to reset their DevCenter passwords by going to the "Forgot Password" link in DevCenter. Users will need to do this in the Staging Environment and in Prod after the production release.

• Added roles that control who can list or edit shipments. Now users with ShipmentAdmin or OrderAdmin can create or edit shipments. Users with ShipmentReader or OrderReader can get/list shipments.

• Seller-side product lists (v1/products) can now be filtered on CatalogID and CategoryID (CategoryID is unique only within a Catalog, so you must specify both in order to filter on Category.)

• Buyer-side product lists (v1/me/products) that specify CategoryID can also specify depth, which can be an integer 1 or greater (depth=1 means products directly assigned to category) or all. Default is all.

• An order that requires approval can now be sent back to the submitting user by the approver user for editing and re-submission. See Decline Orders for more details.

• We are changing the route to register an anonymous user (previously called "Create From Temp User") to PUT v1/me/register. This will help make our Swagger spec more flexible.

• Any buyer user can now list shipments for their own orders in a User Perspective route, me/shipments. No more need for elevated permissions!

• In order to encourage best practices, only group-level and buyer-level assignments will be allowed for the following resources:

  • Products

  • Categories

  • Promotions

  • Cost Centers

  • Message Config

If there are existing user-level assignments for any of the above, you must convert them to group- or buyer-level before the production release date.

• OrderApproval now contains nested Approver object containing all details of the approving user. Example:

{
    "ApprovalRuleID": "...",
    "ApprovingGroupID": "...",
    "Status": "Pending",
    "DateCreated": "...",
    "DateCompleted": "...",
    "Approver":
    {
        "ID": "...",
        "FirstName": "...",
        "LastName": "...",
        "UserName": "...",
        "Email": "...",
        "Active": "...",
        "xp" : { ... }
    },
    "Comments": "..."
}

• We have also moved approval comments out of the URL query string and into the request body. There is a maximum length of 2000 characters.

• We have added new roles around the administration of Admin Addresses: AdminAddressReader and AdminAddressAdmin.

Inventory Revamp

• Inventory-related data points on Product are being moved into a nested Inventory object.

Summary of Inventory Object Changes:

{{table}}headers=Old,New#rows=Product.InventoryEnabled,Product.Inventory.Enabled&Product.InventoryNotificationPoint,Product.Inventory.NotificationPoint&Product.VarientLevelInventory,Product.Inventory.VariantLevelTracking&Product.AllowOrderExceedInventory,Product.Inventory.OrderCanExceed&Product.InventoryVisible,removed&/products/:id/inventory resource,removed&Inventory.Available,Product.Inventory.QuantityAvailable&Inventory.LastUpdated,Product.Inventory.LastUpdated&Inventory.ID,removed&Inventory.Name,removed&Inventory.Reserved,removed&/products/:id/inventory,removed{{table}}

Summary of Inventory Behavioral Changes:

• Product.Inventory.QuantityAvailable is writable.

  • PATCH v1/products/:id { "Inventory": { "QuantityAvailable": 999 } } is the preferred way to manually set inventory.

• QuantityAvailable is deducted on order submit or final order approval (whichever point order status changes to Open).

• QuantityAvailable is adjusted when quantity changes are made to line items on Open orders.

• QuantityAvailable is validated, but not adjusted, when items are added or quantities change on Unsubmitted orders. A 400 error occurs if item quantity exceeds available inventory and Product.Inventory.OrderCanExceed is false.

• QuantityAvailable is always re-validated per the rules above on order submit.

Shipment Changes

• The nested Shipment.Items collection has been removed, and shipment items are instead retrieved or saved via new endpoints, much like line items.

• To compensate for the above, there is a new me/shipmentitems endpoint.

• BuyerID has been removed from routes, meaning you can list shipments across multiple buyers.

• Shipment IDs are now seller-unique.

• All new fields listed below derive their values from corresponding LineItems, helping to avoid additional lookups when working with shipments.

{{table}}headers=New Shipment Field,Notes#rows=Shipment.Account,writeable&Shipment.FromAddressID,writeable&Shipment.ToAddressID,writeable&Shipment.FromAddress,nested object (read-only)&Shipment.ToAddress,nested object (read-only)&ShipmentItem.UnitPrice,read-only&ShipmentItem.CostCenter,read-only&ShipmentItem.DateNeeded,nested object (read-only)&ShipmentItem.Product,nested object (read-only)&ShipmentItem.Specs,nested collection (read-only)&ShipmentItem.xp,read-only{{table}}

{{table}}headers=Old Endpoint,New Endpoint#rows=GET v1/:BuyerID/shipments,GET v1/shipments&GET v1/:BuyerID/shipments/:id,GET v1/shipments/:id&N/A,GET v1/shipments/:id/items&N/A,GET v1/shipments/:id/items/:orderID/:lineItemID&N/A,POST v1/shipments/:id/items&N/A,PATCH v1/shipments/:id/items/:orderID/:lineItemID{{table}}

Simplified Product and Category Assignments

{{table}}headers=New Properties,Notes#rows=Catalog.Active&CatalogAssignment.ViewAllCategories&CatalogAssignment.ViewAllProducts&CategoryAssignment.Visible,Nullable - inherited from parent or catalog&CategoryAssignment.ViewAllProducts,Nullable - inherited from parent or catalog&Product.DefaultPriceScheduleId,Optional but encouraged.{{table}}

• For a Buyer User to see a Product in the User Perspective (GET v1/me/products), all of the following must be true:

  • Product.Active is true

  • Product belongs to a Catalog where Catalog.Active is true

  • Buyer is assigned to this Catalog

• In addition, one of the following must be true:

  • In Buyer assignment to Catalog, CatalogAssignment.ViewAllProducts is true, OR

  • Product belongs to active Category in the catalog, Category is assigned to Buyer (or any Group the user is in), and CategoryAssignment.ViewAllProducts is true, OR

  • Product is assigned directly to Buyer (or any Group the user is in).

We recommend checking out the Catalog Visibility Guide

• Fixed a bug where, in some particular cases, a user who submitted an order could also approve it.

• We now round the following to two decimal places:

  • OrderPromotion.Amount

  • LineItem.LineTotal

  • Order.Subtotal

  • Order.ShippingCost

  • Order.TaxCost

  • Order.PromotionDiscount

  • SpendingAccount.Balance

  • Shipment.Cost

  • Payment.Amount

  • PaymentTransaction.Amount

• We now return a useful and informative error message if you try to list CatalogAssignments without required parameters.

• We now return a useful and informative error message if you try to delete a user who has an open order outstanding.

• We now decrement SpendingAccounts on delete of a payment and not if it's just routed for approval.

• Fixed a couple issues where markups on product specs were not being correctly reflected in lineitem totals.

• XP filtering on buyers is now fixed.

• Delete webhook firing issue is fixed.

• Fixed an issue where the Reset Password Token didn't expire. Now expires after two hour.

• Fixed an issue around Promotions with value expressions containing product.incategory

• Fixed an issue where you couldn't delete orders after they'd been approved.

• Fixed an issue where you'd get a 500 instead of a useful error if you submit an order without specs if the order contained a specc'd product

• Fixed an issue where you got a 500 instead of a useful error if you tried to assign a non-existent user to an admin group

• Improved large value handling in unit prices

• You now (correctly) need ApprovalRuleAdmin and ApprovalRuleReader to admin/read approval rules and not AddressReader.

• Fixed an issue where you couldn't update a Category's ParentID to null

• Fixed a bug around promotions with value expressions evaluating product.incategory

• Removed some ApprovalRule fields related to features that don't exist yet.

• Fixed a tricksy bug where in some situations, the Meta of a list would change if the pageSize changed.

• You now get a much more helpful error if you try to assign a price to a product that doesn't exist.

• Fixed an issue where occasionally, if you added valid promo on an order, you would not be able to update the order afterwards.

• Several performance improvements around Product and Product Inventory

• We've added a FromCompanyID to the Order object, and you can filter on it, so that orders from different companies can be easily identified.

• We've fixed an issue where, if a product on an lineitem has required specs, but no specs are filled out and there's no default, the line item create is successful. Instead, now an error is thrown with with the missing specs.

• You should now be able to successfully set a string as a spec value on a lineitem if the product on the lineitem allows open text.

• If a buyer user has a private credit card and elevated roles (FullAccess, CreditCardReader & OrderAdmin, for example), you'll be able to create a payment on the private credit card without errors.

• Admin listing endpoints for assignments (listProductAssignments, etc) will no longer return assignments for deleted buyers.

We've added a new sub-object to the LineItem object. Now, when you list LineItems, you'll see the products that are on the lineitem too. This currently does not include the full price break information. New Line Item Object Example:

{
   "ID":"6-Ap0yfJ6k2kDxEJhPA4432vjA",
   "ProductID":"Test01",
   "Quantity":5,
   "DateAdded":"2016-05-19T17:51:46.127+00:00",
   "QuantityShipped":0,
   "UnitPrice":null,
   "LineTotal":0,
   "CostCenter":null,
   "DateNeeded":null,
   "ShippingAccount":null,
   "ShippingAddressID":"2WRMZMDcakaVaoJ6Hf_r1w",
   "ShipFromAddressID":null,
   "Product":{
      "ID":"Test01",
      "Name":"Test01",
      "Description":"Test01 Lorem Ipsum",
      "QuantityMultiplier":1,
      "ShipWeight":1,
      "ShipHeight":null,
      "ShipWidth":null,
      "ShipLength":null,
      "xp":{
         "test":false
      }
}

Shipping Rates Integration

• We've added UPS account configuration options to the Shipping Rates integration.

• We've added the option to adjust (as an admin) rates that are displayed to users by either a percentage or a flat rate, either at a global or carrier level.

• You can now add a manual shipper as well, to account for another kind of shipper than USPS or UPS.

Authorize.net

• We're storing the partial card number for single use card payments in the Payment object's XP, so it can be used in the refund transaction.

Bug Fixes

• You can't see expired Spending Accounts in the User Perspective Spending Account list, and you can't use one to make a new payment either.

• You can create a payment that exceeds the Spending Account balance if and only if the Spending Account Assignment for the relevant party has AllowExceed set to true.

• Speaking of price schedules, you can now set a minimum quantity, even when the quantity is not restricted to particular breaks. So, you can now say someone has to order at least 5 products, but they don't have to order only 10, 20, or 30, for example.

• A buyer user without elevated permissions cannot cancel their completed orders. (๑•̀ㅂ•́)و

Mandrill Integration

• We've fixed an issue with the Date Submitted variable for Orders not getting pulled into Mandrill email templates properly.

Authorize.net

• We've fixed the partial UpdateCreditCard to stop overwriting the CardholderName with null.

• We've expanded how you can use categories in the Rules Engine. You can now use items.total in your value expressions.

• We've added some new Mandrill variables that can be used in your Mandrill integrations:

  • Line Item Count

  • PO#

  • Ship To

  • Prior Approver

• You can use any Order XP in your Mandrill templates, including subobjects. EX: orderxp_xpKey, nested objects: orderxp_xpKey_xpKey2, and xp arrays indexes are accessed like this: orderxp_xpKey_0 (with zero being the index of choice).

• The Shipping Rate integration will now also calculate shipping rates based off of the Line Item level ship from address, not just the product ship from address. Line Item-level shipping will take priority over product-level.

• You can now use just a username, not an email, to trigger a forgotten password email!

Bug Fixes

• We fixed a bug where the Product Delete webhook trigger wasn't firing correctly.

• We fixed a display issue in the documentation around sorting priority.

• We added a new User Perspective endpoint for returning a user's spending accounts. Me/ListSpendingAccounts

• We've improved the information in our documentation about searchable/sortable properties and the order of precedence that these are applied in. An example is the API Documentation around Addresses

• We've added some performance enhancements around Products, particularly listing all products for a buyer.

• We now allow you to delete a product that is being used in an unsubmitted order. In submitted orders, the product information is retained, even after deletion.

• You can now use categories in the Rules Engine! For example, if you'd like to make a promotion that applies to products in only one category, you can use the following for a value expression: items.any(product.incategory('xxx'))

Bug Fixes

• When you update a buyer company's default catalog, it actually updates now!

• We fixed an issue where, if you were authenticating as a user with claims other than FullAccess, the authentication performance was very poor.

Client Libraries

• Angular SDK

• You can now filter list Order queries on the BillingAddress and ShippingAddress subobjects. This works on both Order and Me.Order lists. EX: /orders?ShippingAddress.Street1=xyz

• We've added true order-level shipping addresses. If a shipping address is set at the order level, all line items on the order will inherit that shipping address.

  • PLEASE NOTE: Previously, if all your line items had the same shipping address, any new line item would have the same shipping address. This is no longer true. Line items will ONLY inherit a shipping address when it is explicitly set at the order level.

  • There are no longer write-only address IDs on Order or Line Items; all of the following are now read/write:

    • Order.BillingAddressID

    • Order.ShippingAddressID

    • LineItem.ShippingAddressID

    • LineItem.ShipFromAddressID

• We've made several performance improvements around product history.

Bug Fixes:

• You can again list and delete security profile assignments for admin users.

• Search results will now be accurate when listing categories using a depth parameter.

• You can no longer assign an invalid spec to a product; you will get an error on assignment.

• The Authorize.net integration was updated to return more information in a more uniform response body.

• Delivery date added to Shipments

Bug Fixes:

• several fixes around Buyer Networks

• Shared Catalogs: Now a seller org can have multiple catalogs that can be assigned to one or many buyer orgs. There will be more information about this feature coming soon, but please be aware that it may break some existing routes particularly around categories, as categories are now specific to a catalog instead of a buyer. To update your existing categories routes, you'll need to add the catalog ID to your API routes, and as a parameter in your SDK calls. Me Category endpoints are not affected, except in that you can optionally filter by catalog.

• A single client ID for an app can be used by different buyers. This is our first step towards an exciting feature on our roadmap, Buyer Networks.

• You can now reference Product Names in your Mailchimp/Mandrill message templates! Previously, you could use Product Description and Product ID, now you can add Product Name as well.

Bug Fixes:

• We updated Spending Accounts to be decremented when an order is submitted, rather then when a payment is applied to an unsubmitted order. (Clearing an order will refund any payments applied, even if the order is unsubmitted-- deleting the order will not do so automatically.)

SDK Release Notes:

The SDK that will be going out with the API release will be v1.0.24.

After the API is released, if anyone runs a bower update with lastest in their bower.json for ordercloud-ng-sdk they will be updated to v1.0.24

• Integration Proxies and Assignments

• Webhook assignments

• Product/Spec Enhancements

Bug Fixes

• Preserve InteropID in Buyer Delete

• Line Items: Date Needed cannot be in the past

• Category: SaveCategoryAssignmentAsync Assigning to usergroup also assigns at company level

• Category: Client.Me.ListCategoriesAsync not returning expected result

• "Sequence contains no elements" exceptions in BaseApiController

• Line Items: Attempt to patch product id should throw error

• Credit Cards: should validate on creating

• Performance issues - order/{orderid}/submit endpoint - time out error

• Specs: /productassignments returns 500 if no specID

• Promotions - Patching order incorrectly updates PromotionDiscount

• Resolved Deadlock/Timeout issue on product search with xp filter

• Add Dimensions to Product Object

• Security Profiles can now be assigned at the party level. (Buyer, User Group, User) These Security Profiles will be inherited, so a user's total roles will actually be the total sum of these inherited profiles. In order to see what roles a user actually has, user.AvailableRoles is an array listing all the roles that user has.

• Because security profiles can be assigned at the Buyer level, apps can now use self-signup of users more easily.

• Administration of Admin Users is more granular now with new AdminUserReader and AdminUserAdmin roles for Security Profiles.

• We added XP to Approval Rules.

• We added the option to limit usage of a Promotion to once per customer.

• We added a read-only RedemptionCount to Promotions, so that users will be able to report more easily on how often a Promotions is used.

• We have added the ability to set a default ShipFrom address on a product, so that it will always show as shipping from that address.

• Admin Users can now be put into Admin User Groups, much like Buyer Users/Buyer User Groups.

Bug Fixes

• Previously, you would occasionally get a 409 error when PATCHing an order. This has now been fixed.

Breaking Changes

• Integration Proxy responses are now more clear about where an error is coming from.

• We changed how we store refresh tokens. This adds more security, as well as allowing us to have an unlimited refresh token. All apps will have to reauthorize after we deploy API 24.

• As the Category List endpoint now supports filtering a list of categories by parentID, we have removed: GET categories/xyz/categories (Categories.ListChildren) GET me/categories/xyz/categories (Me.Categories.ListSubcategories)

• Providing a parentID parameter explicitly in Category List is now redundant. Users should check that you are using the latest version of your SDK.

• Username is now required to be unique within a seller network. This opens up better possibilities for multiple buyers within one app, and a better user verification process. If you have not updated your username before the API 24 deploy when contacted, you will not be able to log in.

• We have changed our integration proxy base URL from api.ordercloud.io/v1/nativeintegrationproxy/:service to api.ordercloud.io/v1/integrationproxy/:service. If you use an integration within your app, please verify your url has been updated.

• A new Promotions feature has been added to the platform. Now you can set up promotions, using the same Rules Engine logic as Approval Rules. This new functionality allows buyers to get a limited time discount, free shipping, etc. These Promotions can now be added to orders. Promotions are assignable to buyer parties. But like products, they are admin owned and can be shared between multiple buyers.

• An existing user can now start off as a temp user and then log in as an existing user. This gives them the ability to keep their current temp user order.

• The Order Approvals endpoint has been updated. You can now add comments and sort chronologically.

• You can now filter on Order.Total

• The endpoints returned from the Documentation API now properly reflect the Role information for each endpoint.

• The ability to get a list of pending order approvals has been improved. You can now get a list of unique users in one step, via: /orders/xyz/eligibleapprovers

• A number of bug fixes also went out with this release.

• You can now list the pending approvals, for an order, by passing in the Order ID. This will primarily be used for email integrations. Notifications can now be sent to the approving group of users for each step, as the order gets passed along.

• The ability to set a ship-from address on a line item has been added, this will be useful for calculating shipping rates

• Endpoints have been created for seller addresses

• XP is now available for Approval Rules

• A Description field is now available for viewing, approving, and declining orders.

• XP is now available for Variants

• a number of bug fixes were also deployed with this release.

• Endpoint arguments that exist in the model, which the endpoint returns, and that have listArgs, have been removed. Example: - v1/buyers/{buyerID}/categories/assignments This endpoint accepts buyerID, categoryID, userID, userGroupID, level, and listArgs. buyerID is required because it is part of the route. level should also be included because it is not part of the CategoryAssignment model. However, categoryID, userID, and userGroupID are all part of the CategoryAssignment model and can therefore be added to the Filters field within listArgs (since in both cases they will be included as query string parameters).

• The State and Zipcode validation has been updated. For Addresses with US country code, it is now required to have a State and Zipcode. For non-US addresses, it is not required.

• XP has been added to Cost Center endpoints.

• List routes for /me order will now mirror admin order routes with respect to requiring incoming/outgoing. Further, the rules of visibility have changed with the four order list routes in the interest of simplicity: - orders/outgoing orders from my company (submitted only unless UnsubmittedOrderReader role) - orders/incoming orders to my company (submitted only unless UnsubmittedOrderReader role) - me/orders/outgoing orders created, approved, or declined by me - me/orders/incoming orders awaiting my approval

• For Approval Rules, approved(ruleid) has been changed to order.approved(ruleid)

• Previously, admin address routes allowed you to see all addresses assigned to the buyer company AND your own private addresses. In order to simplify the visibility rules for admin routes (like with orders), private addresses are now only visible through /me routes.

• Route params have been added to webhooks. An object has been added that contains the values from the routeparams.

• A small number of bug fixes also went out with this release.

• The API now has elevated security integration. 3rd party systems now have the ability to perform elevated security operations. This means that we can grant them specific access that is not accessible by the (buyer) client.

• The Rules Engine has been updated to replace the item object with items aggregate function. The item object has been replaced with items that contains aggregate functions allowing you do this: items.any(CostCenter = 'XYZ') instead of this: item.CostCenter = 'XYZ' This supports four such aggregate functions:

  • items.any(subexpression) - returns true/false indicating whether any items match subexpression

  • items.all(subexpression) - returns true/false indicating whether any items match subexpression

  • items.quantity(subexpression) - returns total quantity of items matching subexpression

  • items.total(subexpression) - returns price total of all items matching subexpression

• Upon sending a webhook, an access token is now appended to the outbound web hook call. If a web hook receiver needs to perform actions on behalf of that user with elevated claims, they can now use this token to do so. A nullable field has been added to webhooks called ElevatedClaimsList containing a comma separated list of Claims.

• Several improvements have been made to the Dev Center to allow management of the webhooks from with the Dev Center UI.

• Several bug fixes were also deployed with this release.

• Approval rules have been updated significantly in this release. This release includes the new ApprovalRule data model (with full admin-side CRUD endpoints), support for a wide variety of expressions, and support for the actual buyer-side flow, including (legacy) email messaging. There will be an approval rules blog post in the near future that will cover this more in-depth.

• The API route for Order listing has changed. When listing orders as a Seller user, you must now specify incoming or outgoing in the route, rather than in the query string. For example:
  v1/orders/incoming This does NOT apply to me/orders - outgoing is always assumed there. It only applies to admin routes, such as incoming orders for sellers and outgoing orders for approving buyer users. Apps will need to be updated accordingly, and make sure you're using the latest version of the SDK

• IsReportingGroup and IsApprovingGroup have been removed from the UserGroup object.

• This release also contains several bug fixes.

• Buyer users can now can get a list of the products assigned to themselves. This used to require multiple API calls.This is now a single call.

• There is now the ability to list security profiles in the API itself and not just in DevCenter (as before).

• When logged in as a buyer user you can now list their assigned security profiles

• There is now the ability to create personal addresses (billing and shipping) outside the organization.

• There is now the ability to create a personal list of saved credit cards outside the organization. Users can now add, update, and delete personal credit cards.

• Shipment XP - XP can now be used on Shipments

• Address XP - XP can now be used on Addresses.

• API Client XP - XP can now be used on a client organization.

• There are now more advanced search and filtering capabilities available on Addresses, Credit Cards, Specs, and Buyer Categories. This new search capability allows for more advanced filtering and fuzzy searches on lists. Take a look at the new, searchable attributes here.

• The API has been updated to allow for Anonymous Shopping within the OrderCloud platform. This update allows for much more flexibility in the buyer user workflow. In the past, buyer users had to be registered in order to purchase products. Now, they can go through the entire shopping workflow without signing in.

• Spec Options can now be designated as the Default Spec Option for a Spec.

• There is now the ability to create registration off of a temp user. A user can start with a temp user session and when they choose to profile themselves, a new user based on the template is created.

• Temp users can create an order but nothing else on Me. It is now impossible for a temp user to create Me data outside of an order.

• A SpecCount can now be shown to designate how many options are set up for a particular Spec.

• The Docs section of Devcenter has been reorganized to better reflect how people are actually using the API.

• We fixed a bug so that users can now filter on XP in the /me endpoint lists.

• Multiple bug fixes were also included in this release.

• We've fixed a bug where, if you searched a list on XP, you sometimes got duplicate results.

• We've fixed a bug where, if you are an Admin User, you couldn't update the line items on an order for a Buyer User. This is an uncommon scenario, as generally an Admin user would impersonate a Buyer User to make an order on behalf of the Buyer user, but some integrations use an Admin User directly.

• Duplicate error when creating categories in different buyers

• We've added some new functionality around how we store credit card and other payment transactions. If your app uses our credit card processing, you'll probably want to check out the documentation on Payments, and make sure everything is working the way you expect.

• You can now use partial updates ( PATCH calls) to update fields on any model to NULL instead of having to overwrite with some other value!

• We've changed how you can check if all the line items on an Order are being shipped to the same place. While you could previously set all the line items on an order to the same address by writing to Order.ShippingAddressID , the value was write-only. Now Order.ShippingAddressID will return a non-null value if and only if all the line items on that order have the same shipping address. Check out the documentation for more on this.

• To go along with the above, if Order.ShippingAddressID is non-null (that is, all the line items are being shipped to the same place), newly added line items will inherit that shipping address.

• Some performance improvements were made around working with line-items. If your app has a lot of PATCHing of line items, you'll hopefully notice those improvements.

• Payments: Unable to create, states order is already fully paid

• Products: Generating variants throws 500 error

• CostCenterID cannot be set on an ApprovalRule

• Specs: After variants are generated for a product, the definesVariant is set to false

• Payment Types allow using multiple payment types on a single order

• Generate Variants

Breaking Changes

• DefinesVariant has been moved from the Spec model to the Product-Spec Assignment model

Generating Variants

There are 4 things needed to create a product with variants Spec(s) Spec options a spec product relationship that sets Defines variant = true an explicit call to POST {productID}/variants/generate

it's pretty simple once they're initially set up. Take the ubiquitous shirt example Specs size small, large color red, black

spec - product = size/shirt/definesvariant = true spec - product = color/shirt/definesvariant = true

a call to POST {productID}/variants/generate will generate 4 variants

• small red

• small black

• large red

• large black

Adding specs is pretty simple add color:blue and a call to POST {productID}/variants/generate will ADD the missing variants 1 small blue 2 large blue The tricky bit starts when a spec is removed. if color is deleted, all the variants are not relevant because color is built into all of them. Delete color and add logo to our shirt. So that this is the config of shirt: size: small,large logo: logoA,logoB

and a call to POST {productID}/variants/generate will only ADD new variants and you'll have 8. Even with the spec deleted, the dependant variant can still exist, it's just not tied to the deleted spec. This is important if that variant is already on an order.

• small logoA

• small logoB

• large logoA

• large logoB

• small red

• small black

• large red

• large black

if your intention is to start over and reset the variants, there is the spec nuclear option:

POST {productID}/variants/generate?overwriteExisting=true

This will DELETE ALL variants and regenerate them based on the current spec configurations. If a variant is on a lineitem, it will be removed. The previous example deletes color and adds logo. calling overwriteExisting=true will result in

• small logoA

• small logoB

• large logoA

• large logoB

The key to overwriteExisting=true is that it will always delete all variants and regenerate regardless of the change to the spec configuration.