API v1.0.50 Release Notes

Released on null

A public staging environment will be available starting on Sunday, April 2nd. The 1.0.50 version will be released to Production on May 4th at 8:00 PM Central.

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