Security Profiles

Forgotten Credentials

ImpersonationConfigs allow users to make API calls on behalf of a buyer user, which we refer to as impersonation.
If you're a marketplace owner user with the BuyerImpersonation role you can impersonate any buyer user under your organization as long as an applicable Impersonation Config has been created.
If you're a buyer user with the BuyerImpersonation role you can impersonate any other buyer user within the same buyer company as long as an applicable Impersonation Config has been created.

Impersonation Configs

Certs

Open Id Connects

Buyers, or customers, are the organizations that view the categories and products and place orders.

Buyers

A user is a person with access to the application.  The properties of a user define who they are and what they are able to do with their login to the application.

Users

User Groups are used to streamline the management of users within an application.  By placing like users in groups, you can filter content, define order management rules, and manage changes much more easily than trying to account for individual users.

User Groups

Addresses are used for the purposes of billing and shipping an order.  An address may belong to a list that can be shared among many users if appropriate.

Addresses

A cost center is used to allocate organizational expenditures.  Different businesses call these by different names such as "allocation codes" or "charge back codes", but the basic purpose is the same - to allocate an expense back to someone or some department of an organization.

Cost Centers

Credit cards are used as a payment method for an order.  A user may have access to one or many credit cards for personal spend or group spending.
Credit Cards may be saved and assigned to members of an organization for use during purchase.

Credit Cards

Spending Accounts are funds given to users by a managing entity and are managed as part of a user's account.  These funds are generally used as "corporate dollars", "rewards dollars", or "gift cards".
They can be used to pay for all of or part of an order with parameters that control account expiration, balance available, balance renewal, user access and overdraft.
Multiple spending accounts can be assigned to a member of an organization and applied to all transactions, but only one can be used as a payment method.
When multiple Spending Accounts are used on a transaction each is deducted individually.

Spending Accounts

Approval rules are used to verify the integrity of an order.  Common examples include orders requiring managerial approval, approval for orders that contain a specific product category, approval for quantity thresholds or approval for orders that exceed a specific price.  Properties are also available to control the triggers and timing for processing approvals whether parallel to another rule, or in succession of a previous rule.

Approval Rules

Product Collections brings an ability to categorize products into Lists and group them for easy access.

Product Collections

"Me" is a container for read-only endpoints that return a filtered view of things that the current buyer user is allowed to see, i.e. things that they are assigned to either directly or as a member of a buyer organization or user group. It also provides ways for a user to update or change their own information.

My Addresses

My Catalogs

My Categories

My Cost Centers

My Credit Cards

My Orders

My Product Collections

My Products

My Promotions

My Sellers

My Shipments

My Spending Accounts

My Subscription Items

My Subscriptions

My User Groups

An Order represents a business transaction between two parties. It typically consists of a collection of Line Items, a Payment Method, Tax and Shipping information, etc. The OrderCloud platform defines various "actions" that can be performed against Orders, such as Submit, Approve, Ship, etc. These actions transform the state of the order and often trigger external events such as financial transactions.

Orders

The Cart is a straightforward way for a buyer user to interact with an order prior to submit. Unlike Order endpoints, an OrderID is never needed to interact with the cart. This simplifies workflows and eliminates the need to keep track of the OrderID on the front end. Please note Cart should be used as a distinct alternative to Order endpoints for a buyer user during the shopping experience; combining the use of Cart endpoints with Order endpoints may have unexpected results, and is not supported. Only available to Buyer Users.

Cart

A Line Item represents a single line on an Order. At a minimum, it contains a single Product SKU and a quantity. A line item may also include Spec values, a Cost Center, shipping details, date needed, and other custom information.

Line Items

Promotions are used to reduce the cost of a line item or an order.  Promotions can have redemption rules that can be applied for available dates, occurences and value.
Promotions can be assigned to Products, Categories, Buyers, UserGroups and Users for redemption.

Promotions

Payments

A Shipment is a grouping of one or more Line Items from one or more Orders that is physically packaged and delivered to the Buyer as a single unit. It is typically created by the Marketplace Owner after the Order is submitted as part of the fulfillment process.

Shipments

An OrderReturn represents a transaction between two parties. It can be a record of physical items being returned, or simply a credit being issued not tied to the return of an item.

Order Returns

Order return approval rules are used to verify the integrity of an order return. Common examples include order returns exceeding a specified refund amount or order returns that contain no physical items to return. Properties are also available to control the triggers and timing for processing approvals whether parallel to another rule, or in succession of a previous rule.

Seller Approval Rules

A Bundle represents a group of lines on an Order. At a minimum, each line contains a single Product SKU and a quantity. A line item may also include Spec values, a Cost Center, shipping details, date needed, and other custom information.

Bundle Line Items

Bundle Subscription Items

Subscription Items

Subscriptions

A Catalog represents a group of categories used to group and place content for a specific audience. All buyers are issued and assigned a default catalog upon creation. Catalogs can be shared between buyers using assignments.

Catalogs

Categories are used within a catalog to group and place content for a specific audience. Content can be in the form of another category, nested categories, products or HTML.

Products

Price schedules allow the same product to be sold across multiple channels.  A price schedule may include quantity price breaks, min and max quantity per order, whether to apply tax or shipping calculations, or to what type of order the price schedule applies.

Price Schedules

Specs are used to capture user input when adding a Product to an Order. At its simplest, a spec is a name/value pair. A spec value may have a price markup or markdown associated with it. In more advanced scenarios, specs can drive the product SKU. For example, a product may be available in 3 colors and 3 sizes and therefore have a total of 9 SKUs. **The OrderCloud platform will choose the correct SKU based on the user-selected color and size specs**.

Specs

A product facet is an extended property (value on product.xp) designated to participate in faceted navigation. Buyer list endpoints for products will populate and return Meta.Facets, a collection of facet names, values, and counts. Counts represent the total results that would be returned should the current set be further filtered on that facet value.

Product Facets

Inventory Records represent physical locations where inventory for a given product exists. Use of Inventory Records will prevent writing to Product.Inventory.QuantityAvailable, which will instead be a sum of inventories across all locations associated to the product.

Inventory Records

A Bundle represents a bundle of physical, digital, or abstract good that is offered for sale by a Marketplace Owner or Supplier and is purchase-able by Buyer Users via an Order.

Bundles

Users on an Organization level are users that have administrative access to things like adding users, creating catalogs, processing orders or creating products. These users are not specific to a buyer company.

Admin Users

Admin User Groups

Admin Addresses

Api Clients

An incrementor is used to add an atomically incremented number to your object IDs. For example, "aprefix-{myIncrementorID}", will yield an order ID of aprefix-10010.

Incrementors

Locales are used to facilitate multi-currency product pricing and ordering in a marketplace. They can be assigned to Buyers or Buyer UserGroups.Duplicate Currency/Language combinations not permitted.

Locales

Webhooks

Xp Indices

Suppliers can own, supply, and/or distribute products within the marketplace.

Suppliers

Supplier Users

Supplier User Groups

Supplier Addresses

The OrderCloud.io API implements OAuth2 combined with our own notion of Roles to control user authentication and authorization at fine-grain level. Be prepared to spend time learning about these concepts and designing the right model for your application. If you over-privilege your users and attempt to control what they can do via front-end code, you run the risk of technically savvy users circumventing this by making direct API calls.

Authentication and Authorization

At the center of any OrderCloud.io solution is a single Seller organization. It consists directly of Users, Groups, and Addresses (used mainly for shipping calculations), which should be established ahead of Product Catalogs, Buyers, and Suppliers.

Seller

Buyers represent real-world legal entities to which the Seller offers Product Catalogs and from which the Seller receives Orders. Buyers contain many of the same things as Sellers (Users, Groups, Addresses) and much more, including Cost Centers, Spending Accounts, and Approval Rules.
Assignments are prevalent concept. Most "things" can be assigned to a User, Group, or entire Buyer organization. Plan ahead, and use Groups to your advantage here. For example, if you assign 100 Addresses directly to 50 Users, you are going to need to create 100 additional assignments every time you add a new User. Or, 50 more assignments for every new Address. With careful planning, Groups can save you from "assignment hell".

Suppliers are a third, optional type of organization used in indirect supply chain scenarios. Like the Seller, they contain Users and Groups. Once established, Products can be configured to auto-forward to Suppliers when ordered. This will automatically create a new PO, notify the Supplier, and track costs and profit margins if configured.

Products are priced (or unpriced) goods that can be offered to Buyers for placement on Orders. A Product can belong to any number of Catalogs, and a Catalog can be organized into hierarchical Categories to any arbitrary depth. Catalogs are assigned to Buyers, though visibility and pricing may vary by Buyer, User Group, Category, or individual Product. Pricing may include quantity breaks (collectively called a Price Schedule), and Price Schedules may be shared with multiple Products. User-selected Specs, which may include price markups, can be assigned to Products, enabling Buyer configurability at the time of ordering.

Product Catalogs

The central concept within OrderCloud.io is (not surprisingly) the Order. This is where Buyers, Sellers, Products, Addresses, and just about everything else come together to form business transactions. A feature that is somewhat unique to this area of the API is that you'll use the same set of endpoints regardless of whether you're a Buyer, Seller, or Supplier. What's important is the order *direction*, which is either incoming or outgoing. Order IDs are guaranteed unique within that context. As a seller, this means you can aggregate lists of incoming orders from many Buyers, or outgoing orders to many Suppliers. You may filter a list by Buyer or Supplier, but it's not required to uniquely identify an Order. (Buyers typically only deal with outgoing Orders; Suppliers with incoming.) Buyers add Line Items to Orders by specifying a Product, Quantity, and (optionally) Spec values. Shipping is applied at either the Order level or Line Item level. Shipments are independent of Orders; you can ship a partial Order, or aggregate items from multiple Orders onto a single Shipment.

Orders and Fulfillment

With an understanding of the robust visibility options involving roles, group-level assignments, Buyer-specific pricing, "Active" bits, and the like, you might be wondering, where are all these rules actually enforced? This is the job of the resources that begin with "me". Whether authenticated as yourself or impersonating as someone else, you see only what that user is allowed to see. A good rule of thumb is that, other than authentication, you should be able to build an entire Buyer experience using only endpoints that start with "orders" or "me".

Me and My Stuff

Integration refers to the ways in which OrderCloud can interact with external systems.