API clients represent applications or tools that need to interact with OrderCloud to send requests and receive data.

API clients

Security profiles define the access levels and permissions granted to users and roles within the platform, ensuring that only authorized individuals can perform specific actions. These profiles are customizable, allowing organizations to tailor security settings based on the unique needs of their operations and workflows.

Security profiles

These endpoints allow you to reset a user's password or retrieve a forgotten username.

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

OpenID Connect (OIDC) is an authentication protocol built on top of the OAuth 2.0 framework, allowing applications to verify the identity of users and obtain basic profile information securely. It enables Single Sign-On by allowing users to authenticate with an identity provider (such as Google, Microsoft, or a custom provider) rather than directly within OrderCloud.

Open ID connects

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

Buyers

Users are people with access to the marketplace. A user's roles define who they are and what they can do when they log in to the application.

Users

User groups streamline user management in your marketplace. By assigning similar users to groups, you can filter content, define order management rules, and manage changes more easily than accounting for individual users.

User groups

Addresses are used for billing and shipping an order. You can create multiple addresses and assign them to user groups, or create private addresses through the Me resource.

Addresses

Cost centers are used to allocate organizational expenditures. Customers may have different names for this, such as "allocation codes" or "charge back codes", but the purpose is to allocate an expense to a person or department in an organization. Cost centers can referenced on line items, but they do not influence any behavior in OrderCloud.

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 assigned to users that can be used as a payment method on an order. These funds are generally used as corporate budget accounts or rewards dollars. They include parameters that control expiration, balance available, balance renewal, user access and overdraft.

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 are used to group products into lists to support things like wishlists, or "saved for later" features for individual buyer users.

Product collections

Admin users are people with access to the marketplace. A user's organization and roles define who they are and what they can do when they log in. Admin users may have broader access than other user types, as they can access information about other organizations with the proper roles.

Admin users

User groups streamline user management in your marketplace. By placing similar users in groups, you can filter content, define order management rules, and manage changes more easily than accounting for individual users.

Admin user groups

Admin addresses define a ShipFromAddress on a product or line item, or represent physical locations for product specific inventory.

Admin addresses

Incrementors add an atomically incremented number to your object IDs. For example, using "aprefix-{myIncrementorID}" results in an order ID of "aprefix-10010".

Incrementors

Locales facilitate multi-currency product pricing and ordering in a marketplace. You can assign locales to Buyers or Buyer UserGroups. Duplicate Currency/Language combinations are not permitted.

Locales

Webhooks are HTTP callbacks that allow OrderCloud to send real-time data or notifications to a specified target when an event occurs.

Webhooks

XP indices are created for a given XP property on a resource to optimize that data for indexing. This allows filtering on that property.

XP indices

"Me" is a container for endpoints that return a filtered view of things that the current user is allowed to see. 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 Subscriptions

My User Groups

Orders represent a business transaction between two parties. They typically consist of a collection of line items, a payment method, tax and shipping information, etc. The 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

Carts are a straightforward way for a buyer user to interact with an order before submitting it. Unlike order endpoints, an order ID is not needed to interact with the cart. This simplifies workflows and eliminates the need to keep track of the order ID 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 is not supported and may have unexpected results. Only available to buyer users.

Cart

Line items represent a single line on an order. At a minimum, they contain a single product ID 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 reduce the cost of a line item or an order. Promotions can have redemption rules that can be applied for available dates, occurrences, eligible products and categories and value. Promotions can can be assigned to buyers or  user groups for redemption.

Promotions

Payments store information about payments and transactions related to a spending account, or those that occur in a 3rd party payment provider.

Payments

Shipments are a grouping of one or more line items from one or more orders that are physically packaged and delivered to the Buyer as a single unit. They are typically created by the marketplace owner or supplier after the order is submitted as part of the fulfillment process.

Shipments

Order returns represent a transaction between two parties. They can be a record of physical items being returned, or a credit being issued not tied to the return of an item, for example, a delayed shipping credit.

Order returns

Order return approval rules 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

Bundles represent a group of lines on an order. At a minimum, each line contains a single product ID 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

Subscription orders allow users to set up recurring orders for bundled products or services that are needed on a regular basis.

Bundle subscription items

Group orders endpoint returns a token which can be used to interact with the order associated with the invitation.

Group orders

Subscription items are used in conjunction with Subscriptions to order products on a recurring basis.

Subscription items

Subscription orders allow users to set up recurring orders for products or services that are needed on a regular basis.

Subscriptions

Catalogs represent containers for multiple categories used to group products for a specific audience. When a buyer is created, they are issued and assigned a default catalog unless an existing catalog ID is provided. Catalogs can be shared between buyers using assignments., and should be when appropriate.

Catalogs

Categories are used within a catalog to group products or other categories.

Products

Price schedules let you sell the same product with different prices or rules within the same marketplace. A price schedule can include quantity price breaks, min and max quantity per order, or whether to apply tax or shipping calculations.

Price schedules

Specs are name-value pairs, typically captured during user input when adding a product to an order. A spec value may have a price markup or markdown associated with it. In more advanced scenarios, specs can define a specific product variant. For example, a product may be available in 3 colors and 3 sizes and therefore have a total of 9 variants. OrderCloud will choose the correct variant to add based on the user-selected values, in this example color and size.

Specs

Product facets are extended properties (values on product XP) designated to drive data to support faceted navigation. Buyer list endpoints for products will populate and return facets in the meta object, a collection of facet names, values, and counts. Counts represent the total results that would be returned if the current set were 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

Bundles represent a collection of physical, digital, or abstract goods that are offered for sale, sometimes at a specially defined price, by a seller or supplier and are purchasable by buyer users via an order.

Bundles

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

Suppliers

Supplier users are people with access to the marketplace. A user's organization and roles define who they are and what they can do when they log in to the application.

Supplier users

Supplier user groups

Supplier addresses define a ShipFromAddress on a product or line item, or represent physical locations for product specific inventory.

Supplier addresses

OrderCloud is a cloud-hosted B2B, B2C, and B2X eCommerce platform exposed entirely via a RESTful API. It enables rapid development of custom, secure, and scalable eCommerce solutions. Spin up a fully functional commerce app in minutes and customize it to the limits of your imagination.

OrderCloud implements OAuth2 combined with our own notion of roles to control user authentication and authorization at fine-grain level. 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

A single seller organization is at the center of any OrderCloud solution, this seller is referred to as the marketplace owner. It is the only organization that can administer other organizations and their resources. It consists of users, user groups, and addresses. You should establish these components before setting up catalogs, products, buyers, and suppliers.

Marketplace owner

Buyers represent real-world entities to which the seller offers product catalogs and from which the seller receives orders. Buyers have many of the same resources as sellers (users, user groups, addresses) and much more, including cost centers, spending accounts, and approval rules. Assignments are a prevalent concept. Most resources can be assigned to a group, or entire buyer organization.

Buyer

Suppliers represent real-world entities, and are an optional type of organization. Like the marketplace owner, they contain users, user groups and addresses. Once established, products can be configured to auto-forward when ordered, or ordered directly from suppliers.

Supplier

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

Orders are the central concept within OrderCloud. They are 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. 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

OrderCloud offers robust pricing and visibility options involving roles, group-level assignments, buyer-specific pricing, and more. Resources that begin with "me" enforce all of those configurations into a set of endpoints that are generally all available with only the singular Shopper role. Whether authenticated as yourself or impersonating as someone else, you see only what that user is allowed to see. 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

Integrations support interactions between OrderCloud and customer middleware or other external systems.

API Reference