Comviva

A shopping cart is a digital interface within an online or retail platform that enables users to select, organize, and manage items they wish to purchase along with a omnichannel capability. The shopping cart allows customers to add products, adjust quantities, and review their selections before proceeding to checkout. It plays a crucial role in facilitating the online shopping experience by providing a centralized location for collecting desired items, calculating totals, applying discounts or promotions. Shopping cart also supports in life sales journey of the services owned by the customer, for e.g. change of plan, termination of services, buying add-on services etc. BlueMarble shopping cart is compliant with TMF-663 (shopping cart API) with necessary extensions.

Key Features:
- Multiple product categories and multiple process context support through offer container
- Capability to add, remove or update cart item(s), offer container(s) or shopping as a whole.
- New buy and in life sales journeys
- Price points
- Pricing based on channel, place, market segments and product terms
- Attribute based pricing
- Support for external price override
- Manual price override based on roles
- Agreement based pricing
- Promotions at the cart item, offer container and cart levels
- Price adjustment using gift cards or wallet balance
- Static bundles, bundles inside a bundle, bundling of offerings across different offer container categories
- Shopping Cart rules
- Category Cardinility Validation and Mutually Exclusivity
- Save carts for anonymous journeys
- Access Control based on user type and permissions assigned to user
- Non-persistence in shopping cart
- Cart Validations
- Move cart to different channel / place
- Context store and context data signature verification

Introduction

Query Shopping Cart

Retrieves a shopping cart using the shopping cart Id

Get Shopping Cart by ID

This API can be used to query one or more shopping carts by providing one ore more filter criteria,
for e.g. get all shopping carts for a specific customer, get all shopping carts which contains
a specific product offering and created in last one hour. Using the fields query parameter,
it is possible to get only relevant fields in the response which if not provided, the complete
shopping cart will be returned in the response.


Get Shopping Cart(s)

Manage Shopping Cart

This API allows to create a shopping cart and associate it with a specific channel, place, market segment and related parties.Channel, place and market segment must be associated when creating the cart as it influences the product offerings which can be added to the cart and its price. Shopping cart can be created with one or more offer containers in one call or without any container.


Create Shopping Cart

Shopping Cart Patch API allows to update specific attributes of child objects or create a new child object.
This also allows to execute multiple operation on multiple objects at the same time For e.g. add a cart item,
update quantity of existing cart item, create a note at offer container level which otherwise requires to call multiple APIs.
Patch operation is not generalized and supports create / patch / delete of only certain objects.
Request body can contain list of patch operations. Each of them must have operation, path and value defined.
Operation can be add / patch / delete / replace. Path should be the complete path of the object to be created or updated.
Fields defined in 'Value' is used to create / update the object as defined in the path.


Patch Shopping Cart

Removes all offer containers and its content while customer and contact information is retained

Empty Shopping Cart

This API can be used to permanently delete a shopping cart from the database. This also generates a event 'ShoppingCartDeletedEvent'.Deleting a shopping cart also deletes the associated checkout data.


Delete Shopping Cart

This API can be used to add one or more offer containers into the shopping cart. Each offer container must have category and process context defined.


Add Offer Container

This API can be used to replace the cart items in one or more offer containers in a single call.
At offer container level, only additionalAttributes are replaced with what is received in the request and rest of the attributes are ignored.
Offer containers are uniquely identified using the portfolioId so portfolioId must be passed in the request to update an
existing offer container. If the portfolioId is not passed in the request, new offer container is created.
For the existing cart items in the existing offer containers, product.id must be passed in the request.
If product.id is not passed for cart item in the request, a new cart item is created.
Existing cart items if not sent in the request are deleted.


Update OfferContainers

This API can be used to delete an offer container from a shopping cart based on the offer container id. The complete content of the offer container is removed.


Delete offer container

This API can be used to add one or more cart items into an offer container. Each item must have either a product offering or product associated to it.


Create Cart Item

This API can be used to update one or more cart items within an offer container in a single call.
All the existing cart items are removed and replaced with all the cart items received in the request.


Update Cart Items

Deletes a cart item from a given offer container in the shopping cart

Delete Cart Item

Validates the shopping cart and generates a validity token if successfully validated. Following validations are done:
- Validates Signature
- Check promotion validity and reapply promotion as per the latest definition
- Validates mandatory characteristics are present
- Check the validity of the product offerings based on validity dates, channel, place and market segment
- Reprice the cart

Validate Shopping Cart

This API can be used if shopping cart needs to be transferred to a different channel or place. Client needs to call this API explicitly
if they decide to transfer the cart and if transferred successfully, all the rules, pricing, promotions are evaluated based on the new channel / place.
Before the transfer can happen, validation is done by service to ensure that the existing offers and promotions in the cart are valid for the new channel / place and if any discrepancies
it either removes them or send error in response based on the selection made for offerAutoRemoval and promoAutoRemoval in the request.

Additional mandatory fields :
 - Either channel or place


Modify Channel and Place

Recalculates the price of entire shopping cart. This API can be used to query shopping cart with the latest price at that point of time. For e.g. when a user logs in, the shopping cart created in the past needs to be recalculated and show the latest price

Do Base Price

Discounts and Price Adjustments

Allows to apply one or more promotions at the cart item, offercontainer or cart level.
Each promotion in the request must be accompanied with the promotion signature along with promotion Id.
Promotion signature is used to check the authenticity of the promotion with respect to the current shopping cart.
In case a promotion is applicable for a product offering (cart item level) then actionObjectId must be passed in the request.


Apply Promotion

This API endpoint allows the removal of a promotion from a cart item, offer container or shopping cart.  It is utilized when a customer opts to revoke a previously applied promotion or when a promotion becomes ineligible according to qualification rules, necessitating automatic removal by the client UI.

Remove Promotion

This API endpoint allows the application of a downpayment to the price of a specific item within a particular offering. It either creates a new item price for the downpayment or updates an existing one with the amount specified in the request. Additionally, it adjusts the original item price to reflect the downpayment. Downpayments can only be applied to designated product offerings, and the downpayment amount must exceed the minimum amount defined for the product offering.


Apply downpayment

This API endpoint allows a user with specific permissions to adjust the price of items in a shopping cart. Price adjustments can be made at the cart item level by percentage, fixed value, or by overriding the price entirely. The user must have a role with defined price adjustment limits; otherwise, price overrides will not be permitted.


Apply manual price override

Removes manual price override from a cart item

Remove Manual Price Override

This API can be used to adjust non-recurring prices (say Onetime charge) of the cart total price using gift card or wallet balance or both.
This updates tne amountPayable of each item price after adjusting it with gift card and wallet balance.
Multiple gift cards can be added. Wallet adjustment is allowed only once and if reapplied,
it overwrites the existing wallet adjustment.


Adjust Non-recurring Prices

This API can be used to remove non-recurring price adjustment (gift card/wallet balance) from the shopping cart.

Remove Non-recurring Price Adjustment

Amendment Shopping Cart

This API can be used to create an Amendment cart. Amendment cart needs to be created to amend an order which
is in progress where user can make the changes and submit again. The amendment cart is created as a
copy of the shopping cart which was converted to the order being amended. It restricts updating items
which are not amendable and also calculates the price that user may need to pay additionally or get back
as refund as a result of the amendment.


Create Amendment Cart

Shopping Cart Notes

This API can be used to add one or more notes into the offer container

Create Note on Offer Container

Updates a note on a given offer container in a shopping cart

Patch Note On Offer Container

Deletes a note on a given offer container in the shopping cart

Delete Note on Offer Container

This API can be used to add one or more notes into the cart item

Create Note on Cart Item

Updates a note on a given cart item of a offer container in the shopping cart

Patch Note on Cart Item

Deletes a note on a given cart item of the given offer container in the shopping cart

Delete Note on Cart Item

Anonymous Cart

Save a cart to retrieve later. Can be used by unregistered user to save and retrieve cart

Save Cart

A saved cart id can be retrieved by this API by providing the unique id that was returned in the response of save cart

Get Saved Cart ID

Transfer a shopping cart from an anonymous user to another anonymous user or a customer

Transfer Shopping Cart

Simulated Product Price

This API endpoint retrieves the prices and applicable price points for one or more product offerings as if they were added to a specified shopping cart. The prices are calculated by simulating the addition of each product offering to the existing cart, one by one. If a product offering is associated with specific terms or configurable characteristics, these details should be included in the request.


Get Product Offring Price

Configuration

This API can be used to configure frequency of cron jobs to abandon, expire and delete shopping carts. It also takes parameters required by the cron jobs like cartActivePeriod, cartExpiredPeriod, conditions based on which specific shopping carts are processed. The scheduler configuration becomes effective immediately once the API is executed successfully.


Configure Scheduler


Allows you to define one or more price adjustment limits for different roles.
Limit can be defined at the cart item / offer container / shopping cart level for each priceType and recurringChargePeriod for a given role.
Limit can be defined either in percent or the amount.
If the limit is specified in positive number, price can only be reduced as per limit defined.
If the limit is defined in negative number, price can only be increased as per the limit specified.

Additional mandatory fields :

- Either priceAdjustmentLimit.limit.percent or priceAdjustmentLimit.limit.amount


Add/Update Price Adjustment Limit

Allows to delete existing price adjustment limit

Delete Price Adjustment Limit

Allows to query price adjustment limits based on level, priceType, recurringChargePeriod and role. If no criteria is provided, all records are retrieved.

Get Price Adjustment Limit(s)

Default

Shopping Cart

Production

Sandbox

The Shopping Cart component is responsible for handling all aspects related to the management and manipulation of shopping carts within the e-commerce system. It encompasses functionalities for creating, updating, and deleting shopping carts, as well as adding, removing, and modifying items within them. This component serves as the backbone of the shopping experience, enabling users to interact with their carts and make changes as needed.Key Features:<ul class="slate-ul"><li class="slate-li">Multiple product categories and multiple process context support through offer container</li><li class="slate-li">Capability to add, remove or update cart item(s), offer container(s) or shopping as a whole.</li><li class="slate-li">New buy and in life sales journeys</li><li class="slate-li">Price points</li><li class="slate-li">Pricing based on channel, place, market segments and product terms</li><li class="slate-li">Attribute based pricing</li><li class="slate-li">Support for external price override</li><li class="slate-li">Manual price override based on roles</li><li class="slate-li">Agreement based pricing</li><li class="slate-li">Promotions at the cart item, offer container and cart levels</li><li class="slate-li">Price adjustment using gift cards or wallet balance</li><li class="slate-li">Static bundles, bundles inside a bundle, bundling of offerings across different offer container categories</li><li class="slate-li">Shopping Cart rules</li><li class="slate-li">Category Cardinility Validation and Mutually Exclusivity</li><li class="slate-li">Save carts for anonymous journeys</li><li class="slate-li">Access Control based on user type and permissions assigned to user</li><li class="slate-li">Non-persistence in shopping cart</li><li class="slate-li">Cart Validations</li><li class="slate-li">Move cart to different channel / place</li><li class="slate-li">Context store and context data signature verification</li></ul>

The Shopping Cart component is responsible for handling all aspects related to the management and manipulation of shopping carts within the e-commerce system. It encompasses functionalities for creating, updating, and deleting shopping carts, as well as adding, removing, and modifying items within them. This component serves as the backbone of the shopping experience, enabling users to interact with their carts and make changes as needed.

The &apos;Get Shopping Cart&apos; component provides functionalities to retrieve information about shopping carts. It allows users to query various aspects of a shopping cart, including its contents, prices and promotions. This module enables both customers and administrators to view and analyze the contents of shopping carts, facilitating order management and customer service processes

The 'Get Shopping Cart' component provides functionalities to retrieve information about shopping carts. It allows users to query various aspects of a shopping cart, including its contents, prices and promotions. This module enables both customers and administrators to view and analyze the contents of shopping carts, facilitating order management and customer service processes

The &apos;Manage Shopping Cart&apos; component is responsible for handling all aspects related to the management and manipulation of shopping carts within the e-commerce system. It encompasses functionalities for creating, updating, and deleting shopping carts, as well as adding, removing, and modifying items within them. This component serves as the backbone of the shopping experience, enabling users to interact with their carts and make changes as needed.

The 'Manage Shopping Cart' component is responsible for handling all aspects related to the management and manipulation of shopping carts within the e-commerce system. It encompasses functionalities for creating, updating, and deleting shopping carts, as well as adding, removing, and modifying items within them. This component serves as the backbone of the shopping experience, enabling users to interact with their carts and make changes as needed.

This API suite allows for the application of discounts through various promotions at the item, offer container, or shopping cart levels. It also supports price overrides by agents and adjusts the total payable amount in the cart based on upfront down payments, redeemed gift vouchers, or wallet balances.

This API suite allows for the application of discounts through various promotions at the item, offer container, or shopping cart levels. It also supports price overrides by agents and adjusts the total payable amount in the cart based on upfront down payments, redeemed gift vouchers, or wallet balances.



Once an order is submitted, the status of the associated shopping cart is updated to &quot;submitted,&quot; making it read-only and unmodifiable. If a user wants to make changes to the order after submission, this can be done through an order amendment process. However, items that have reached the Point of No Return (PONR) cannot be modified, even through this process.Blue Marble order management provides APIs that allow an order to be put on hold. The client can then query the order line items to determine which items can still be amended and which cannot. Amendments are initiated using an amendment shopping cart, which initially loads all line items with a status of &quot;Keep.&quot; The user can then modify the cart and resubmit it.When an order is modified through the amendment shopping cart, it may result in new products being added or existing products being removed, potentially leading to price changes. If the price increases, the user may need to pay the additional amount. Conversely, if the price decreases, the user will be refunded the balance.

Once an order is submitted, the status of the associated shopping cart is updated to "submitted," making it read-only and unmodifiable. If a user wants to make changes to the order after submission, this can be done through an order amendment process. However, items that have reached the Point of No Return (PONR) cannot be modified, even through this process.

Blue Marble order management provides APIs that allow an order to be put on hold. The client can then query the order line items to determine which items can still be amended and which cannot. Amendments are initiated using an amendment shopping cart, which initially loads all line items with a status of "Keep." The user can then modify the cart and resubmit it.

When an order is modified through the amendment shopping cart, it may result in new products being added or existing products being removed, potentially leading to price changes. If the price increases, the user may need to pay the additional amount. Conversely, if the price decreases, the user will be refunded the balance.

Provides set of APIs to add, update or delete notes at item or offer container level

Provides set of APIs to add, update or delete notes at item or offer container level

Provides set of APIs to support anonymous journey

Provides set of APIs to support anonymous journey

Provides API to calculate the price of offerings in a simulated mode before they are added to the cart.

Provides API to calculate the price of offerings in a simulated mode before they are added to the cart.


This set of APIs enables the management of shopping cart configurations, including scheduling settings and defining price adjustment limits based on user roles.

This set of APIs enables the management of shopping cart configurations, including scheduling settings and defining price adjustment limits based on user roles.

This API configures the frequency of cron jobs for abandoning, expiring, and deleting shopping carts. It also accepts parameters needed by these cron jobs, such as cartActivePeriod and cartExpiredPeriod, and conditions for processing specific shopping carts. The scheduler configuration takes effect immediately upon successful execution of the API

This API configures the frequency of cron jobs for abandoning, expiring, and deleting shopping carts. It also accepts parameters needed by these cron jobs, such as cartActivePeriod and cartExpiredPeriod, and conditions for processing specific shopping carts. The scheduler configuration takes effect immediately upon successful execution of the API

The period in which if the cart is not updated by user then cart is expired. Value can be defined in minute(s), hour(s) and day(s). For e.g 4 hour(s)

cartExpiredPeriod

The period in which if the cart is not converted to order then cart is abandoned. Value can be defined in minute(s), hour(s) and day(s). For e.g 120 minute(s).

cartActivePeriod

This attribute takes the cron job expression to run a task to abandon/expire cart at specific frequency.

abandonedExpiredCartRepeatFrequencyTime

This attribute takes the cron job expression to run a task to delete expired shopping carts at specific frequency.

deleteExpiredCartRepeatFrequencyTime

This attribute takes the cron job expression to run a task to expire a shopping cart quote based on it's validity at specific frequency.

quoteExpiredCartRepeatFrequencyTime

The period for which cart will remain in QUOTE_CREATED status. Value can be defined in minute(s), hour(s) and day(s). For e.g 6 day(s)

quoteValidityPeriod

conditionalPeriods

description

It is a unique identifier assigned to a specific transaction within a system or application.This is required to identify the sequence of API calls related to a specific transaction in the logs for monitoring and troubleshooting


X-Transaction-Id

It is a unique identifier assigned to a particular transaction, request, or event in a distributed system.It serves the purpose of linking related messages, actions, or components together as they traverse various parts of the system.This is required to identify the sequence of API calls related to a specific record in the logs for monitoring and troubleshooting


X-Correlation-Id

Name of the source channel that sent the request to be passed by consumer component.This is required to identify the API calls in the logs which have come from specific channels


X-Source-Channel

It is a unique code or identifier that is assigned to each tenant in a multi-tenant system or application.In a multi-tenant architecture, a single instance of the software or service serves multiple clients or tenants, keeping their data and configurations separate to ensure privacy and data isolation. This is required to identify the API calls related to a specific tenantin the logs for monitoring and troubleshooting


X-Tenant-Id

Authorization

An  "error code" is a numeric or alphanumeric identifier employed to signify a particular error or problem that has arisen within a service

code

An "error reason" refers to an explanation or description of the underlying cause or reason for a specific error or issue that has occurred within a service

reason

This indicates the HTTP status code linked to this error

status

The "timestamp" at which error occurred" refers to the specific date and time when an error or issue occurred within a service

timestamp

An "error message" is a specific piece of information or notification that is generated by a service to inform the user that an error or issue has occurred

message

errors

This API enables to define price adjustment limits for various roles. These limits can be set at the cart item, offer container, or shopping cart level for each price type and recurring charge period associated with a given role. Limits can be specified either as a percentage or a fixed amount. A positive limit denotes the maximum allowable reduction, while a negative limit denotes the maximum allowable increase.

Additional mandatory fields :<ul class="slate-ul"><li class="slate-li">Either priceAdjustmentLimit.limit.percent or priceAdjustmentLimit.limit.amount</li></ul>

This API enables to define price adjustment limits for various roles. These limits can be set at the cart item, offer container, or shopping cart level for each price type and recurring charge period associated with a given role. Limits can be specified either as a percentage or a fixed amount. A positive limit denotes the maximum allowable reduction, while a negative limit denotes the maximum allowable increase.



priceAdjustmentLimitId

This API allows to delete existing price adjustment limits.

This API allows to delete existing price adjustment limits.

This API allows querying of price adjustment limits based on level, price type, recurring charge period, and role. If no criteria are provided, all records are retrieved.

This API allows querying of price adjustment limits based on level, price type, recurring charge period, and role. If no criteria are provided, all records are retrieved.

Use this to query based on level at which limit is applied.

level

Use this to query based on price type on which limit is set.

priceType

Use this to query based on recurring charge period associated to limit.

recurringChargePeriod

role

Allowed values are cartItem,  offerContainer and shoppingCart

Limitation can be defined separately for each price type

Refers to a specific interval or time frame during which a charge or payment is repeatedly applied for a particular service, subscription, or product. For e.g.  Monthly, Quarterly, Annually, etc.

Role of the user. Price adjustment limit can be defined separately for each role

Defines the limit in amount or percent,  only one of them can be specified

Sections