Use REST APIs to Manage Your Entities

Before you start using the REST APIs, ensure that you have the required roles and privileges.

For more information, see the Create Users and Assign Roles chapter in this guide. Let's see how you can use the REST APIs to manage your buying and ordering entities.

You can extend various entities in line with your business requirements apart from the corresponding TMF specifications and Oracle extensions:

• Product Offering (Product Offering Information)
• Party (Individual)
• Customer
• Party Account
• Shopping Cart
• Product Order

For more information, see REST API for Buying Experience in Oracle Digital Experience for Communications Buying Experience (2730574.1) on My Oracle Support at https://support.oracle.com.

Manage Sales Catalog

You create and use the sales catalog in the runtime. It contains a collection of the following:

• Product offers

• Catalog categories

• Product lines

• Product specifications

• Price lists

• Price or Alterations

• Recommendation rules

• Eligibility rules or Compatibility rules

• Migration rules

Each product offer in a catalog describes the relationships between products, the services used to realize the products, and the resources they require. You use the category to organize the product offers in the sales catalog. You can use the product catalog management REST APIs to get and manage various catalog entities, such as:

• Product offering: You can get all the product offers, bundles, and packages from the design-time applications. You can now add multiple commercial bundles to a package. The API response includes banners, marketing features, and product offer recommendations. You can separate catalogs by the catalog type using the product catalog management API. For example, product, service and resource. You can also define a rank for each of the attachments for product offers in the design time. Use the ranks to display the default image for the product offering in the customer shopping journey.

  In addition, you can use the queryProductRecommendation REST API to query product offer recommendations based on the product offering ID. These recommendations are very essential for e-commerce businesses in upsell or cross-sell scenarios.

• Product offering price: You can get different product pricing schemes to associate with all types of product offers such as package, bundles, and simple offers. In addition to component based pricing model, you can also associate prices to packages and Bundles (commercial and service bundle). The price associated at the package or bundle level will be inclusive of the prices of the required components of the package or bundle. Optional components of the bundle or package have a separate price. The various supported pricing schemes are listed here:

  • One-time, recurring, usage, or penalty fees

  • Attribute-based pricing, where prices are based on combination of characteristics values derived from product specifications

  • Product-based alterations and component alterations (in packages)

  • Volume-based discounts for non-asset product offerings

  • Filter product offering price at aggregate and compatible-offering levels based on the price list.

  • Define tax inclusive price by providing the tax percentage with the tax code associated to the product offering price.

• Price lists: You can get the prices for product offerings according to the price lists configured in design time. Price lists can be region-specific (for example, different currencies). To get prices for a product offering that belongs to a specific price list, provide the price list ID or name as the query parameter in the GET productOffering endpoint. Similarly, to get the correct price for a line item, specify the price list information in the payload you create for the shopping cart and product order requests. Otherwise, the application creates the items with only 0 (zero) price. You can perform price adjustments at a component level, such as a bundle.

  Product lines: You can get a product line to group-related product offers together.

  Product specifications: You can get the product attributes associated with a product offer to define the technical aspects of that offer.

  Inventory availability: You can pass the SKU numbers with comma separated values along with locations to check the inventory availabilities. The API response has SKU number, product offer Id, channel types along with regular and preorder stock available as true or false. True means available.

Search in the Sales Catalog

Prospects and subscribers can find plans, devices, and accessories using the Oracle Buying Search Service. Search service options include:

• Catalog browsing:

  The customers can browse and filter different product offers based on their requirement using the GET productOffering by list APIs. The customer can apply multiple filter criteria to minimise the search result for a better browsing experience. You can also get the details of a specific product offer using the GET by ID API. Here are the lists of filters and other functionalities that are supported by the productOffering APIs:

  1. Filters product offers based on the type (packages, services, devices, accessories, service bundles, and commercial bundles).
  2. Filters product offers based on provided categories.
  3. Filters product offers based on multiple eligibility criteria.
  4. Filters products offers that are on a specific price range.
  5. Filters product offers based on price list name.
  6. Filters products that are shippable, sellable, and for which installation is required.
  7. Filters product offers based on user defined characteristics that are enabled in the design time.
  8. Filters product offers that have banners or promotions associated with.
  9. Filters product offers based on certain search tags and banner names.
  10. Sorting of product offers based on price and name in ascending or descending order.
  11. In case of packages and bundles, the customer can see the detailed price break-up for the each bundled products, including list price, adjusted price, tax, and any other alterations.
  12. Supports filters on product offers on after marketing extension fields.
  13. Supports browsing and also shows price break up of compatible items (device, service, and accessories) in the context of the parent (package and bundles).
  14. Supports query on related offers: Related Offers refers to offers that are linked or associated in some way. If a customer is viewing a specific offer, related offer could be the additional services that the provider thinks the customer might be interested in.
• Auto suggest:

  Search provides (Type-ahead) API, that can help the customers to provide out-of-the-box support of providing suggestions of product offers as they start typing any keyword in the search bar.

• Keyword search:
  The search also supports search APIs for keyword search, sorting, and browsing product offers using POST APIs:

  • Keyword (free-text) search:

    For the search bar use-case where if a customer tries to find the product offers with a specific keyword, and if the keyword is present in any searchable fields (name, description, category name, banner name, searchTag, banner description, marketingFeature name, marketingFeature description, marketingFeature shortDescription, and commercial name), then those products are returned in the API response.

  • Sorting:

    Search API supports sorting by name and sorting by prices of product offers. Sorting order can be ascending or descending based on input parameters. If no sorting criteria is passed then the product offers are sorted in the default order that is, Package > Device > Accessory > Service > Commercial Bundle > Service Bundle.

• Browsing and filtering of product offers POST:

  The Search API also supports the feature of browsing and filtering product offers using the POST API. You can modify the request payload using the filter criteria to filter product offers based on type, categories, eligibility criteria, pricelist name, price range, characteristics, and extension fields. You can also filter product offers that have banners or promotions, or that can be shipped, sold, or require installation, using this API.

Manage Quotes

You can create a quote for package purchases using the Quoting API. You can create quotes using multiple price lists that are defined in different currencies. You can update quotes, such as changing the account details, packages, optional items, devices and services, header level notes and email addresses. You can save your quote using the Enterprise buyer email address and retrieve it when needed.

Manage Shopping Cart

Your customers use shopping carts to temporarily save the selected products and retrieve them later for a purchase. The customer can be a subscriber or an anonymous user. You can use the shopping carts REST API to create, update, retrieve, and check out shopping carts. You can also do the following using this API:

• Group cart items to represent items that belong to a specific person, such as a member in a family plan, and assign it a nickname.

• Let your customers purchase devices that aren't part of any package and associate the device with the package that they purchase. They can also associate any existing device with their new package. When they terminate the package, all the associated devices will be terminated.

• Let your customers procure devices on a lease basis for first-time purchases. The device that you procure can be part of a package or an individual product, but you must associate it with the package by defining a relationship.

• Get detailed item price break-up for your products, including alterations:

  • List Amount: Starting price of the offer.
  • Alteration Amount: The discount amount that's applied on the offer. Currency value in case of discount is %.
  • Total Alteration Amount: The total discount amount on the offer.

• Support advanced discounting features such as:

  • Time Based Discounts: Discounts can be provided, that are valid only for a certain period after the purchase or service activation.
  • Limited Time Discounts: Discounts can be provided, that are short lived and are valid during a specific occasion.
  • Criteria Based Discounts: Discounts can be provided based on user's (Subscriber and Anonymous user or guest) location parameters. Also, this could be extended in field to support discounts based on extension parameters.

• Send shipping method, tracking ID, and URL in the API response to help in order fulfillment.

• Enable or disable eligibility and compatibility-related validations.

• Send the channel-specific URL from external clients in the shopping carts.

• Support manual price override for simple offers, packages, and bundles by a support specialist role during cart creation or update. The manual override allowed can't be above the floor limit.
• Support ability to either apply manual price overrides on top of the system discounts (discount amount or discount percentage on the item price) or completely override the system discount with the manual price overrides.
• Support out of the box extensions in the shopping cart.
• In addition to the existing eligibility criteria, Customer Type is a newly supported criterion in the shopping cart. Subscribers with at least one active product are treated as existing subscribers where as others are treated as new subscribers.
• Support family plan and account hierarchy in the shopping cart.
  • The shopping cart API with accountHierarchyChange flag will create an order when the account has atleast one active asset present under it and internally the account hierarchy will be changed. The new target parent will be able to query the asset after the hierarchy change and the old parent (source parent account) won't be able to query the asset.
• Support change of owner account, billing account, or service account in the case of family plan within the account hierarchy.
• Support package termination when aggregate discounts were applied in the shopping cart.
• Support for location based discounts in the shopping cart for new purchase, update, and termination.
  Note: To apply the location based discount, you must pass location parameters under eligibility profile in the request payload.
• Create preorder for future dated product offerings of type, device or accessory with subtype as preorder.
• Support ability to enable a tenant or a system integrator to centrally define the business logic using Business Logic Extensions (BLE). The business logic can then be triggered from the shopping cart. The business logic can vary from simple to complex validations, algorithm, or calculations.
• Support computation of tax of a cart item internally. If the tax percentage is associated to the price of a product offer then the tax percentage will be used to compute the tax internally.
  Note: An example use case for this could be integrating with an external pricing system to manually override the price of a cart item.
• You can now abandon and purge shopping carts that can be triggered using specific user-roles, using a new Bulk job API that can be triggered as an on-demand job (this functionality is specifically available for Bulk job administrator and Business Operations Specialist roles). This complements the current functionality that abandons and purges the shopping carts as a scheduled background job run at mid-night every day.

For stock increment or decrement, in the API request, you have to pass SKU number, channel code, quantity, action (INCREMENT/DECREMENT) and stock type (REGULAR/PREORDER). In API response, you will get id, href, SKU number, channel code, regular, or preorder stock final value after the action taken, stock availability date, and market release date. In addition, you can use the configuration REST API to configure the abandoned shopping cart settings. For more information, see Configure Shopping Carts chapter in this guide.

Manage Product Configurator

You may sometimes configure products in the runtime. For example, add simple products to one or more complex bundles or update subscriber's existing assets at the runtime. You typically do this to add a promotion bundle or a standalone configurable product to a quote or order. You can use the product order management REST APIs to do the following:

• Get all the existing product offers and bundles.

• Configure promotion bundles.

• Add optional child products.

• Update configurable attributes for bundles and child products, for example, update the speed for high-speed internet service.

Manage Product Orders

You can use the product order management REST APIs for product orders.

The product ordering API resource lets you create, view, get, update, and cancel product orders and also get an order cancellation request. You can also do the following using these APIs:

• Let your customers purchase devices that aren't part of any package and associate the device with the package that they purchase. They can also associate any existing device with their new package. When they terminate the package, all the associated devices will be terminated.

• Let your customers procure devices on a lease basis for first-time purchases. The device that you procure can be part of a package or an individual product, but it has to be associated with the package by defining a relationship.

• Search for specific product orders.

• Enable or disable eligibility and compatibility-related validations.

• Get detailed item price break-up for your products, including alterations:

  • List Amount: Starting price of the offer.
  • Alteration Amount: The discount amount that's applied on the offer. Currency value in case of discount is %.
  • Total Alteration Amount: The total discount amount on the offer.

• Support advanced discounting features, such as aggregate discounts, for first-time purchases.

• Group order items to represent items that belong to a specific person, such as a member in a family plan, and assign it a nickname.

• Send shipping method, tracking ID, and URL in the API response to help in order fulfillment.

• Capture the estimated fulfillment start date received from the fulfillment application in your product order.

• Defer submission of orders to the fulfillment application when created using the POST method of the product ordering API. These orders are created in the pending state. Your subscribers or support specialists can later update these orders created based on their requirement and then submit for fulfillment using the PATCH method.

• Track the base product order life cycle state in accordance with the Cancel product order life cycle states as the cancellation request is being processed by the downstream fulfillment system.
• Support manual price override for simple offers, packages, and bundles by a support specialist role during order creation or update. The manual override allowed can't be above the floor limit.
• Support ability to either apply manual price overrides on top of the system discounts (discount amount or discount percentage on the item price) or completely override the system discount with the manual price overrides.
• Support out of the box extensions during order creation or update.
• Query product order using anonymous role.
• In addition to the existing eligibility criteria, Customer Type is a newly supported criterion in the product order. Subscribers with at least one active product are treated as existing subscribers where as others are treated as new subscribers.
• Support family plan and account hierarchy in product order.
• Support change of owner account, billing account, or service account in the case of family plan within the account hierarchy.
• Support package termination when aggregate discounts were applied in product order.
• Support location based discounts in product order for new purchase, update, and termination.
  Note: To apply the location based discount, you must pass location parameters under eligibility profile in the request payload.
• Create preorder for future dated product offerings of type, device or accessory with subtype as preorder.
• Bulk submission of preorders to fulfillment (by bulk job administrator).
• Bulk update to market release date for preorders (by business operations specialist).

You can perform bulk operations on product orders by creating and running jobs using the bulkJob API. You can use this REST API to do the following:

• You can create the product orders in bulk. Also, submit the previously created product orders to fulfillment in bulk.

• Get bulk job details by ID

• Get all the bulk jobs matching specific criteria, for example, status, completion date, or both.

A new background job added runs every day in the 24 hours interval. This job queries all the preorders that are in pending status and for which the market release date (MRD) is today (current date). This job submits these orders to the fulfilment system for further processing. For more information, see the Manage Bulk Operations chapter in this guide.

Manage Products (Assets)

You can use the product management REST APIs to get the products or assets.

A product consists of one or more services or resources. The Products API resource lets you view and change group name and alias for products. You can calculate disconnect penalty for a product and get package change options using this resource. You can also do the following:

• Search for specific products.

• Get products that are purchased on lease basis.

• Get products that are purchased outside of a package but are associated with the package. Terminating the package terminates all the devices associated with that package.

• Get detailed item price break-up for your products, including alterations:

  • List Amount: Starting price of the offer.
  • Alteration Amount: The discount amount that's applied on the offer. Currency value in case of discount is %.
  • Total Alteration Amount: The total discount amount on the offer.

• Modify assets, such as adding a new optional product or changing the asset characteristics.

• Get the list of assets upto root parent (package) level, installed in a given service address or service ID (This functionality is specifically available for System Integrator and Support Specialist roles.)

Manage Agreements

You can use the agreements REST API to get the terms and conditions committed to enter into a contract.

Manage Accounts

You can use the account management, customer management, and party REST APIs to get all the accounts to whom the service is delivered or billed. For example, party accounts, customers, and individuals. These resources help you to create, delete, get, and update party accounts, individual accounts, and customers.

You can get payment methods associated with an account. Also, search for customers and party accounts using the engaged party ID or related party ID respectively. You can create account hierarchy between accounts. You can update account hierarchy of accounts using Account Management API when there are no open carts, orders, or assets. Single level account hierarchy is supported.

You can create accounts with valid account types that are defined in business configuration.

You can attach one or more documents of the following types: pdf, jpg, jpeg, png, docx, doc, gif, and bmp for party entity (Individual) to support use cases such as identification documents.

Note:

You can store the documents in any document management system through the document management adapter. You must configure the CXIF document management adapter to work with the preferred document management system.

Manage Promotions

You can use the promotion REST API to get all the available promotions and apply them to the customers who meet the specified criteria. You can get all the promotion details or a specific promotion by using the GET by ID method. Here are the filter criteria you can use to apply promotions:

• Product Offering
• Product Line
• Product Specification
• Location-Specific attributes
• Start date and end date based criteria
• Partial or exact promotion name
• Price list name or price list ID
• Entity ID or entity name
• State, City, Postal Code, and Country

Manage Contracts

Generate Contract on Order Completion

The ProductOrder based contracts will get generated only when the Business Process Config 'generateContractOnOrderCompletion' is set to true.

After a Product order is created (via Shoppingcart checkout or ProductOrder API), you can use the generateContract REST APIs on these entities to create a Contract creation job. The system will generate a contract document as a PDF when the product order is fulfilled by the order management system. You can view the generated contract document under the related documents of agreement. The contract document will have a unique contract number added.

Manage Generic Contracts

Here's how you can use the Generic Contracts API when the Business Process Config 'generateContractOnOrderCompletion' is set to false.

1. You can use the Contracts REST APIs for managing the contracts.
2. The Contract Management API resource lets you create the generic contract document, download the contract document, get, and update the contract record information.
   1. Generate Contract Document: By using POST API, you can generate the generic contract document for any external entity such as 'ShoppingCart' or 'ProductOrder' by passing the externalEntityId, entityType, and templateName in the request payload. The allowed roles are Anonymous, Subscriber, and Support Specialist.
   2. Update Contract Life Cycle Status: By using PATCH API, the contract administrator can update contract document life cycle status with 'accepted', 'active', 'inactive', and 'obsolete' statues based on the business needs.
   3. Download Contract Document: You can download the contract document. The allowed roles are Subscriber, Support Specialist, and Contract Administrator. The subscribers are allowed to download their contract documents only. Support specialists and contract administrators are allowed to download any contract documents.
3. The Generic Contract API expects input in the form of JSON data. The JSON data is divided into two sections: a fixed flat attributes section and a dynamic section that varies based on the template selected for generating the contract.
   • The fixed flat attribute section includes fields such as templateName, externalEntityId, entityType, externalEntityHref, accountId, accountNumber, externalContractNumber, validFrom, and validUpto.
   • The dynamic section starts with the field input and is further divided into header, body, and footer. The fields under the header, body, and footer vary based on the selected template to generate the contract.
   • Values for placeholders existing in the header section of the template should be provided under the "header" key in the JSON payload. Similarly, for placeholders existing in the body section of the template, values should be placed under the "body" key, and for placeholders in the footer section, under the "footer" key.
   • For table entries, values should be organized in an array because a table can have more than one row or column.

Manage Subscriber User Creation

As part of the subscriber purchase, you can create user accounts in the identity management system using the following two APIs:

1. https://<server>/api/buyingUserManagement/v1/onboardUser
2. https://<server>/api/buyingUserManagement/v1/user

Note: In the case of family plan, you can also create users for the child accounts in the hierarchy using this API: https://<server>/api/buyingUserManagement/v1/user

For more information, see REST API for Buying Experience in Oracle Digital Experience for Communications Buying Experience (2730574.1) on My Oracle Support at https://support.oracle.com.

Manage SKU Inventory

You can create and use the SKU inventory in the runtime. It contains a collection of the following:

• SKUs with Product Offers
• Channels
• Stores
• Inventory for SKU and Channel combination
• Global Threshold Configuration
• Channel and SKU Threshold Configuration

SKUs with Product Offer: SKUs with product offer will be published from Launch. You can get all the product offers along with their SKUs, only SKUs with their attributes or you can fetch only specific SKU or product offer by Id or SKU number or with Siebel Id. You can use PATCH and PUT APIs to modify existing SKU or add new SKU to existing product offer.

Channels: Channels will be created by Inventory Management Specialist. You can get all the channels or fetch only specific channel by Id. You can use PUT and PATCH API to update the channel information. You can't modify the channel code.

Stores: Store will be created by Inventory Management Specialist associating to one channel code. You can't assign same channel code to multiple stores. You can get all the stores or fetch a store by Id.

Inventory: Inventory will be created by Inventory Management Specialist. You can get all the inventories or specific inventory by passing SKU number and channel code. The API response will have SKU number, channel code, regular stock or preorder stock or both, stock availability date, and market release date.

Global Threshold Configuration: Global threshold configuration will be set by Back Office Specialist.

Channel and SKU Threshold Configuration: The threshold configuration will be set to specific channel and SKU combination. This configuration will be set by Back Office Specialist.

Events are generated:

• If the stock quantity is less than or equal to threshold value, an event will be generated.
• If the stock quantity is zero, an event will be generated.
• If the stock quantity is less than or equal to safe limit value, an event will be generated.

Onboarding New User in the Shopping Cart Checkout Process

Onboarding User

• When you’re checking out, you’ll capture details of the customer information.

  These include customer details such as last name and first name. These also include customer type such as retailer, end customer, customer from an organization, or partner. The payment method is also captured. Entities such as individual, customer, and partyAccount are created.

• When you checkout, along with checkout, order processing also occurs in the shopping cart API. An order is created for the particular checkout.

  The payment details are processed and then the application realizes that the user is anonymous and not yet registered. Buying Experience application will send an email notification to you based on the email ID that you shared as a part of checkout process. In case of family plan, Buying Experience application will send email notification to child accounts as well based on the email address.

• You’ll receive the email.

  In the email, there’s a URL.

• Onboarding supports hierarchy of accounts also. You must provide entities such as individual, customer, and partyAccount in ArrayList format.

Registering User

• Click the URL to register yourself as the user.

  After clicking the URL, you’ll reach the user registration page.

• Provide personal details such as personal information and credit card information.
• Click Register, the onboard user API is run.
• Provide all the required sign in credentials and these will be stored in the Identity Cloud Service.

Note: If you click the registration link beyond the expiration time then you’ll receive another email notification with the latest link to register.

• You’re created as the user in the Identity Cloud Service.

  The Identity Cloud Service will send an email to you to reset the password.

• When you click the reset password link in the email, you’ll reach the Identity Cloud Service page and you can reset the password.
• After you reset the password, you can use your user ID and password to sign into the Buying Experience application.
• Note: You can complete the registration process using APIs for standard attributes such as code or user name or account number or order number, or email address attribute.

Custom Claim

Custom claim is any attribute other than the standard attributes of user ID or email address. Custom claim is an attribute such as party number for example, using which the Buying Experience application can identify and register the user.