Product collections

Save for later

• Move products from active orders
• Preserve shopping intentions
• Simplify future purchases
• Track desired items

Favorite products

• Mark preferred items
• Quick access to frequent purchases
• Personalized product lists
• Simplified reordering

Custom wishlists

• Create multiple lists
• Organize by purpose
• Share product selections
• Track desired items

Visibility control

Product restrictions:

• Only visible products can be added

  GET me/products
  

• Follows standard visibility rules

• Respects user permissions

• Maintains data security

Access management

Current limitations:

• Collections visible to creator only
• No public list sharing
• No organization-wide visibility
• No user-to-user sharing

Future possibilities:

• Public list functionality
• Organization-wide sharing
• User-specific sharing
• Controlled visibility

Collection limits

System boundaries:

• 500 products per collection
• Unlimited collections per user
• Efficient list management
• Optimized performance

Collection management

Basic operations:

• GET v1/me/productcollections

  • List all collections
  • View collection details
  • Access personal lists

• GET v1/me/productcollections/{productCollectionID}

  • Retrieve specific collection
  • View collection details
  • Access list contents

• POST v1/me/productcollections

  • Create new collection
  • Set collection name
  • Configure properties

• PUT v1/me/productcollections/{productCollectionID}

  • Update entire collection
  • Modify all properties
  • Replace configuration

• PATCH v1/me/productcollections/{productCollectionID}

  • Partial collection updates
  • Modify specific properties
  • Preserve other settings

• DELETE v1/me/productcollections/{productCollectionID}

  • Remove collection
  • Delete all entries
  • Clean up resources

Product management

List operations:

• GET v1/me/productcollections/{productCollectionID}/products
  • View collection contents
  • List included products
  • Follow product visibility rules

Item operations:

• PUT v1/me/productcollections/{productCollectionID}/{productID}

  • Add product to collection
  • Create new entry
  • Update list contents

• DELETE v1/me/productcollections/{productCollectionID}/{productID}

  • Remove product from collection
  • Delete entry
  • Update list contents

New capabilities

December 2024 enhancements:

• Entry creation endpoint:

  POST v1/productcollections/{productCollectionID}/products
  

Required fields:

• ProductID: Target product

Optional features:

• ListOrder: Custom sorting
• DateAdded: Automatic timestamp

Entry management

Sorting options:

• Custom list order
• Addition date
• Product attributes
• User preferences

Use cases:

• Wishlist organization
• Saved item management
• Priority ordering
• Custom arrangements

Collection design

Best practices:

1. Plan collection structure
2. Define naming conventions
3. Consider xp requirements
4. Document limitations

Product handling

Guidelines:

1. Verify product visibility
2. Check collection limits
3. Manage entry ordering
4. Handle removals

User experience

Recommendations:

1. Clear collection naming
2. Intuitive organization
3. Easy product management
4. Efficient navigation

Implementation scenarios

Access level property

The AccessLevel property defines who can view and interact with a product collection:

ProductCollectionReader role

This new role provides different capabilities based on user type:

GET v1/buyers/{buyerID}/productcollections
GET v1/buyers/{buyerID}/productcollections/{productCollectionID}
GET v1/buyers/{buyerID}/productcollections/{productCollectionID}/products

ProductCollectionInvitation resource

This new resource enables collection owners to grant access to their private collections:

{
  "ProductCollectionInvitation": {
    "ID": "",
    "Name": "",
    "Admin": false,
    "Accepted": false,
    "ExpirationDate": "",
    "xp": {}
  }
}

POST v1/me/productcollections/{productCollectionID}/invitations
DELETE v1/me/productcollections/{productCollectionID}/invitations/{invitationID}
GET v1/me/productcollections/{productCollectionID}/invitations
POST v1/me/productcollections/{productCollectionID}/invitations/accept/{invitationID}
POST v1/me/productcollections/{productCollectionID}/invitations/decline/{invitationID}

Message senders

Private lists: Favorites, Save for Later, or Custom lists

Authenticated shoppers can create personal Product Collections to save products to their account:

• "Save for Later" option for cart items they're not ready to purchase
• Quick-save buttons (heart/star) on product cards for frequently purchased or favorite items
• Custom named lists for specific projects (e.g., "Game Room" for home furnishing projects)

Privately shared wishlists

Product Collections can be shared with specific users. For example, creating shared grocery lists or holiday wish lists. The AccessLevel property controls sharing:

• AccessLevel:Private allows the creator to invite specific users:
  • Admin:False - View-only access
  • Admin:True - Full edit access (add/delete products, rename list, invite others)

Invited users must accept the invitation to access the Product Collection.

Shareable wishlists

Creating a Product Collection with AccessLevel:Shareable generates a shareable link. Example use case: A teacher sharing classroom supply needs with student families via a link:

https://www.yourwebsitehere.com/productcollection/view/2dcf59c0-6cca-11ec-b7a2-a7c693c3c9

This eliminates the need for individual invitations.

Gift registry

Wedding and baby registries use Product Collections with AccessLevel:Public. These lists are searchable and accessible to anyone. Extended properties (xp) can store:

• Recipient names
• Event date
• Location
• Quantity requested per item
• Purchase tracking

Buying lists

For business scenarios, like a restaurant chain District Manager distributing monthly marketing materials, Product Collections simplify ordering. Create a list of required items and share it with purchasing staff using Private or Shareable AccessLevel.

Implementation requirements

Implementation steps

POST sandboxapi.ordercloud.io/v1/me/productcollections HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "ID": "wishlist",
  "Name": "Wishlist"
}

import { Me } from "ordercloud-javascript-sdk";

Me.CreateProductCollection({
  ID: "wishlist",
  Name: "Wishlist"
})
.then((productCollection) => {
  console.log(productCollection);
})
.catch((ex) => console.log(ex));

import { Me, OrderCloudError, ProductCollection } from "ordercloud-javascript-sdk";

Me.CreateProductCollection({
  ID: "wishlist",
  Name: "Wishlist"
})
.then((productCollection: ProductCollection) => {
  console.log(productCollection);
})
.catch((ex: OrderCloudError) => console.log(ex));

using OrderCloud.SDK;

var productCollection = new ProductCollection
{
  ID = "wishlist",
  Name = "Wishlist"
};

try {
  ProductCollection response = await Me.CreateProductCollection(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

PUT https://sandboxapi.ordercloud.io/v1/me/productcollections/wishlist/enterprise-product-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

import { Me } from "ordercloud-javascript-sdk";

Me.CreateProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully added a product to your wishlist!");
})
.catch((ex) => console.log(ex));

import { Me, OrderCloudError } from "ordercloud-javascript-sdk";

Me.CreateProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully added a product to your wishlist!");
})
.catch((ex: OrderCloudError) => console.log(ex));

using OrderCloud.SDK;

try {
  await Me.CreateProductCollectionEntry("wishlist", "enterprise-product-id");
  Console.WriteLine("Successfully added a product to your wishlist!");
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

GET https://sandboxapi.ordercloud.io/v1/me/productcollections/wishlist/products HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

import { Me } from "ordercloud-javascript-sdk";

Me.ListProductCollectionEntries("wishlist")
.then((wishlist) => {
  console.log(wishlist.Items);
})
.catch((ex) => console.log(ex));

import { Me, OrderCloudError } from "ordercloud-javascript-sdk";

Me.ListProductCollectionEntries("wishlist", "enterprise-product-id")
.then((wishlist: ListPageWithFacets<BuyerProduct) => {
  console.log(wishlist.Items);
})
.catch((ex: OrderCloudError) => console.log(ex));

using OrderCloud.SDK;

try {
  ListPageWithFacets<BuyerProduct> response = await Me.ListProductCollectionEntries("wishlist", "enterprise-product-id");
  Console.WriteLine(response.Items);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

DELETE https://sandboxapi.ordercloud.io/v1/me/productcollections/wishlist/enterprise-product-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

import { Me } from "ordercloud-javascript-sdk";

Me.DeleteProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully removed a product from your wishlist.");
})
.catch((ex) => console.log(ex));

import { Me, OrderCloudError } from "ordercloud-javascript-sdk";

Me.DeleteProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully removed a product from your wishlist.");
})
.catch((ex: OrderCloudError) => console.log(ex));

using OrderCloud.SDK;

try {
  await Me.DeleteProductCollectionEntry("wishlist", "enterprise-product-id");
  Console.WriteLine("Successfully removed a product from your wishlist.");
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Implementation considerations