# Getting Started with Your API
Source: https://docs.kibocommerce.com/api-overviews/getting-started
Learn how to authenticate and make your first API calls to the Kibo platform.
# Getting Started With Your API
This page will help you get started with Kibo's APIs.
Implementing Kibo Composable Commerce REST APIs allows merchants to take advantage of efficient ecommerce, order management, and fulfillment strategies to bridge the gap between online and in-store shopping.
# Making API Calls
This section explains how to determine API base URLs, perform authentication, and define headers when you make API calls outside of the interactive documentation.
## Base URLs
Base URLs reference either a production or sandbox environment, and can optionally include a Site ID (`s00000`) in addition to your required Tenant ID (`t00000`). The `tp0` is your tenant's assigned production pod for making calls to production environments.
Example US Sandbox Tenant: `https://t00000.sandbox.mozu.com/api`
Example US Production Tenant: `https://t00000.tp0.mozu.com/api`
Example EU Sandbox Tenant: `https://t00000.sb.euw0.kibocommerce.com/api`
Example EU Production Tenant: `https://t00000.tp0.euw1.kibocommerce.com/api`
Example GCP Sandbox Tenant: `https://t00000.sb.usc1.gcp.kibocommerce.com`
Example GCP Prod Tenant: `https://t00000.tp0.usc1.gcp.kibocommerce.com`
Example GCP EUW4 Sandbox Tenant: `https://t00000.sb.euw4.gcp.kibocommerce.com`
Example GCP EUW4 Prod Tenant: `https://t00000.tp0.euw4.gcp.kibocommerce.com`
## How to Authenticate
Any user that calls into the Kibo APIs must authenticate by including an OAuth 2.0 access token in the request header. To obtain this token, you must provide the prerequisite Application (Client) ID and shared Client Secret.
This ID and secret may be found in the Dev Center under the Application Core details if needed.
```shell theme={null}
curl --request POST \
--url 'https://t00000.sandbox.mozu.com/api/platform/applications/authtickets/oauth' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data ' { "client_id": "string", "client_secret": "string", "grant_type": "client_credentials" } '
```
Response **200**
```json theme={null}
{
"access_token": "{jwt}",
"token_type": "bearer",
"expires_in": 600000,
"refresh_token": "{refreshtoken}"
} `
```
## Additional Headers
The request headers may include additional context which often identifies the site and catalog you are referencing. If you use the hostname format that includes the Site ID, then the master catalog, catalog, site, locale, and currency context are inferred by the site and do not need to be explicitly provided.
The following is an example explicitly defining that context:
```
x-vol-master-catalog: 1
x-vol-catalog: 1
x-vol-site: 11111 `
```
The following table describes all headers supported by Kibo, though most are not required for every API operation.
| Header | Type | Value |
| ----------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| x-vol-catalog | request and response | The identifier of the catalog. Your first catalog is 1, the second catalog is 2, and so on. |
| x-vol-master-catalog | request and response | The identifier of the master catalog. Your first master catalog is 1, the second catalog is 2, and so on. |
| x-vol-site | request and response | The unique identifier of the site. When you log in to Admin, this number appears in the URL for the Site Builder module, preceded by an "s-". |
| x-vol-locale | request and response | The code of the content locale. For example: en-US |
| x-vol-version | request and response | The version of the API to use in the request. If the version is not specified, the request uses the latest available version. |
| x-vol-currency | request and response | The three-letter ISO 4217 standard global currency code. For example: USD |
| x-vol-purchase-location | request | The location code of the store that you want to restrict your call to, such as for querying products only at that particular location. |
| x-vol-pricelist | request | The code of the pricelist that you want to restrict your call to, such as when querying for products. |
| x-vol-correlation | request | An optional GUID used to associate multiple log entries in a cascading chain of API requests. |
| x-vol-dataview-mode | request | The mode in which to view runtime data, which is Live or Pending. |
## Putting it All Together
```shell theme={null}
curl --request GET \
--url 'https://t123.sandbox.mozu.com/api/commerce/catalog/admin/attributedefinition/producttypes?pageSize=10' \
--header 'accept: application/json' \
--header 'authorization: Bearer {jwt}'\
--header 'x-vol-master-catalog: 1'
```
# Further Documentation
To learn how to use Postman, see the [Getting Started with Postman](/pages/getting-started-with-postman) guide.
For information on how to filter and sort API queries, see the [Filtering and Sorting documentation](/pages/sorting-and-filtering-apis).
After you have submitted your request, refer to the [Status Codes documentation](/pages/status-codes) for the HTTP statuses and other API response codes you can expect.
# API Overviews
Explore the available APIs organized by domain.
## Platform & Administration
Tenant configuration and admin user management
Build and manage applications on the Kibo platform
Site and system configuration settings
Custom entity data storage and retrieval
Content management and document storage
Event subscriptions and webhook notifications
## Catalog
Product, category, and attribute management
Storefront product search and display
## Commerce & Customers
Orders, carts, checkout, and payments
Customer accounts, segments, and authentication
Recurring orders and subscription management
Bulk data import and export operations
## Inventory & Fulfillment
Stock levels, allocations, and inventory tracking
Shipment processing and fulfillment workflows
Intelligent order allocation and routing rules
Inventory reservations and holds
## Location & Shipping
Location configuration and management
Store locator and location search
Shipping rates, carriers, and delivery options
# App Development Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_appdevelopement_overview
Manage installed applications, authentication tickets, and application packages for your tenant.
# App Development
The Applications API updates and retrieves details about the applications installed for your tenant. Use
the AuthTickets resource for applications resource to manage authentication tickets for your apps. For information about creating applications, see the [Application Development](/pages/applications-1a6c791-introduction) guides.
Use the \*\*App Auth Tickets resource to manage authentication tickets for your applications.
Use the **Filebased Package** resource to download a file-based representation of the application definition to work on collaboratively with your team using your own source control process.
Use the **Package** resource to manage the application packages and retrieve summaries.
Use the **Public Application** resource to retrieve package metadata or application versions as well as manage package files.
# Catalog Administration Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_catalog_admin_overview
Configure catalogs, products, categories, discounts, price lists, and search settings for your storefront.
# Catalog Administration
The Catalog Administration APIs are a collection of resources for configuring the catalogs and products offered to your shoppers, including
discounts and coupon sets, faceting, price lists, and different types or variations of products. See the
[Catalog user guides](/concept-guides/catalog)
for information about the related features in the Unified Commerce Admin.
Use the **Attributes** resource to manage localization and attribute configurations for your catalogs. This current version of the Attributes API includes localizedContent to
support [multi-locale catalogs](/pages/catalog-structure#multi-locale-catalogs), which was not present in the legacy API model. If
you were a client prior to May 2024 and have upgraded your implementation to support this feature,
you can still access attribute data that has not yet been rewritten to the new model by providing
an x-api-version header set to "1".
Use the **Categories** resource to organize products and control where they appear on the storefront. Create
and maintain a hierarchy of categories and subcategories where the site will store properties. This current version of the Categories API includes localizedContent to
support [multi-locale catalogs](/pages/catalog-structure#multi-locale-catalogs), which was not present in the legacy API model. If
you were a client prior to May 2024 and have upgraded your implementation to support this feature,
you can still access category data that has not yet been rewritten to the new model by providing
an x-api-version header set to "1".
Use the **Coupon Sets** resource to view and create coupon sets. You can use coupon sets to group multiple
coupon codes together and associate them with one or more discounts.
Use the **Currency** resource to manage the currency localization rules and exchange rates for any of the
currencies that are supported for placing orders in.
Use the **Discounts** and **Discount Settings** resources to define and manage discounts to apply to products, product categories, or
orders. This current version of the Discounts API includes localizedContent to
support [multi-locale catalogs](/pages/catalog-structure#multi-locale-catalogs), which was not present in the legacy Products API model. If
you were a client prior to May 2024 and have upgraded your implementation to support this feature,
you can still access discount data that has not yet been rewritten to the new model by providing
an x-api-version header set to "1".
Use the **Facets** resource to manage the facets shoppers use to filter product display results on a
storefront. Facets can include categories, product attributes, or prices, and use either a range of
values or discrete values.
Use the **Master Catalog** resource to view details of the master catalogs associated with a tenant and to
manage the product publishing mode for each master catalog.
Use the **Price Lists** resources to view and create price lists. You can use price lists to override the
catalog pricing of products for specific customer segments and/or sites.
Use the **Products**, **Product Types/Extras/Options/Properties**, and **Product Sort Definitions** resources to create new product definitions in the master catalog and determine which
catalogs will feature products. This current version of the Products API includes localizedContent to
support [multi-locale catalogs](/pages/catalog-structure#multi-locale-catalogs), which was not present in the legacy Products API model. If
you were a client prior to May 2024 and have upgraded your implementation to support this feature,
you can still access product data that has not yet been rewritten to the new model by providing
an x-api-version header set to "1".
Use the **Publishing** resource to publish pending product updates together as part of a set.
Use the **Search** resource to manage all settings and options for providing product search on your site, as
well as search tuning rules.
# Catalog Storefront Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_catalog_storefront_overview
Retrieve product categories, pricing, and search results for the shopper-facing storefront experience.
# Catalog Storefront
The Catalog Storefront APIs are a collection of resources for managing storefront categories, currencies, price lists, products, and
product search. This controls how the products in your catalog are organized and displayed on the
storefront. See the
[Catalog user guides](/concept-guides/catalog)
for information about the related features in the Unified Commerce Admin.
Use the **Currencies** resource to retrieve exchange rates for displaying prices on your storefront.
Use the **Storefront Categories** resource to view the product category hierarchy as it appears to shoppers
who are browsing the storefront. The hierarchy can be returned as a flat list or as a category tree.
Use the **Pricelists** resource to retrieve the details of a price list. The details may contain a hierarchy
of ancestor and/or descendant price lists dependening on your configuration.
Use the **Storefront Products** resource to manage the shopper product selection process during a visit to
the web storefront. You can update product options as shoppers pick and choose their product choices. A
shopper cannot add a product to a cart until all of its required options have been selected.
Use the **Product Search** resource to provide dynamic search results to shoppers as they browse and search
for products on the web storefront, and to suggest possible search terms as the shopper enters text. The related **Search Redirect**
resource allows you to retrieve any search redirect items.
# Commerce Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_commerce_overview
Manage shopping carts, checkouts, orders, returns, wishlists, and B2B quotes for your commerce operations.
# Commerce
The Commerce API interacts with the commerce entities of your tenant, including shoppers's active shopping
carts, checkouts, submitted orders, wishlists, and returns as well as B2B quotes.
Use the **Carts** resource to manage storefront shopping carts as shoppers add and remove items for purchase.
Each time a shopper's cart is modified, the Carts resource updates the estimated total with any
applicable
discounts.
Use the **Channels** and **Channel Groups** resources to manage the channels a company uses to create logical
commercial business divisions based on region or types of sales, such as "US Online," "Amazon," or "EMEA
Retail."
All orders include a channel association that enables the company to perform financial reporting for
each defined channel.
Because channels are managed at the tenant level, you must associate all the tenant's sites with a
channel. Sites that do not
have a defined channel association cannot successfully submit orders.
Use the **Checkouts** resource to track a shopper's order items and their intended destinations on sites that
have the multiple shipment feature enabled.
Use the **Orders** resource to manage all components of order processing, payment, and order-level
fulfillment.
Use the **Quotes** resource to support B2B functionality by managing order quotes, similar to wishlists.
Use the **Returns** resource to manage returned items that were previously fufilled. Returns can include any
number of items associated with an original
order. Each return must either be associated with an original order or a product definition to represent
each returned item.
Use the **Wish Lists** resource to manage the shopper wish lists of products associated with a customer
account. Although customer accounts are managed at the tenant
level, the system stores shopper wish lists at the site level. This enables the same customer to have
wish lists for each of a merchant's sites. The **Wish List Items**
resource allows you to manage the individual items in a wish list.
# Content Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_content_overview
Organize site content into document hierarchies and manage publishing workflows for your storefront.
# Content
The Content APIs allow you to organize your site content into a hierarchy of folders and documents, as
well as control the publishing of your content to the live site with publish sets that group pending
changes together to publish at the same time. For more information about managing site content and the associated UI,
see the [Site Builder](/pages/content-overview) and [Publishing](/pages/publishing-introduction) user guides.
Use the **Document Lists** and **Document List Types** resources to organize your site's documents into a hierarchy. Document lists can
contain documents, folders, and complete hierarchies of folders, which contain documents with unique
names. The type denotes a content type for that list of folders, sub-folders, and documents such as
`web_pages`.
Use the **Document Types** and **Document Property Types** resources to manage the document and property types supported by the Content API.
Use the **Document Publishing** resource to manage and publish document drafts. The
related **Document Publish Set** resource manages publish sets and the pending content drafts.
# Customer Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_customer_overview
Manage customer accounts, contacts, segments, credits, B2B hierarchies, and authentication for shoppers.
# Customer
The Customer API manages a customer's information, including their billing and shipping address
information,
contact information, order history, lifetime value, and more. It allows for customers to be grouped into
sets
to control the specific sites they can access using the same login credentials, as well as supports the
B2B
commerce feature that includes a hierarchy of customer accounts. For more information about customer management and the Unified Commerce Admin UI, see the [general](/pages/customers-overview) and [B2B](/pages/b2b-overview) customers guides.
Use the **B2B** and **Customer Accounts** resources to manage the components of shopper accounts, including
attributes, contact information, company notes, and groups associated with the customer account.
Use the **Address Validation** resource to validate addresses associated with a customer account contact.
\*\*Customer Attributes are custom attributes that you can apply to customer accounts to add further
definition for special uses, such as marketing campaigns, or discounts. Refer to the Customer
Attributes user guide for more information.
Use the **Customer Credits** resource to manage the store credit associated with a customer account. Store
credit can represent a static amount the customer can redeem at any of the tenant's sites, or a gift
card registered for a customer account. At this time, gift card functionality is reserved for future
use.
Use the **Customer Segments** resource to manage groups of customers and target discounts for these segments. After a customer segment is defined, you can
associate any number of customer accounts with it. Meanwhile, the **Customer Sets** resource controls the specific sites your customers can access using the same
login credentials, as well as what My Account storefront customer information is shared between sites.
Use the **Visits** resource to manage all visits a customer makes to a tenant's sites and measure the level
of transactions a customer performs during a unique visit for customer account analytics. Track customer
visits by site (including online and in-person interactions), the transactions a customer performs
during the visit, and the device type associated with the visit, if any.
Use the **Customer In-Stock Notification Subscription** resource to manage the subscriptions customer
accounts use to send product notifications. This resource can send a notification when a product in a
catalog returns to a site's active inventory after it is out of stock, or when a new product becomes
available for the first time. (Not supported for bundled products.)
Use the **Storefront Auth Ticket** resource to generate and refresh authentication tickets for
customer accounts.
# Entities Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_entities_overview
Store and query custom JSON data with indexed properties for large, filterable datasets.
# Entities
Entities are JSON entries within the Kibo database for handling large data sets to heavily filter (>2,000
items). Each entity is associated to an EntityList with schema, rules, and formatting for storing the
content. This content can be accessed via the API and Hypr tags.
The **Entity Lists** resource manages all dynamic entities in your Kibo eCommerce document store of the
cloud. The content is JSON and can have up to five indexed properties (integer, decimal, string, date,
and boolean) with support for additional customized elements as needed. Every document in the entity
list has a validated unique ID. A Content property is not supported for Entity List. Instead, the
MetaData JSON property should be used to supply content when needed. Otherwise, to populate an Entity
List the user should create an entity and then add that resource to the list using the InsertEntity
operation.
The **Entity Containers** resource provides all properties and data for entities within a site/tenant. This
data encapsulates all associated IDs including entity lists, entity views, site, tenant, entities, and
more.
The **List Views** resource provides settings and options for displaying associated content within a context
level of site, tenant, catalog, or master catalog. ListViews can be associated with entity lists and
entities.
# Events Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_event_overview
Subscribe to push notifications for CRUD operations and query event history for your applications.
# Events
The Event APIs are used to subscribe to notifications when create, read, update, or delete operations are
performed. If an application subscribes to the event, use the **Events** resource to query for
recent events published to your application or events that were not published successfully. See the [Event Subscription documentation](/pages/event-subscription) for more information
The **Subscriptions** resource triggers a push service to sent immediate notifications to the subscribed
tenants
and applications. The resource sends messages regarding a subscription event that occurs in the tenant
or site.
# Fulfillment Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_fulfillment_overview
Manage shipments, packages, pick waves, and manifests throughout the order fulfillment workflow.
# Fulfillment
The Fulfillment APIs support order management and fulfillment workflows based on the Shipment API and its
packages, including supporting needs such as pick waves and manifests. Once an order has been placed, it
generally
cannot be edited at the order-level. Instead, changes to the items, pricing, and other information must
be done at the
shipment level with the Shipment API. See the [Fulfillment user guides](/concept-guides/fulfillment) for more information about fulfillment in Kibo.
When using the Shipment API to transition a shipment through each stage of its fulfillment process, it
can be
difficult to remember how to format the next step's endpoint and the expected parameters on-the-fly.
Additionally,
if a call such as cancellation, adding tracking information, or marking the shipment as fulfilled needs
to be performed
outside of the usual fulfillment flow, it may be confusing to determine how to perform the action
without referring to the
documentation. To assist with this, the Shipment API provides guidelines within the response body. This
response
includes two objects, workflowState and \_links, that detail the shipment's next step in the workflow as
well as all
possible actions currently available to the shipment. Use
[this walkthrough](/pages/fulfillment-api-overview) to better
understand how to work with this response data.
Use the **Customer Survey** resource to create surveys and gather data from your customers.
Use the **Manifests** resource to create shipping manifests for fulfillment partners such as Canada Post that require manifests for groups of shipments.
Use the **Pick Wave** resource to generate and process pick waves for picking groups of items at a fulfillment locations.
Use the **Shipment**, **Shipment Attributes**, **Shipment Data**, and **Shipment Notification** resources to manage the actual shipments being fulfilled and perform actions on them.
Use the **Shipment Packages** resource to create, update, and delete the individual packages within a shipment.
Use the **Storefront** resource to retrieve shipment information for the storefront.
Use the **Workflow Process** resource to retrieve BPM configurations and the fulfillment steps based on shipment type.
# Import Export Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_importexport_overview
Bulk import and export Kibo resources using CSV files for efficient data management.
# Import Export
The Import Export APIs are used to "import and export" Kibo's resources efficiently in **CSV** file format.
For Importing, files are first zipped and uploaded via the **Files API**. Then an import job can be created, referencing the uploaded files using the **Import API.**
For Exporting, create an export job via the **Export API**, specifying the resource to be exported. Then after completion, the csv extracts can be downloaded via the **File API**.
For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
## API Endpoints
### Import
| Endpoint | Description |
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
| [Create Import Job](/api-reference/import/create-import-job) | `POST /platform/data/import` — Creates a new import job |
| [Get Import Jobs](/api-reference/import/get-import-jobs) | `GET /platform/data/import` — Retrieves a list of all import jobs |
| [Get Import Job](/api-reference/import/get-import-job) | `GET /platform/data/import/{id}` — Retrieves an import job by ID |
| [Delete Import Job](/api-reference/import/delete-import-job) | `DELETE /platform/data/import/{id}` — Deletes an existing import job |
### Export
| Endpoint | Description |
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
| [Create Export Job](/api-reference/export/create-export-job) | `POST /platform/data/export` — Creates a new export job |
| [Get Export Jobs](/api-reference/export/get-export-jobs) | `GET /platform/data/export` — Retrieves a list of all export jobs |
| [Get Export Job](/api-reference/export/get-export-job) | `GET /platform/data/export/{id}` — Retrieves an export job by ID |
| [Delete Export Job](/api-reference/export/delete-export-job) | `DELETE /platform/data/export/{id}` — Deletes an existing export job |
## See Also
* [Import/Export API Overview](/pages/import-export-api-overview) — Detailed usage guide, file format specifications, and field references
# Inventory Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_inventory_overview
Retrieve and adjust inventory levels, manage allocations, and segment stock with tags across fulfillment locations.
# Inventory
Use the Inventory API to retrieve the inventory levels of requested products, refresh and adjust current
stock levels at fulfillment locations, and tag segmented inventory for different channels. When using tags for inventory segmentation, inventory records are separated into categories to identify
which portions of its
total quantity are intended for different channels, customer groups, fulfillment methods, or other
needs.
This allows for setting a percentage of the quantity that would be available for each category and
setting discrete units at the location level as available for each category. For example, tags could
define how much of each
inventory record is set aside for a certain sales channel: the Kibo storefront, Walmart, or Amazon. The
percentages of the
inventory allotted for each channel would add up to 100% - the Kibo storefront could have 80% of the
inventory, Amazon 10%, and Walmart 10%. For more information, see the [Inventory guides](/developer-guides/inventory).
Use the **Inventory**, **Inventory Allocation**, and **Modify Inventory** resources to retrieve and update inventory levels.
Use the **Inventory Job** resource to retrieve information about your pending inventory update processing jobs.
Use the **Inventory Tag** and **Tag Category** resources to segment your inventory records.
# Location Administration Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_location_admin_overview
Create and manage fulfillment locations, location groups, and location types for inventory and pickup.
# Location Administration
The Location and Location Groups APIs enable tenants to associate a physical address with product inventory,
provide a store finder for in-store pickup, or both and manage these locations at individual and group levels. See the
[Location user guides](/pages/locations-overview)
for information about the related feature in the Unified Commerce Admin.
The **Location Admin**
resource
allows information about the individual locations to be accessed and edited, including creating new
locations.
Use the **Location Group** and **Location Group Configuration** resources to manage groups, or sets of similar fulfillment locations that are bundled together
to improve efficiency of managing configurations based on catalogs, custom fulfillment flows,
available carrier options, and so forth.
Use the **Location Types** resource to manage the types of locations your tenant maintains, such as
warehouses,
physical storefronts, and kiosks.
Use the **Location Settings** resource to to define the available usages; or the locations and
location types that interact
with a specified site.
# Location Storefront Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_location_storefront_overview
Retrieve fulfillment location details for the shopper-facing storefront experience.
# Location Storefront
The Location API for the storefront simply allows information about the individual fulfillment locations to be queried at the
storefront. These are not administrative calls for managing location records and groups - they are a set of GET
requests for retrieving location data.
To create and update (or perform other management actions) location records, see the Location Administration API service instead.
# Order Routing Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_orderrouting_overview
Configure routing filters, location groups, and rules to determine optimal fulfillers for orders.
# Order Routing
Although the Order Routing
interface is the best place to configure order routing rules, some
aspects of routing can be managed through REST API calls when convenient.
# New UI APIs
Do not mix New UI APIs with Old UI APIs, it might break the functionality.
Use the **Strategy** resource to manage routing strategies.
Use the **Scenario** resource to manage routing scenarios within strategies.
Use the **Filter Data** resource to filter data for routing scenarios.
Use the **Custom Data List** resource to manage custom data lists for filtering.
Use the **EDD** resource for estimated delivery date routing configuration.
Use the **Strategy Export** resource to export and import strategies.
# Reservations Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_reservation_overview
Create and manage inventory reservations for items, quantities, and fulfillment methods.
# Reservations
The Reservation APIs are used to create and manage inventory reservations. This includes updating items and quantities, fulfillment methods, zip codes and pickup locations, and resetting
the expiration timer for a reservation. For more information, see the [Reservations feature guide](/pages/reserve-inventory-in-cart).
# Site Settings Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_settings_overview
Configure site, checkout, payment, and application settings for your tenant and storefronts.
# Site Settings
The Site Settings APIs are a collection of resources used to manage settings for sites, checkout, installed applications, locations,
shipping, and general settings for a site. For more information about site settings and the associated configurations in the Unified Commerce Admin
interface, see the [Settings user guides](/pages/general-settings).
Use the **Cart** resource to manage settings for the cart, such as whether to include handling fees in the
cost calculations.
Use the **Checkout Settings** resource to specify the site-wide settings that define checkout and order
processing behavior. This resource includes subresources for payment settings, customer checkout
settings, and order processing settings.
Use the **Fulfillment Settings** resource to define site-wide fulfillment options such as the default
backorder duration, rejection actions, and BPM configurations.
Use the **General Settings** resource to define global site settings such as the site name, shipping and
email addresses, and logo images. You can block undesirable IP addresses using this resource as well as
configure custom
routes.
Use the **Inventory Settings** resource to enable or disable inventory jobs and set a preferred time of day
for the jobs to run at.
Use the **Return Settings** resource to specify the default return options for processing fees, shipping
locations, and label generation.
Use the **Shipping** resource to manage settings for the site shipping information, such as origin address
information, carrier shipping methods, shipping rate providers, and regions available for shipping.
# Subscriptions Overview
Source: https://docs.kibocommerce.com/api-overviews/openapi_subscription_overview
Manage recurring order subscriptions, including items, frequencies, and subscription lifecycle.
# Subscriptions
The Subscription APIs are used to create and manage subscriptions in either an eCommerce+OMS implementation or a standalone
Subscriptions solution. This includes updating items and quantities, subscription frequency, coupons, and performing actions
on a subscription in addition to turning a subscription into an order. For more information, see the [Subscriptions feature guide](/concept-guides/subscriptions).
# SDKs and Toolkits
Source: https://docs.kibocommerce.com/api-overviews/sdks-and-toolkits
Available SDKs, Postman collections, and developer tools for integrating with Kibo APIs.
# SDKs and Tool Kits
## SDKS
[](#sdks)
TypeScript SDK
* [Documentation](/pages/typescript-sdk)
* [GitHub](https://github.com/KiboSoftware/typescript-rest-sdk)
* [NPM](https://socket.dev/npm/package/@kibocommerce/rest-sdk)
Java SDK
* [GitHub](https://github.com/KiboSoftware/java-rest-sdk)
Legacy Node
* [NPM](https://www.npmjs.com/package/mozu-node-sdk)
Legacy DotNet
* [Nuget](https://www.nuget.org/packages/Mozu.Api.SDK)
##
CLIs and ToolKits
[](#clis-and-toolkits)
Kibo NextJs Starter Kit
* [GitHub](https://github.com/KiboSoftware/nextjs-storefront)
* [Demo](https://kibo-commerce-nextjs-storefront.vercel.app/)
* [Builder Demo](https://github.com/KiboSoftware/nextjs-builderio-starter-storefront)
* [Amplience Demo](https://github.com/KiboSoftware/nextjs-amplience-starter-storefront)
* [ContentStack Demo](https://github.com/KiboSoftware/nextjs-contentstack-starter-storefront)
* [Amplify Demo](https://github.com/KiboSoftware/nextjs-storefront-amplify)
* [Prismic Demo](https://github.com/KiboSoftware/nextjs-prismic-starter-storefront)
* [Contentful Demo](https://github.com/KiboSoftware/nextjs-contentful-starter-storefront)
Kibo API Extension Generator CLI
* [GitHub](https://github.com/Mozu/generator-mozu-actions)
* [NPM](https://www.npmjs.com/package/generator-mozu-actions)
Kibo Sandbox Data CLI
* [NPM](https://www.npmjs.com/package/@kibocommerce/kibo-sandbox-data-cli)
* [GITHUB](https://github.com/KiboSoftware/kibo-sandbox-data-cli)
# Create Customer Rule
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/create-customer-rule
/openapi/openapi_customer.json post /commerce/rules/customer
Create Customer Rule
# Delete Customer Rule (with cross-service validation)
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/delete-customer-rule-with-cross-service-validation
/openapi/openapi_customer.json delete /commerce/rules/customer/{code}
Delete Customer Rule (with cross-service validation)
# Evaluate Customer Rules
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/evaluate-customer-rules
/openapi/openapi_customer.json post /commerce/rules/customer/evaluate/{customerAccountId}
Evaluate Customer Rules
# Get All Customer Rules
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/get-all-customer-rules
/openapi/openapi_customer.json get /commerce/rules/customer
Get All Customer Rules
# Get Customer Rule by Code
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/get-customer-rule-by-code
/openapi/openapi_customer.json get /commerce/rules/customer/{code}
Get Customer Rule by Code
# Get Customer Rule Usages by Code
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/get-customer-rule-usages-by-code
/openapi/openapi_customer.json get /commerce/rules/customer/{code}/usages
Get Customer Rule Usages by Code
# Update Customer Rule
Source: https://docs.kibocommerce.com/api-reference/accountrankingrule/update-customer-rule
/openapi/openapi_customer.json put /commerce/rules/customer/{code}
Update Customer Rule
# Validate Address
Source: https://docs.kibocommerce.com/api-reference/addressvalidation/validate-address
/openapi/openapi_customer.json post /commerce/customer/addressvalidation
Allows merchants and services to validate an address against the configured AddressValidator capability in SiteSettings, fallback uses USPS Address Validation.
# Create User Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/adminauthticket/create-user-auth-ticket
/openapi/openapi_user.json post /platform/adminuser/authtickets/tenants
Authenticates a user for a particular tenant given a set of user credentials and a tenantId.
# Create User Auth Ticket With Ws Fed
Source: https://docs.kibocommerce.com/api-reference/adminauthticket/create-user-auth-ticket-with-ws-fed
/openapi/openapi_user.json post /platform/adminuser/authtickets/wsfed/auth/{id}
Create User Auth Ticket With Ws Fed
# Delete User Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/adminauthticket/delete-user-auth-ticket
/openapi/openapi_user.json delete /platform/adminuser/authtickets
Logs out a user by deleting the refresh token
# Get Ws Fed Challenge Url
Source: https://docs.kibocommerce.com/api-reference/adminauthticket/get-ws-fed-challenge-url
/openapi/openapi_user.json get /platform/adminuser/authtickets/wsfed/challenge/{id}
Get Ws Fed Challenge Url
# Get Ws Fed Sign Out Url
Source: https://docs.kibocommerce.com/api-reference/adminauthticket/get-ws-fed-sign-out-url
/openapi/openapi_user.json get /platform/adminuser/authtickets/wsfed/SignOut/{id}
Get Ws Fed Sign Out Url
# Refresh Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/adminauthticket/refresh-auth-ticket
/openapi/openapi_user.json put /platform/adminuser/authtickets/tenants
Reauthenticates the current user for a different tenant. If the user does not have access to the tenant, the operation fails.
# Add Admin Group
Source: https://docs.kibocommerce.com/api-reference/admingroup/add-admin-group
/openapi/openapi_user.json post /platform/adminuser/groups
Adds an admin group
# Add Users to Admin Group
Source: https://docs.kibocommerce.com/api-reference/admingroup/add-users-to-admin-group
/openapi/openapi_user.json post /platform/adminuser/groups/{groupCode}/addusers
Add users to admin group
# Delete Admin Group
Source: https://docs.kibocommerce.com/api-reference/admingroup/delete-admin-group
/openapi/openapi_user.json delete /platform/adminuser/groups/{groupCode}
Deletes an Admin Group
# Get Admin Group
Source: https://docs.kibocommerce.com/api-reference/admingroup/get-admin-group
/openapi/openapi_user.json get /platform/adminuser/groups/{groupCode}
Gets an Admin group by id
# Get Admin Groups
Source: https://docs.kibocommerce.com/api-reference/admingroup/get-admin-groups
/openapi/openapi_user.json get /platform/adminuser/groups
Gets a collection of user groups
# Remove Users from Admin Group
Source: https://docs.kibocommerce.com/api-reference/admingroup/remove-users-from-admin-group
/openapi/openapi_user.json post /platform/adminuser/groups/{groupCode}/removeusers
Remove users from admin group
# Update Admin Group
Source: https://docs.kibocommerce.com/api-reference/admingroup/update-admin-group
/openapi/openapi_user.json put /platform/adminuser/groups/{groupCode}
Update an existing adminGroup
# Add User Role
Source: https://docs.kibocommerce.com/api-reference/adminuser/add-user-role
/openapi/openapi_user.json post /platform/adminuser/accounts/{userId}/roles/{roleId}
Adds a role to the specified user's Admin account.
# Change Password
Source: https://docs.kibocommerce.com/api-reference/adminuser/change-password
/openapi/openapi_user.json post /platform/adminuser/accounts/{userId}/Change-Password
Change a password
# Change User Password
Source: https://docs.kibocommerce.com/api-reference/adminuser/change-user-password
/openapi/openapi_user.json post /platform/adminuser/accounts/{userId}/Change-User-Password
Changes a user's password to the provided new password
# Create User
Source: https://docs.kibocommerce.com/api-reference/adminuser/create-user
/openapi/openapi_user.json post /platform/adminuser/accounts
Creates a new user
# Delete User
Source: https://docs.kibocommerce.com/api-reference/adminuser/delete-user
/openapi/openapi_user.json delete /platform/adminuser/accounts/{userId}
Removes a user account from the site.
# Get Tenant Scope
Source: https://docs.kibocommerce.com/api-reference/adminuser/get-tenant-scope
/openapi/openapi_user.json get /platform/adminuser/accounts/{userId}/tenants
Get tenant scope for users
# Get User
Source: https://docs.kibocommerce.com/api-reference/adminuser/get-user
/openapi/openapi_user.json get /platform/adminuser/accounts/{userId}
Retrieves the details of a user specified by user ID.
# Get User By Id
Source: https://docs.kibocommerce.com/api-reference/adminuser/get-user-by-id
/openapi/openapi_user.json get /platform/adminuser/accounts/{userId}/userbyid
Retrieves the details of a user specified by user ID.
# Get User Roles
Source: https://docs.kibocommerce.com/api-reference/adminuser/get-user-roles
/openapi/openapi_user.json get /platform/adminuser/accounts/{userId}/roles
Retrieves all the roles for a specified user on the specified tenant.
# Get Users
Source: https://docs.kibocommerce.com/api-reference/adminuser/get-users
/openapi/openapi_user.json get /platform/adminuser/accounts
Retrieves a list of Admin users for a specified site according to any specified filter criteria and sort options.
# Remove User Role
Source: https://docs.kibocommerce.com/api-reference/adminuser/remove-user-role
/openapi/openapi_user.json delete /platform/adminuser/accounts/{userId}/roles/{roleId}
Removes a role from the specified Admin account.
# Reset Password
Source: https://docs.kibocommerce.com/api-reference/adminuser/reset-password
/openapi/openapi_user.json post /platform/adminuser/accounts/Reset-Password
Resets the password for a user specified by email address.
# Unlock User
Source: https://docs.kibocommerce.com/api-reference/adminuser/unlock-user
/openapi/openapi_user.json post /platform/adminuser/accounts/{userId}/unlock
Unlocks (or "enables") a user
# Update User
Source: https://docs.kibocommerce.com/api-reference/adminuser/update-user
/openapi/openapi_user.json put /platform/adminuser/accounts/{userId}
Modifies user information for a specified user.
# App Authenticate
Source: https://docs.kibocommerce.com/api-reference/appauthtickets/app-authenticate
/openapi/openapi_appdevelopement.json post /platform/applications/authtickets
Authenticates an application using shared secret and application id. The method returns a set of authentication tokens used to manage application authentication.
# Delete App Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/appauthtickets/delete-app-auth-ticket
/openapi/openapi_appdevelopement.json delete /platform/applications/authtickets/{refreshToken}
This method is used to expire an application's current refresh token which \r\nwill force the application to reauthenticate once the current access token expires.
# Oauth Authenticate App
Source: https://docs.kibocommerce.com/api-reference/appauthtickets/oauth-authenticate-app
/openapi/openapi_appdevelopement.json post /platform/applications/authtickets/oauth
Authenticate an application using OAuth.
# Refresh App Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/appauthtickets/refresh-app-auth-ticket
/openapi/openapi_appdevelopement.json put /platform/applications/authtickets/refresh-ticket
Returns the AppAuthTicket with a refreshed AccessToken
# Create Application Subscription
Source: https://docs.kibocommerce.com/api-reference/appevent/create-application-subscription
/openapi/openapi_appdevelopement.json post /platform/appdev/appsubscriptions/events
Create a new application event subscription.
# Delete Application Subscription
Source: https://docs.kibocommerce.com/api-reference/appevent/delete-application-subscription
/openapi/openapi_appdevelopement.json delete /platform/appdev/appsubscriptions/events/{applicationSubscriptionId}
Delete an application event subscription.
# Get Application Subscription
Source: https://docs.kibocommerce.com/api-reference/appevent/get-application-subscription
/openapi/openapi_appdevelopement.json get /platform/appdev/appsubscriptions/{subscriptionId}
Get a specific application subscription by ID.
# Update Application Subscription
Source: https://docs.kibocommerce.com/api-reference/appevent/update-application-subscription
/openapi/openapi_appdevelopement.json put /platform/appdev/appsubscriptions/events
Update an existing application event subscription.
# Get Application
Source: https://docs.kibocommerce.com/api-reference/appinstall/get-application
/openapi/openapi_appdevelopement.json get /platform/appdev/appinstall/application/entitlement/{applicationEntitlementId}
Get a specific application entitlement by ID.
# Get Applications
Source: https://docs.kibocommerce.com/api-reference/appinstall/get-applications
/openapi/openapi_appdevelopement.json get /platform/appdev/appinstall/application/entitlement
Get a list of installed applications.
# Get Entitlements By Application
Source: https://docs.kibocommerce.com/api-reference/appinstall/get-entitlements-by-application
/openapi/openapi_appdevelopement.json get /platform/appdev/appinstall/applicationversion/{applicationId}/entitlements
Retrieve a list of entitlements for a specific application.
# Get Entitlements By Tenant
Source: https://docs.kibocommerce.com/api-reference/appinstall/get-entitlements-by-tenant
/openapi/openapi_appdevelopement.json get /platform/appdev/appinstall/tenant/{tenantId}/entitlements
Get a list of applicaiton entitlements by tenant.
# Install App To Production Tenant
Source: https://docs.kibocommerce.com/api-reference/appinstall/install-app-to-production-tenant
/openapi/openapi_appdevelopement.json post /platform/appdev/appinstall/toproductiontenant
Install an application to a production tenant.
# Install Application
Source: https://docs.kibocommerce.com/api-reference/appinstall/install-application
/openapi/openapi_appdevelopement.json post /platform/appdev/appinstall/application/entitlement
Install an application entitlement.
# Add Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/add-account
/openapi/openapi_customer.json post /commerce/customer/b2baccounts
Creates a new B2B account in the Pending Approval state. This account will not yet be active, as it requires a sales representative to be assigned (with .../b2baccounts/{accountId}/salesrep/{userId}) before it is approved (with .../b2baccounts/{accountId}/status/{actionName}).
# Add B2B Account tAttribute
Source: https://docs.kibocommerce.com/api-reference/b2baccount/add-b2b-account-tattribute
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/{accountId}/attributes
Add a customer attribute to the B2B account.
# Add Sales Rep To B2B Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/add-sales-rep-to-b2b-account
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/{accountId}/salesrep/{userId}
Adds a sales rep to a B2B account.
# Add Sales Reps To B2B Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/add-sales-reps-to-b2b-account
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/{accountId}/addsalesreps
Adds lists of sales reps to a B2B account.
# Add User
Source: https://docs.kibocommerce.com/api-reference/b2baccount/add-user
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/{accountId}/user
Adds user to B2B account.
# Add User Role Async
Source: https://docs.kibocommerce.com/api-reference/b2baccount/add-user-role-async
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/{accountId}/user/{userId}/roles/{roleId}
Add a role to B2B user. These roles include Admin, Purchaser, and Non-Purchaser.
# Assign a role to a specific account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/assign-a-role-to-a-specific-account
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/roles/{roleId}/accounts/{accountId}
Assign a role to a specific account.
# Change Parent Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/change-parent-account
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/{accountId}/changeparent/{parentAccountId}
Change the B2B parent account for an existing B2B account that belongs to an account hierarchy.
# Create a new role and associate it with specified accounts.
Source: https://docs.kibocommerce.com/api-reference/b2baccount/create-a-new-role-and-associate-it-with-specified-accounts
/openapi/openapi_customer.json post /commerce/customer/b2baccounts/roles
Required fields:
- Name: Role name (must be unique within tenant)
- Behaviors: List of behavior IDs (at least one required)
- AccountIds: List of account IDs to associate with role (at least one required)
# Delete Account Priorities
Source: https://docs.kibocommerce.com/api-reference/b2baccount/delete-account-priorities
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/priority/delete
Deletes the priorities of specified B2B accounts
# Delete B2B Account Attribute
Source: https://docs.kibocommerce.com/api-reference/b2baccount/delete-b2b-account-attribute
/openapi/openapi_customer.json delete /commerce/customer/b2baccounts/{accountId}/attributes/{attributeFQN}
Deletes a specific customer attribute specified by attributeFQN.
# Delete role and all its account associations.
Source: https://docs.kibocommerce.com/api-reference/b2baccount/delete-role-and-all-its-account-associations
/openapi/openapi_customer.json delete /commerce/customer/b2baccounts/roles/{roleId}
This operation will fail if any users are currently assigned to this role
in any of the associated accounts.
# Enable or disable role inheritance for future child accounts.
Source: https://docs.kibocommerce.com/api-reference/b2baccount/enable-or-disable-role-inheritance-for-future-child-accounts
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/roles/{roleId}/accounts/{accountId}/apply-to-future-children/{enabled}
This setting only affects future account creation and does not modify existing child accounts.
The inheritance applies to all levels of the hierarchy (children, grandchildren, etc.).
When enabled, the system will automatically assign this role to all future child accounts
and grandchildren created under the specified account in the hierarchy.
# Get Account Priorities
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-account-priorities
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/priority/read
Retrieves the priorities of B2B accounts
# Get Accounts by User
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-accounts-by-user
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/accountsbyuser
Retrieves account IDs of all active accounts that a user belongs to by username or email. If emailAddress and userName are both provided, the email address will be used. When getAllAccounts is set to true, all accounts will be returned regardless of the AccountStatus.
# Get Accounts For Sales Rep
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-accounts-for-sales-rep
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/salesrep/{userId}
Gets list of accounts for the B2B sales rep account.
# Get all roles available to the specified account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-all-roles-available-to-the-specified-account
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/roles
Get all roles available to the specified account.
# Get B2B Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-b2b-account
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}
Retrieves the details of a B2B account specified by its unique identifier.
# Get B2B Account Attribute
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-b2b-account-attribute
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/attributes/{attributeFQN}
Retrieves the contents of a particular attribute attached to a specified account.
# Get B2B Account Attributes
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-b2b-account-attributes
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/attributes
Retrieves a list of notes added to an account according to any specified filter criteria and sort options.
# Get B2B Account Hierarchy
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-b2b-account-hierarchy
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/hierarchy
Retrieves the account hierarchy for a B2B account specified by its unique identifier.
# Get B2B Accounts
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-b2b-accounts
/openapi/openapi_customer.json get /commerce/customer/b2baccounts
Retrieves a list of B2B accounts according to any filter criteria and sort options.
# Get Behaviors for b2b shopper
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-behaviors-for-b2b-shopper
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/behaviors
Get Behaviors for b2b shopper
# Get role details by role ID, including associated account IDs
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-role-details-by-role-id-including-associated-account-ids
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/roles/{roleId}
Get role details by role ID, including associated account IDs.
# Get User Behaviors
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-user-behaviors
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/user/{userId}/behaviors
Gets shopper behaviors of the B2B user.
# Get User Roles Async
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-user-roles-async
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/user/{userId}/roles
Retrieves all the roles for a specified user of a b2b account. These roles may include Admin, Purchaser, and Non-Purchaser.
# Get Users Async
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-users-async
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/users
Retrieves a list of user for a B2B account according to any filter criteria and sort options.
# Get Users By Role
Source: https://docs.kibocommerce.com/api-reference/b2baccount/get-users-by-role
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/{accountId}/roles/{roleId}/users
Retrieves a list of users who have a specific role in a B2B account.
# Gets all the behavior categories for the b2b shopper
Source: https://docs.kibocommerce.com/api-reference/b2baccount/gets-all-the-behavior-categories-for-the-b2b-shopper
/openapi/openapi_customer.json get /commerce/customer/b2baccounts/behaviors/categories
Gets all the behavior categories for the b2b shopper
# Remove a role from a specific account.
Source: https://docs.kibocommerce.com/api-reference/b2baccount/remove-a-role-from-a-specific-account
/openapi/openapi_customer.json delete /commerce/customer/b2baccounts/roles/{roleId}/accounts/{accountId}
This operation will fail if any users in the account are currently
assigned to this role.
# Remove Sales Rep From B2B Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/remove-sales-rep-from-b2b-account
/openapi/openapi_customer.json delete /commerce/customer/b2baccounts/{accountId}/salesrep/{userId}
Removes a specific sales rep from B2B account .
# Remove User
Source: https://docs.kibocommerce.com/api-reference/b2baccount/remove-user
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/{accountId}/user/{userId}/remove
Removes a B2B user from an account.
# Remove User Role Async
Source: https://docs.kibocommerce.com/api-reference/b2baccount/remove-user-role-async
/openapi/openapi_customer.json delete /commerce/customer/b2baccounts/{accountId}/user/{userId}/roles/{roleId}
Removes a role from the specified user.
# Update Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-account
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/{accountId}
Modifies an existing B2B account. If you want to update the users on an account, call the user-specific endpoints (such as Add User and Remove User) instead.
# Update Account Priorities
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-account-priorities
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/priority/update
Updates the priorities of B2B accounts. The Priority for blacklisted accounts will be set as -1.
# Update B2B Account Attribute
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-b2b-account-attribute
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/{accountId}/attributes/{attributeFQN}
Modifies an existing attribute for a b2b account.
# Update B2B Account Status
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-b2b-account-status
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/{accountId}/status/{actionName}
Updates the status on B2B account by transitioning it between states with the approve, deny, enable, and disable actions. An account that has been newly requested will be in the Pending Approval state and can be approved or denied. An account that has been previously approved can be disabled to deactivate it, while a disabled or denied account can be reinstated by enabling or approving it.
# Update existing role and its account associations.
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-existing-role-and-its-account-associations
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/roles/{roleId}
Required fields:
- Name: Role name (must be unique within tenant)
- Behaviors: List of behavior IDs (at least one required)
- AccountIds: List of account IDs to associate with role (at least one required)
Note: This performs a complete replacement of account associations.
# Update Sales Reps On B2B Account
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-sales-reps-on-b2b-account
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/{accountId}/salesrep
Updates list of sales reps on a B2B account.
# Update User
Source: https://docs.kibocommerce.com/api-reference/b2baccount/update-user
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/{accountId}/user/{userId}
Updates a B2B user specified by user Id.
# Upgrade B2C Accounts To B2B
Source: https://docs.kibocommerce.com/api-reference/b2baccount/upgrade-b2c-accounts-to-b2b
/openapi/openapi_customer.json put /commerce/customer/b2baccounts/upgradeaccounts
Upgrades bulk B2C accounts to B2B
# Get B2B Contacts
Source: https://docs.kibocommerce.com/api-reference/b2bcontact/get-b2b-contacts
/openapi/openapi_customer.json get /commerce/customer/b2bcontacts
Retrieves a list of B2B contacts according to any specified filter criteria and sort options.
# Create B2BSettings
Source: https://docs.kibocommerce.com/api-reference/b2bsettings/create-b2bsettings
/openapi/openapi_settings.json post /commerce/settings/b2b/b2bsettings
Create B2BSettings
# Get B2BSettings
Source: https://docs.kibocommerce.com/api-reference/b2bsettings/get-b2bsettings
/openapi/openapi_settings.json get /commerce/settings/b2b/b2bsettings
Get B2BSettings
# Update B2BSettings
Source: https://docs.kibocommerce.com/api-reference/b2bsettings/update-b2bsettings
/openapi/openapi_settings.json put /commerce/settings/b2b/b2bsettings
Update B2BSettings
# Create back order rebalancing rule
Source: https://docs.kibocommerce.com/api-reference/backorderrebalancingrules/create-back-order-rebalancing-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/backorderrebalancing
Creates a new back order rebalancing rule.
# Delete back order rebalancing rule
Source: https://docs.kibocommerce.com/api-reference/backorderrebalancingrules/delete-back-order-rebalancing-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/backorderrebalancing/{code}
Deletes a back order rebalancing rule by code.
# Get back order rebalancing rule by code
Source: https://docs.kibocommerce.com/api-reference/backorderrebalancingrules/get-back-order-rebalancing-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/backorderrebalancing/{code}
Gets a back order rebalancing rule details by code.
# Get back order rebalancing rules
Source: https://docs.kibocommerce.com/api-reference/backorderrebalancingrules/get-back-order-rebalancing-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/backorderrebalancing
Gets a collection of back order rebalancing rules according to any specified filter criteria and sort options.
# Update back order rebalancing rule
Source: https://docs.kibocommerce.com/api-reference/backorderrebalancingrules/update-back-order-rebalancing-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/backorderrebalancing/{code}
Updates an existing back order rebalancing rule.
# Update back order rebalancing rule rank
Source: https://docs.kibocommerce.com/api-reference/backorderrebalancingrules/update-back-order-rebalancing-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/backorderrebalancing/{code}/rank
Updates the rank for a back order rebalancing rule and rearranges the ranks of all other rules accordingly.
# Create Batch Job
Source: https://docs.kibocommerce.com/api-reference/batchjob/create-batch-job
/openapi/openapi_importexport.json post /platform/data/batchJob
Creates a new batch job
# Delete Batch Job
Source: https://docs.kibocommerce.com/api-reference/batchjob/delete-batch-job
/openapi/openapi_importexport.json delete /platform/data/batchJob/{code}
Deletes an existing batch job
# Get Available Actions
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-available-actions
/openapi/openapi_importexport.json get /platform/data/batchJob/actions/{code}
Retrieves all available actions for the specified batch job
# Get Batch Job
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-batch-job
/openapi/openapi_importexport.json get /platform/data/batchJob/{code}
Retrieves information about a specific batch job
# Get Batch Job Item
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-batch-job-item
/openapi/openapi_importexport.json post /platform/data/batchJob/actions/{code}/items/{correlationId}
Retrieves a specific item in a batch job
# Get Batch Job Items
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-batch-job-items
/openapi/openapi_importexport.json post /platform/data/batchJob/actions/{code}/items
Retrieve a list of all batch job items. Query for items of a specific processing status and/or resource by appending ?processingStatus={processingStatus}&resourceType={resourceType}. Resource type can be Products, ProductProperty, or Pricelistentries.
# Get Batch Job Summaries
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-batch-job-summaries
/openapi/openapi_importexport.json get /platform/data/batchJob/actions/summaries
Retrieves a list of all batch job summaries
# Get Batch Job Summary
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-batch-job-summary
/openapi/openapi_importexport.json get /platform/data/batchJob/actions/{code}/summary
Retrieves a batch job summary by its code
# Get Batch Jobs
Source: https://docs.kibocommerce.com/api-reference/batchjob/get-batch-jobs
/openapi/openapi_importexport.json get /platform/data/batchJob
Gets all batch jobs
# Perform Batch Action
Source: https://docs.kibocommerce.com/api-reference/batchjob/perform-batch-action
/openapi/openapi_importexport.json post /platform/data/batchJob/actions/{code}
Performs an action on the specified batch job. Possible actions are start, cancel, and reset actions. Reset can only be called for jobs that are already completed or canceled, and will remove all items so that you can re-use the empty job.
# Update Batch Job
Source: https://docs.kibocommerce.com/api-reference/batchjob/update-batch-job
/openapi/openapi_importexport.json put /platform/data/batchJob/{code}
Updates an existing batch job. Currently only allows you to change the name of a job.
# Add an item to a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/add-an-item-to-a-blanket-order
/openapi/openapi_commerce.json post /commerce/blanketorders/{blanketOrderId}/items
Add an item to a Blanket Order.
# Aggregate remaining quantity across blanket orders scoped to the current tenant and site.
Source: https://docs.kibocommerce.com/api-reference/blanketorder/aggregate-remaining-quantity-across-blanket-orders-scoped-to-the-current-tenant-and-site
/openapi/openapi_commerce.json get /commerce/blanketorders/aggregate
Sums `items[].remainingQuantity` and returns breakdowns by product code, customer, and status.
Use the `filter` parameter to scope the aggregation (e.g. `items.product.productCode in [SKU1,SKU2]`,
`customerAccountId eq 1234`, `items.status ne Cancelled`).
# Bulk cancel Blanket Orders
Source: https://docs.kibocommerce.com/api-reference/blanketorder/bulk-cancel-blanket-orders
/openapi/openapi_commerce.json post /commerce/blanketorders/actions/bulk-cancel
Bulk cancel Blanket Orders.
# Cancel a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/cancel-a-blanket-order
/openapi/openapi_commerce.json post /commerce/blanketorders/{blanketOrderId}/cancel
Cancel a Blanket Order.
# Cancel an item on a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/cancel-an-item-on-a-blanket-order
/openapi/openapi_commerce.json post /commerce/blanketorders/{blanketOrderId}/items/{itemId}/cancel
Cancel an item on a Blanket Order.
# Create a new Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/create-a-new-blanket-order
/openapi/openapi_commerce.json post /commerce/blanketorders
Create a new Blanket Order.
# Create header-level attributes on a blanket order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/create-header-level-attributes-on-a-blanket-order
/openapi/openapi_commerce.json post /commerce/blanketorders/{blanketOrderId}/attributes
Create header-level attributes on a blanket order.
# Create line-level attributes on a blanket order item; skips FQNs that already exist
Source: https://docs.kibocommerce.com/api-reference/blanketorder/create-line-level-attributes-on-a-blanket-order-item;-skips-fqns-that-already-exist
/openapi/openapi_commerce.json post /commerce/blanketorders/{blanketOrderId}/items/{itemId}/attributes
Create line-level attributes on a blanket order item; skips FQNs that already exist.
# Delete a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/delete-a-blanket-order
/openapi/openapi_commerce.json delete /commerce/blanketorders/{blanketOrderId}
Delete a Blanket Order.
# Delete a single header-level attribute from a blanket order by FQN
Source: https://docs.kibocommerce.com/api-reference/blanketorder/delete-a-single-header-level-attribute-from-a-blanket-order-by-fqn
/openapi/openapi_commerce.json delete /commerce/blanketorders/{blanketOrderId}/attributes/{attributeFqn}
Delete a single header-level attribute from a blanket order by FQN.
# Delete a single line-level attribute from a blanket order item by FQN
Source: https://docs.kibocommerce.com/api-reference/blanketorder/delete-a-single-line-level-attribute-from-a-blanket-order-item-by-fqn
/openapi/openapi_commerce.json delete /commerce/blanketorders/{blanketOrderId}/items/{itemId}/attributes/{attributeFqn}
Delete a single line-level attribute from a blanket order item by FQN.
# Delete an item from a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/delete-an-item-from-a-blanket-order
/openapi/openapi_commerce.json delete /commerce/blanketorders/{blanketOrderId}/items/{itemId}
Delete an item from a Blanket Order.
# Deletes a change message for a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/deletes-a-change-message-for-a-blanket-order
/openapi/openapi_commerce.json delete /commerce/blanketorders/{blanketOrderId}/changemessages/{changeMessageId}
Deletes a change message for a Blanket Order.
# Get a Blanket Order by ID
Source: https://docs.kibocommerce.com/api-reference/blanketorder/get-a-blanket-order-by-id
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}
Get a Blanket Order by ID.
# Get a paged collection of Blanket Orders
Source: https://docs.kibocommerce.com/api-reference/blanketorder/get-a-paged-collection-of-blanket-orders
/openapi/openapi_commerce.json get /commerce/blanketorders
Get a paged collection of Blanket Orders.
# Get a single consumption record for a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/get-a-single-consumption-record-for-a-blanket-order
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}/consumptionrecords/{consumptionRecordId}
Get a single consumption record for a Blanket Order.
# Get all header-level attributes for a blanket order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/get-all-header-level-attributes-for-a-blanket-order
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}/attributes
Get all header-level attributes for a blanket order.
# Get all line-level attributes for a blanket order item
Source: https://docs.kibocommerce.com/api-reference/blanketorder/get-all-line-level-attributes-for-a-blanket-order-item
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}/items/{itemId}/attributes
Get all line-level attributes for a blanket order item.
# Get consumption records for a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/get-consumption-records-for-a-blanket-order
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}/consumptionrecords
Get consumption records for a Blanket Order.
# Gets a single change message for a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/gets-a-single-change-message-for-a-blanket-order
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}/changemessages/{changeMessageId}
Gets a single change message for a Blanket Order.
# Gets change messages for a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/gets-change-messages-for-a-blanket-order
/openapi/openapi_commerce.json get /commerce/blanketorders/{blanketOrderId}/changemessages
Gets change messages for a Blanket Order.
# Roll over an expired Blanket Order to create a new order with selected items.
Source: https://docs.kibocommerce.com/api-reference/blanketorder/roll-over-an-expired-blanket-order-to-create-a-new-order-with-selected-items
/openapi/openapi_commerce.json post /commerce/blanketorders/{sourceBlanketOrderId}/rollover
ICKY-2647: Blanket Order Rollover
Source order must be in Expired status. Only Open items can be selected.
Creates a new Blanket Order in Open status with copied data:
- Customer Account ID
- Buyer and Seller contact information
- Price List Code
- Header and line item attributes
# Update an existing Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/update-an-existing-blanket-order
/openapi/openapi_commerce.json put /commerce/blanketorders/{blanketOrderId}
Update an existing Blanket Order.
# Update an item on a Blanket Order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/update-an-item-on-a-blanket-order
/openapi/openapi_commerce.json put /commerce/blanketorders/{blanketOrderId}/items/{itemId}
Update an item on a Blanket Order.
# Update (upsert) header-level attributes on a blanket order
Source: https://docs.kibocommerce.com/api-reference/blanketorder/update-upsert-header-level-attributes-on-a-blanket-order
/openapi/openapi_commerce.json put /commerce/blanketorders/{blanketOrderId}/attributes
Update (upsert) header-level attributes on a blanket order.
# Upsert line-level attributes on a blanket order item
Source: https://docs.kibocommerce.com/api-reference/blanketorder/upsert-line-level-attributes-on-a-blanket-order-item
/openapi/openapi_commerce.json put /commerce/blanketorders/{blanketOrderId}/items/{itemId}/attributes
Upsert line-level attributes on a blanket order item.
# Add Item
Source: https://docs.kibocommerce.com/api-reference/callofforder/add-item
/openapi/openapi_commerce.json post /commerce/callofforders/{callOffOrderId}/items
Add Item
# Aggregate requested quantity across call-off orders spanning every site in the current tenant.
Source: https://docs.kibocommerce.com/api-reference/callofforder/aggregate-requested-quantity-across-call-off-orders-spanning-every-site-in-the-current-tenant
/openapi/openapi_commerce.json get /commerce/callofforders/aggregate
Sums `items[].requestedQty` and returns breakdowns by product code, customer, status,
and requested ship month.
Use the `filter` parameter to scope the aggregation (e.g. `items.product.productCode in [SKU1,SKU2]`,
`customerAccountId eq 1234`, `items.status ne Cancelled`,
`items.requestedShipDate ge 2026-01-01`).
# Bulk cancel call-off orders
Source: https://docs.kibocommerce.com/api-reference/callofforder/bulk-cancel-call-off-orders
/openapi/openapi_commerce.json post /commerce/callofforders/actions/bulk-cancel
Bulk cancel call-off orders.
# Cancel Item
Source: https://docs.kibocommerce.com/api-reference/callofforder/cancel-item
/openapi/openapi_commerce.json post /commerce/callofforders/{callOffOrderId}/items/{itemId}/cancel
Cancel Item
# Create Call Off Order
Source: https://docs.kibocommerce.com/api-reference/callofforder/create-call-off-order
/openapi/openapi_commerce.json post /commerce/callofforders
Create Call Off Order
# Create header-level attributes on a call-off order
Source: https://docs.kibocommerce.com/api-reference/callofforder/create-header-level-attributes-on-a-call-off-order
/openapi/openapi_commerce.json post /commerce/callofforders/{callOffOrderId}/attributes
Create header-level attributes on a call-off order.
# Create line-level attributes on a call-off order item; skips FQNs that already exist
Source: https://docs.kibocommerce.com/api-reference/callofforder/create-line-level-attributes-on-a-call-off-order-item;-skips-fqns-that-already-exist
/openapi/openapi_commerce.json post /commerce/callofforders/{callOffOrderId}/items/{itemId}/attributes
Create line-level attributes on a call-off order item; skips FQNs that already exist.
# Delete a single header-level attribute from a call-off order by FQN
Source: https://docs.kibocommerce.com/api-reference/callofforder/delete-a-single-header-level-attribute-from-a-call-off-order-by-fqn
/openapi/openapi_commerce.json delete /commerce/callofforders/{callOffOrderId}/attributes/{attributeFqn}
Delete a single header-level attribute from a call-off order by FQN.
# Delete a single line-level attribute from a call-off order item by FQN
Source: https://docs.kibocommerce.com/api-reference/callofforder/delete-a-single-line-level-attribute-from-a-call-off-order-item-by-fqn
/openapi/openapi_commerce.json delete /commerce/callofforders/{callOffOrderId}/items/{itemId}/attributes/{attributeFqn}
Delete a single line-level attribute from a call-off order item by FQN.
# Get all header-level attributes for a call-off order
Source: https://docs.kibocommerce.com/api-reference/callofforder/get-all-header-level-attributes-for-a-call-off-order
/openapi/openapi_commerce.json get /commerce/callofforders/{callOffOrderId}/attributes
Get all header-level attributes for a call-off order.
# Get all line-level attributes for a call-off order item
Source: https://docs.kibocommerce.com/api-reference/callofforder/get-all-line-level-attributes-for-a-call-off-order-item
/openapi/openapi_commerce.json get /commerce/callofforders/{callOffOrderId}/items/{itemId}/attributes
Get all line-level attributes for a call-off order item.
# Get Available Actions
Source: https://docs.kibocommerce.com/api-reference/callofforder/get-available-actions
/openapi/openapi_commerce.json get /commerce/callofforders/{callOffOrderId}/actions
Get Available Actions
# Get Call Off Order
Source: https://docs.kibocommerce.com/api-reference/callofforder/get-call-off-order
/openapi/openapi_commerce.json get /commerce/callofforders/{callOffOrderId}
Get Call Off Order
# Get Call Off Orders
Source: https://docs.kibocommerce.com/api-reference/callofforder/get-call-off-orders
/openapi/openapi_commerce.json get /commerce/callofforders
Get Call Off Orders
# Get Change Messages
Source: https://docs.kibocommerce.com/api-reference/callofforder/get-change-messages
/openapi/openapi_commerce.json get /commerce/callofforders/{callOffOrderId}/changemessages
Get Change Messages
# Perform Action
Source: https://docs.kibocommerce.com/api-reference/callofforder/perform-action
/openapi/openapi_commerce.json post /commerce/callofforders/{callOffOrderId}/actions
Perform Action
# Release Call Off Order
Source: https://docs.kibocommerce.com/api-reference/callofforder/release-call-off-order
/openapi/openapi_commerce.json post /commerce/callofforders/{callOffOrderId}/release
Release Call Off Order
# Returns the list of available credit hold reasons for Call-Off Orders
Source: https://docs.kibocommerce.com/api-reference/callofforder/returns-the-list-of-available-credit-hold-reasons-for-call-off-orders
/openapi/openapi_commerce.json get /commerce/callofforders/credithold/reasons
Returns the list of available credit hold reasons for Call-Off Orders.
# Update Call Off Order
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-call-off-order
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}
Update Call Off Order
# Update Item Destination
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-item-destination
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/items/{itemId}/destination
Update Item Destination
# Update Item Destination By Id
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-item-destination-by-id
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/items/{itemId}/destination/{destinationId}
Update Item Destination By Id
# Update Item Price
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-item-price
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/items/{itemId}/price/{unitPrice}
Update Item Price
# Update Item Quantity
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-item-quantity
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/items/{itemId}/quantity/{quantity}
Update Item Quantity
# Update Item Requested Ship Date
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-item-requested-ship-date
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/items/{itemId}/shipdate
Update Item Requested Ship Date
# Update (upsert) header-level attributes on a call-off order
Source: https://docs.kibocommerce.com/api-reference/callofforder/update-upsert-header-level-attributes-on-a-call-off-order
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/attributes
Update (upsert) header-level attributes on a call-off order.
# Upsert line-level attributes on a call-off order item
Source: https://docs.kibocommerce.com/api-reference/callofforder/upsert-line-level-attributes-on-a-call-off-order-item
/openapi/openapi_commerce.json put /commerce/callofforders/{callOffOrderId}/items/{itemId}/attributes
Upsert line-level attributes on a call-off order item.
# Creates a Call-Off Order Rule. The expression is validated and canonicalized
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/creates-a-call-off-order-rule-the-expression-is-validated-and-canonicalized
/openapi/openapi_commerce.json post /commerce/rules/callOffOrder
at save time; `code` auto-generates from `name` when omitted.
# Evaluates an enabled rule and returns the paged list of matching
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/evaluates-an-enabled-rule-and-returns-the-paged-list-of-matching
/openapi/openapi_commerce.json post /commerce/rules/callOffOrder/{code}/evaluate
Call-Off Order ids. Optionally AND-composes the rule expression with a
`statusFilter` to scope results to a single status.
# Hard-deletes a rule by code. v1 has no usage guard —
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/hard-deletes-a-rule-by-code-v1-has-no-usage-guard-—
/openapi/openapi_commerce.json delete /commerce/rules/callOffOrder/{code}
deleting a rule that is still referenced by a workflow is the caller's
responsibility.
# Lists Call-Off Order Rules for the current tenant with offset paging.
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/lists-call-off-order-rules-for-the-current-tenant-with-offset-paging
/openapi/openapi_commerce.json get /commerce/rules/callOffOrder
Default sort is `createDate DESC`; sortBy accepts
`createDate`, `updateDate`, `code`, `name`, `ruleType`.
filter follows Kibo's standard filter syntax over
`code`, `name`, `ruleType`, `enabled`, `createDate`,
`updateDate`.
# Returns a single Call-Off Order Rule by its tenant-unique code
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/returns-a-single-call-off-order-rule-by-its-tenant-unique-code
/openapi/openapi_commerce.json get /commerce/rules/callOffOrder/{code}
Returns a single Call-Off Order Rule by its tenant-unique code.
# Returns the authoring schema for Call-Off Order Rules: the complete set of
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/returns-the-authoring-schema-for-call-off-order-rules:-the-complete-set-of
/openapi/openapi_commerce.json get /commerce/rules/callOffOrder/schema
expression fields with their data types, allowed operators, nullability,
enum values, and the dynamic-attribute slot pointing at the tenant's
call-off attribute catalog. Reflection-driven from the validator's
`[ExpressionContextProperty]` metadata so the UI and server stay in
lockstep automatically.
# Updates an existing rule. `code` is immutable — a body `code` that
Source: https://docs.kibocommerce.com/api-reference/callofforderrule/updates-an-existing-rule-`code`-is-immutable-—-a-body-`code`-that
/openapi/openapi_commerce.json put /commerce/rules/callOffOrder/{code}
differs from the URL code is rejected. The expression is
re-validated and the canonical `Text` regenerated from `Tree`.
# Create call-off release rule
Source: https://docs.kibocommerce.com/api-reference/calloffreleaserules/create-call-off-release-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/calloffrelease
Creates a new call-off release rule.
# Delete call-off release rule
Source: https://docs.kibocommerce.com/api-reference/calloffreleaserules/delete-call-off-release-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/calloffrelease/{code}
Permanently deletes a call-off release rule (FR-013 hard delete).
# Get call-off release rule by code
Source: https://docs.kibocommerce.com/api-reference/calloffreleaserules/get-call-off-release-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/calloffrelease/{code}
Gets a call-off release rule by its unique code.
# Get call-off release rules
Source: https://docs.kibocommerce.com/api-reference/calloffreleaserules/get-call-off-release-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/calloffrelease
Gets a paged collection of call-off release rules according to any specified filter criteria and sort options.
# Update call-off release rule
Source: https://docs.kibocommerce.com/api-reference/calloffreleaserules/update-call-off-release-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/calloffrelease/{code}
Updates an existing call-off release rule with full replacement semantics (FR-009).
# Update call-off release rule rank
Source: https://docs.kibocommerce.com/api-reference/calloffreleaserules/update-call-off-release-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/calloffrelease/{code}/rank
Atomically reorders ranks within the current master catalog. Returns 204 No Content (FR-019).
# Get Search Campaign
Source: https://docs.kibocommerce.com/api-reference/campaigns/get-search-campaign
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/campaigns/{campaignId}
Get a specific campaign by campaign id.
# Get Search Campaigns
Source: https://docs.kibocommerce.com/api-reference/campaigns/get-search-campaigns
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/campaigns/all
Get list of Search campaigns.
# Get Cancel Reasons
Source: https://docs.kibocommerce.com/api-reference/cancelreasons/get-cancel-reasons
/openapi/openapi_commerce.json get /cancel/reasons
Returns cancellation reasons for the specified resource type and category.
Category defaults to SHOPPER. Category matching is case-insensitive.
# Create Carrier Configuration
Source: https://docs.kibocommerce.com/api-reference/carrierconfiguration/create-carrier-configuration
/openapi/openapi_shipping_admin.json post /commerce/shipping/admin/carriers/{carrierId}
Create a new carrier configuration. The settings[] field is deprecated and no longer needs to be provided when working with credential sets.
# Delete Carrier Configuration
Source: https://docs.kibocommerce.com/api-reference/carrierconfiguration/delete-carrier-configuration
/openapi/openapi_shipping_admin.json delete /commerce/shipping/admin/carriers/{carrierId}
Delete an existing Carrier Configuration
# Get carrier configuration information
Source: https://docs.kibocommerce.com/api-reference/carrierconfiguration/get-carrier-configuration-information
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/{carrierId}
Get Carrier Configuration (for this particular site)
# Get Carrier Configurations
Source: https://docs.kibocommerce.com/api-reference/carrierconfiguration/get-carrier-configurations
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers
Retrieves a list of Carrier Configurations according to any specified filter criteria and sort options
# Update Carrier Configuration
Source: https://docs.kibocommerce.com/api-reference/carrierconfiguration/update-carrier-configuration
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/carriers/{carrierId}
Update an existing carrier configuration. The settings[] field is deprecated and no longer needs to be provided when working with credential sets.
# Get Service Types (with Carrier ID)
Source: https://docs.kibocommerce.com/api-reference/carrierconfigurationglobal/get-service-types-with-carrier-id
/openapi/openapi_shipping_admin.json get /commerce/shipping/global/carriers/{carrierId}/serviceTypes/{localeCode}
Retrieves the available service types for the Default Application carriers
# Get Service Types (without Carrier ID)
Source: https://docs.kibocommerce.com/api-reference/carrierconfigurationglobal/get-service-types-without-carrier-id
/openapi/openapi_shipping_admin.json get /commerce/shipping/global/carriers/serviceTypes/{localeCode}
Retrieves the available service types for the Default Application carriers
# Gets all the Signature Options
Source: https://docs.kibocommerce.com/api-reference/carrierconfigurationglobal/gets-all-the-signature-options
/openapi/openapi_shipping_admin.json get /commerce/shipping/global/carriers/signatureOptions
Gets all the Signature Options
# Create Carrier Credentials
Source: https://docs.kibocommerce.com/api-reference/carriercredential/create-carrier-credentials
/openapi/openapi_shipping_admin.json post /commerce/shipping/admin/carriers/credentials/{carrierId}
Creates new carrier credentials. See this guide for details about the fields that are required for each carrier.
# Delete Carrier Credentials
Source: https://docs.kibocommerce.com/api-reference/carriercredential/delete-carrier-credentials
/openapi/openapi_shipping_admin.json delete /commerce/shipping/admin/carriers/credentials/{carrierId}
Deletes carrier credentials
# Get Carrier Credentials
Source: https://docs.kibocommerce.com/api-reference/carriercredential/get-carrier-credentials
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/credentials
Returns a collection of all carrier credentials
# Get Carrier Credentials by ID
Source: https://docs.kibocommerce.com/api-reference/carriercredential/get-carrier-credentials-by-id
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/credentials/{carrierId}
Retrieves carrier credentials for a specific Carrier ID
# Update Carrier Credentials
Source: https://docs.kibocommerce.com/api-reference/carriercredential/update-carrier-credentials
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/carriers/credentials/{carrierId}
Updates existing carrier credentials. See this guide for details about the fields that are required for each carrier.
# Create Carrier Credential Set
Source: https://docs.kibocommerce.com/api-reference/carriercredentialset/create-carrier-credential-set
/openapi/openapi_shipping_admin.json post /commerce/shipping/admin/carriers/credential-sets/{carrierId}
Creates a new carrier credential set. See this guide for details about the fields that are required for each carrier.
# Delete Carrier Credential Set
Source: https://docs.kibocommerce.com/api-reference/carriercredentialset/delete-carrier-credential-set
/openapi/openapi_shipping_admin.json delete /commerce/shipping/admin/carriers/credential-sets/{carrierId}/{code}
Deletes a carrier credential set
# Get Carrier Credential Set
Source: https://docs.kibocommerce.com/api-reference/carriercredentialset/get-carrier-credential-set
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/credential-sets/{carrierId}/{code}
Returns a credential set based on a specific Carrier ID and Code
# Get Carrier Credential Sets
Source: https://docs.kibocommerce.com/api-reference/carriercredentialset/get-carrier-credential-sets
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/credential-sets
Returns a collection of all carrier credential sets
# Update Carrier Credential Set
Source: https://docs.kibocommerce.com/api-reference/carriercredentialset/update-carrier-credential-set
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/carriers/credential-sets/{carrierId}/{code}
Update an existing carrier credential set. See this guide for details about the fields that are required for each carrier.
# Get Carrier Definition
Source: https://docs.kibocommerce.com/api-reference/carrierdefinition/get-carrier-definition
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/definitions/{carrierId}
Retrieves the carrier definition for the specified carrier
# Get Carrier Definitions
Source: https://docs.kibocommerce.com/api-reference/carrierdefinition/get-carrier-definitions
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/carriers/definitions
Retrieves all shipping carrier definitions for the specified tenant
# Add Item To Cart
Source: https://docs.kibocommerce.com/api-reference/cart/add-item-to-cart
/openapi/openapi_commerce.json post /commerce/carts/current/items
Adds a product or other item to the cart of the current shopper.
# Add Item To Cart By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/add-item-to-cart-by-cartid
/openapi/openapi_commerce.json post /commerce/carts/{cartId}/items
Adds a product or a cart item to the cart specified by the cart ID.
# Add Items To Cart
Source: https://docs.kibocommerce.com/api-reference/cart/add-items-to-cart
/openapi/openapi_commerce.json post /commerce/carts/current/bulkitems
Adds multiple cart items to the cart of the current shopper.
# Add Items To Cart By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/add-items-to-cart-by-cartid
/openapi/openapi_commerce.json post /commerce/carts/{cartId}/bulkitems
Adds multiple cart items to the cart specified by cartId.
# Adds Extended Properties
Source: https://docs.kibocommerce.com/api-reference/cart/adds-extended-properties
/openapi/openapi_commerce.json post /commerce/carts/current/extendedproperties
Add Extended Properties on the current cart. Store an arbitrary number of cart extended properties such as tracking strings, marketing sources, affiliates, sales personnel/data, and so on, on a per cart basis. Each cart may have none, one, or more than one entry in the extended properties collection, and all values in the extended properties collection are represented as strings. When you create an order from a cart, all extended properties are retained from the cart and copied to the order.
# Apply Coupon
Source: https://docs.kibocommerce.com/api-reference/cart/apply-coupon
/openapi/openapi_commerce.json put /commerce/carts/{cartId}/coupons/{couponCode}
Apply coupon to the cart.
# Delete Cart
Source: https://docs.kibocommerce.com/api-reference/cart/delete-cart
/openapi/openapi_commerce.json delete /commerce/carts/{cartId}
Deletes the cart by cart ID.
# Delete Cart Item
Source: https://docs.kibocommerce.com/api-reference/cart/delete-cart-item
/openapi/openapi_commerce.json delete /commerce/carts/current/items/{cartItemId}
Removes a particular cart item from the cart of the current shopper.
# Delete Cart Item By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/delete-cart-item-by-cartid
/openapi/openapi_commerce.json delete /commerce/carts/{cartId}/items/{cartItemId}
Removes a particular cart item from the cart specified by cart item Id and cart Id.
# Delete Current Cart
Source: https://docs.kibocommerce.com/api-reference/cart/delete-current-cart
/openapi/openapi_commerce.json delete /commerce/carts/current
Deletes the cart of the current shopper.
# Delete Extended Properties.
Source: https://docs.kibocommerce.com/api-reference/cart/delete-extended-properties
/openapi/openapi_commerce.json delete /commerce/carts/current/extendedproperties
Delete extended properties on the current cart.
# Delete Extended Property
Source: https://docs.kibocommerce.com/api-reference/cart/delete-extended-property
/openapi/openapi_commerce.json delete /commerce/carts/current/extendedproperties/{key}
Delete extended property on the current cart using the key.
# Delete Multiple Cart Items
Source: https://docs.kibocommerce.com/api-reference/cart/delete-multiple-cart-items
/openapi/openapi_commerce.json put /commerce/carts/current/bulkitems/delete
Removes multiple cart items from the cart of the current shopper in a single operation.
# Delete Multiple Cart Items By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/delete-multiple-cart-items-by-cartid
/openapi/openapi_commerce.json put /commerce/carts/{cartId}/bulkitems/delete
Removes multiple cart items from the specified cart in a single operation.
# Delete User Cart
Source: https://docs.kibocommerce.com/api-reference/cart/delete-user-cart
/openapi/openapi_commerce.json delete /commerce/carts/user/{userId}
Deletes the cart of the user by user ID.
# Get Cart
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart
/openapi/openapi_commerce.json get /commerce/carts/{cartId}
Retrieves the details of the cart specified by cart ID.
# Get Cart Item
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart-item
/openapi/openapi_commerce.json get /commerce/carts/current/items/{cartItemId}
Retrieves an individual cart item from the cart of the current shopper specified by its cart item Id.
# Get Cart Item By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart-item-by-cartid
/openapi/openapi_commerce.json get /commerce/carts/{cartId}/items/{cartItemId}
Retrieves an individual cart item from the cart by cart Id and cart item Id.
# Get Cart Items
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart-items
/openapi/openapi_commerce.json get /commerce/carts/current/items
Retrieves the details of each cart item such as the product name, stock count, unit price, discounts, quantity ordered and total price
# Get Cart Items By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart-items-by-cartid
/openapi/openapi_commerce.json get /commerce/carts/{cartId}/items
Retrieves the details of each cart item such as the product name, stock count, unit price, discounts, quantity ordered and total price for the cart by cartId.
# Get Cart Summary
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart-summary
/openapi/openapi_commerce.json get /commerce/carts/summary
Retrieves the number of items in the active cart, total cost of items in the cart and the cart expiration. (Anonymous shoppers cart expires in 14 days.)
# Get Cart Summary By Cart Id
Source: https://docs.kibocommerce.com/api-reference/cart/get-cart-summary-by-cart-id
/openapi/openapi_commerce.json get /commerce/carts/{cartId}/summary
Retrieves the number of items in the specified cart, total cost of items in the cart, and whether the cart has expired by cartId. All anonymous idle carts that do not proceed to checkout expire after 14 days.
# Get Extended Properties
Source: https://docs.kibocommerce.com/api-reference/cart/get-extended-properties
/openapi/openapi_commerce.json get /commerce/carts/current/extendedproperties
Get extended properties on a cart.
# Get Messages
Source: https://docs.kibocommerce.com/api-reference/cart/get-messages
/openapi/openapi_commerce.json get /commerce/carts/current/messages
Retrieves messages to and from the current shopper. These are messages supplied by the system to notify the shopper of price increases or decreases or product unavailability.
# Get Or Create Cart
Source: https://docs.kibocommerce.com/api-reference/cart/get-or-create-cart
/openapi/openapi_commerce.json get /commerce/carts/current
Retrieves a cart's contents for the current shopper. If the shopper does not have an active cart on the site, one is created.
# Get Or Create User Cart
Source: https://docs.kibocommerce.com/api-reference/cart/get-or-create-user-cart
/openapi/openapi_commerce.json post /commerce/carts/user/{userId}
Get the current cart or create a new cart for the user specified by user ID.
# Get User Cart
Source: https://docs.kibocommerce.com/api-reference/cart/get-user-cart
/openapi/openapi_commerce.json get /commerce/carts/user/{userId}
Retrieves the details of the user's cart from the user ID.Shoppers are not allowed to execute this call. If this ever changes, then auth logic will need to be added
# Get User Cart Summary
Source: https://docs.kibocommerce.com/api-reference/cart/get-user-cart-summary
/openapi/openapi_commerce.json get /commerce/carts/user/{userId}/summary
Retrieves the number of items in the active cart, total cost of items in the cart and the cart expiration by userId. All anonymous idle carts that do not proceed to checkout expire after 14 days.
# Reject Suggested Discount
Source: https://docs.kibocommerce.com/api-reference/cart/reject-suggested-discount
/openapi/openapi_commerce.json post /commerce/carts/{cartId}/rejectautodiscount/{discountId}
Reject Suggested Discount
# Remove All Cart Items
Source: https://docs.kibocommerce.com/api-reference/cart/remove-all-cart-items
/openapi/openapi_commerce.json delete /commerce/carts/current/items
Clears all the cart items from the cart of a current shopper.
# Remove All Cart Items By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/remove-all-cart-items-by-cartid
/openapi/openapi_commerce.json delete /commerce/carts/{cartId}/items
Clears all the cart items from the cart by the cartId.
# Remove All Messages
Source: https://docs.kibocommerce.com/api-reference/cart/remove-all-messages
/openapi/openapi_commerce.json delete /commerce/carts/current/messages
Removes all messages associated with the cart of the current shopper.
# Remove Coupon
Source: https://docs.kibocommerce.com/api-reference/cart/remove-coupon
/openapi/openapi_commerce.json delete /commerce/carts/{cartId}/coupons/{couponCode}
Remove a coupon that had been previously applied to the cart.
# Remove Coupons
Source: https://docs.kibocommerce.com/api-reference/cart/remove-coupons
/openapi/openapi_commerce.json delete /commerce/carts/{cartId}/coupons
Removes all coupons that had been previously applied to the cart.
# Remove Message
Source: https://docs.kibocommerce.com/api-reference/cart/remove-message
/openapi/openapi_commerce.json delete /commerce/carts/current/messages/{messageId}
Removes a single message associated with the cart of the current shopper specified by messageId.
# Update Cart
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart
/openapi/openapi_commerce.json put /commerce/carts/current
Updates the cart of the current shopper.
# Update Cart By Cart Id
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-by-cart-id
/openapi/openapi_commerce.json put /commerce/carts/{cartId}
Updates the cart specified by cart ID
# Update Cart Item
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-item
/openapi/openapi_commerce.json put /commerce/carts/current/items/{cartItemId}
Updates a particular cart item in the cart of the current shopper.
# Update Cart Item By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-item-by-cartid
/openapi/openapi_commerce.json put /commerce/carts/{cartId}/items/{cartItemId}
Updates a particular cart item in the cart specified by card Id.
# Update Cart Item Quantity
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-item-quantity
/openapi/openapi_commerce.json put /commerce/carts/current/items/{cartItemId}/{quantity}
Updates the quantity of an individual cart item in the cart of the current shopper.
# Update Cart Item Quantity By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-item-quantity-by-cartid
/openapi/openapi_commerce.json put /commerce/carts/{cartId}/items/{cartItemId}/{quantity}
Updates the quantity of an individual cart item in the cart specified by cart Id.
# Update Cart Items
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-items
/openapi/openapi_commerce.json put /commerce/carts/current/bulkitems
Updates multiple cart items in the cart of the current shopper.
# Update Cart Items By CartId
Source: https://docs.kibocommerce.com/api-reference/cart/update-cart-items-by-cartid
/openapi/openapi_commerce.json put /commerce/carts/{cartId}/bulkitems
Updates multiple cart items in the cart specified by cartId.
# Update Extended Properties
Source: https://docs.kibocommerce.com/api-reference/cart/update-extended-properties
/openapi/openapi_commerce.json put /commerce/carts/current/extendedproperties
Update extended properties on the current cart.
# Update Extended Property
Source: https://docs.kibocommerce.com/api-reference/cart/update-extended-property
/openapi/openapi_commerce.json put /commerce/carts/current/extendedproperties/{key}
Update extended property on the current cart using the key.
# Update User Cart
Source: https://docs.kibocommerce.com/api-reference/cart/update-user-cart
/openapi/openapi_commerce.json put /commerce/carts/user/{userId}
Updates the cart of the user specified by user ID.
# Create Cart Settings
Source: https://docs.kibocommerce.com/api-reference/cartsettings/create-cart-settings
/openapi/openapi_settings.json post /commerce/settings/cart/cartsettings
Creates new cart settings. If enabling the Handling Fee, note that doing so does not display handling fees as line items in your storefront's checkout page. Rather, it simply includes the cost of the handling fees in the total. To display handling fees as line items in the checkout page, ask your theme developer to make the necessary changes.
# Get Cart Settings
Source: https://docs.kibocommerce.com/api-reference/cartsettings/get-cart-settings
/openapi/openapi_settings.json get /commerce/settings/cart/cartsettings
Retrieves existing cart settings.
# Update Cart Settings
Source: https://docs.kibocommerce.com/api-reference/cartsettings/update-cart-settings
/openapi/openapi_settings.json put /commerce/settings/cart/cartsettings
Modifies existing cart settings. If enabling the Handling Fee, note that doing so does not display handling fees as line items in your storefront's checkout page. Rather, it simply includes the cost of the handling fees in the total. To display handling fees as line items in the checkout page, ask your theme developer to make the necessary changes.
# Add Category
Source: https://docs.kibocommerce.com/api-reference/categories/add-category
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categories
Adds a new category to the catalog's category hierarchy. Specify a ParentCategoryID to determine where to locate the category in the hierarchy; if not specified it becomes a top-level category. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Category Attribute
Source: https://docs.kibocommerce.com/api-reference/categories/add-category-attribute
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categories/{categoryId}/attributes
Adds a new category attribute to the category. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Products to Category
Source: https://docs.kibocommerce.com/api-reference/categories/add-products-to-category
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categories/{categoryId}/add-products
Adds the products in the provided product code list to the specified category.
# Delete Category
Source: https://docs.kibocommerce.com/api-reference/categories/delete-category
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/categories/{categoryId}
Deletes the category specified by its category ID. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Category Attribute
Source: https://docs.kibocommerce.com/api-reference/categories/delete-category-attribute
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/categories/{categoryId}/attributes/{attributeFQN}
Deletes the category attribute specified by its attributeFQN.
# Get Categories
Source: https://docs.kibocommerce.com/api-reference/categories/get-categories
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categories
Retrieves a list of categories according to any specified filter criteria and sort options. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Category
Source: https://docs.kibocommerce.com/api-reference/categories/get-category
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categories/{categoryId}
Retrieves the details of a single category. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Category Attribute
Source: https://docs.kibocommerce.com/api-reference/categories/get-category-attribute
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categories/{categoryId}/attributes/{attributeFQN}
Retrieves the details of a single category attribute. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Category Attributes
Source: https://docs.kibocommerce.com/api-reference/categories/get-category-attributes
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categories/{categoryId}/attributes
Retrieves a list of category attributes. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Category Tree
Source: https://docs.kibocommerce.com/api-reference/categories/get-category-tree
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/categories/tree
Retrieves the list of product categories that appear on the storefront organized in a hierarchical format. Hidden categories do not appear in the list.
# Get Child Categories
Source: https://docs.kibocommerce.com/api-reference/categories/get-child-categories
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categories/{categoryId}/children
Retrieves the immediate subcategories of a category. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Categories
Source: https://docs.kibocommerce.com/api-reference/categories/get-product-categories
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/categories
Retrieves a list of product categories that appear on the storefront as a flat list. Hidden categories do not appear in the list.
# Get Product Category
Source: https://docs.kibocommerce.com/api-reference/categories/get-product-category
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/categories/{categoryId}
Retrieves the name and details of a category that appears on the storefront.
# Remove Products from Category
Source: https://docs.kibocommerce.com/api-reference/categories/remove-products-from-category
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categories/{categoryId}/remove-products
Removes the products in the provided product code list from the specified category.
# Search Category Attributes
Source: https://docs.kibocommerce.com/api-reference/categories/search-category-attributes
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categories/searchCategoryAttributes
Retrieves a list of categories according to any specified filter criteria and sort options for attributes. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Category
Source: https://docs.kibocommerce.com/api-reference/categories/update-category
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/categories/{categoryId}
Modifies a category such as moving it to another location in the category tree, or changing whether it is visible on the storefront. This PUT replaces the existing resource, so be sure to include all the information that you want to maintain for the category. Any unspecified properties are set to null.
This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Category Attribute
Source: https://docs.kibocommerce.com/api-reference/categories/update-category-attribute
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/categories/{categoryId}/attributes/{attributeFQN}
Modifies the category attribute. This current version of the Categories API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access category data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Validate Dynamic Category Expression
Source: https://docs.kibocommerce.com/api-reference/categories/validate-dynamic-category-expression
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categories/ValidateDynamicExpression
Validate an expression for a dynamic category.
# Validate Realtime Dynamic Category Expression
Source: https://docs.kibocommerce.com/api-reference/categories/validate-realtime-dynamic-category-expression
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categories/ValidateRealTimeDynamicExpression
Validate an expression for a realtime dynamic category.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/categoryattributedefinition/create-attribute
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/categoryattributedefinition/attributes
Add a new category attribute definition.
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/categoryattributedefinition/get-attribute
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categoryattributedefinition/attributes/{attributeFQN}
Get a category attribute by its attribute FQN.
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/categoryattributedefinition/get-attribute-vocabulary-values
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categoryattributedefinition/attributes/{attributeFQN}/VocabularyValues
Retrieves the details of attribute vocabulary values.
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/categoryattributedefinition/get-attributes
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/categoryattributedefinition/attributes
Retrieves the details of attributes.
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/categoryattributedefinition/update-attribute
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/categoryattributedefinition/attributes/{attributeFQN}
Update a category attribute.
# Creates Channel
Source: https://docs.kibocommerce.com/api-reference/channel/creates-channel
/openapi/openapi_commerce.json post /commerce/channels
Creates a new channel that defines a new logical business division to use for financial reporting.
# Delete Channel
Source: https://docs.kibocommerce.com/api-reference/channel/delete-channel
/openapi/openapi_commerce.json delete /commerce/channels/{code}
Deletes a channel specified by channel Id. After deleting this channel, assign its associated sites to another channel. Because channels are managed at the tenant level, you must associate all the tenant's sites with a channel. Sites that do not have a defined channel association cannot successfully submit orders.
# Get Channel
Source: https://docs.kibocommerce.com/api-reference/channel/get-channel
/openapi/openapi_commerce.json get /commerce/channels/{code}
Retrieves the details of an channel specified by the channel ID.
# Get Channels
Source: https://docs.kibocommerce.com/api-reference/channel/get-channels
/openapi/openapi_commerce.json get /commerce/channels
Retrieves a list of channels according to any specified filter criteria and sort options. All orders include a channel association that enables the company to perform financial reporting for each defined channel. Because channels are managed at the tenant level, you must associate all the tenant's sites with a channel. Sites that do not have a defined channel association cannot successfully submit orders.
# Update Channel
Source: https://docs.kibocommerce.com/api-reference/channel/update-channel
/openapi/openapi_commerce.json put /commerce/channels/{code}
Updates a channel.
# Creates Channel Group.
Source: https://docs.kibocommerce.com/api-reference/channelgroup/creates-channel-group
/openapi/openapi_commerce.json post /commerce/channelgroups
Creates a new channel group.
# Delete Channel Group
Source: https://docs.kibocommerce.com/api-reference/channelgroup/delete-channel-group
/openapi/openapi_commerce.json delete /commerce/channelgroups/{code}
Deletes a channel grop specified by group code.
# Get Channel Group
Source: https://docs.kibocommerce.com/api-reference/channelgroup/get-channel-group
/openapi/openapi_commerce.json get /commerce/channelgroups/{code}
Retrieves the details of an channel group specified by the code.
# Get Channel Groups
Source: https://docs.kibocommerce.com/api-reference/channelgroup/get-channel-groups
/openapi/openapi_commerce.json get /commerce/channelgroups
Retrieves a list of channel groups according to any specified filter criteria and sort options.
# Updates Channel Group
Source: https://docs.kibocommerce.com/api-reference/channelgroup/updates-channel-group
/openapi/openapi_commerce.json put /commerce/channelgroups/{code}
Updates a specific channel group.
# Add Checkout Item
Source: https://docs.kibocommerce.com/api-reference/checkout/add-checkout-item
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/items
Adds a product or other item to the checkout of the current shopper.
# Add Destination
Source: https://docs.kibocommerce.com/api-reference/checkout/add-destination
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/destinations
Adds a specific destination to the checkout.
# Apply Coupon
Source: https://docs.kibocommerce.com/api-reference/checkout/apply-coupon
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/coupons/{couponCode}
Apply a coupon to the Checkout.
# Bulk Update Item Destinations
Source: https://docs.kibocommerce.com/api-reference/checkout/bulk-update-item-destinations
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/items/destinations
Associate items to destinations in bulk.
# Change Checkout Price List
Source: https://docs.kibocommerce.com/api-reference/checkout/change-checkout-price-list
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/priceList
Changes the pricelist associated with a checkout.The desired price list code should be specified on the ApiContext.
# Create Checkout Attributes
Source: https://docs.kibocommerce.com/api-reference/checkout/create-checkout-attributes
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/attributes
Creates list of checkout attributes specified by checkout Id.
# Create Checkout From Cart
Source: https://docs.kibocommerce.com/api-reference/checkout/create-checkout-from-cart
/openapi/openapi_commerce.json post /commerce/checkouts
Creates a new checkout from an existing cart, that is, when the customer chooses to proceed to checkout.
# Create Payment Action
Source: https://docs.kibocommerce.com/api-reference/checkout/create-payment-action
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/payments/actions
Sets the action of the specified payment transaction interaction. Available actions depend on the current status of the payment transaction. If in doubt, get a list of available payment actions first.
# Delete Checkout Item
Source: https://docs.kibocommerce.com/api-reference/checkout/delete-checkout-item
/openapi/openapi_commerce.json delete /commerce/checkouts/{checkoutId}/items/{itemId}
Removes a particular item from the checkout of the current shopper.
# Get Available Actions
Source: https://docs.kibocommerce.com/api-reference/checkout/get-available-actions
/openapi/openapi_commerce.json get /commerce/checkouts/{checkoutId}/actions
Retrieves available actions which depends on the status of the checkout.
# Get Available Shipping Methods
Source: https://docs.kibocommerce.com/api-reference/checkout/get-available-shipping-methods
/openapi/openapi_commerce.json get /commerce/checkouts/{checkoutId}/shippingMethods
Retrieves available shipping methods for groupings. Typically used to display available shipping method options on the checkout page.
# Get Checkout
Source: https://docs.kibocommerce.com/api-reference/checkout/get-checkout
/openapi/openapi_commerce.json get /commerce/checkouts/{checkoutId}
Retrieves the details of a checkout specified by the checkout ID.
# Get Checkout Attributes
Source: https://docs.kibocommerce.com/api-reference/checkout/get-checkout-attributes
/openapi/openapi_commerce.json get /commerce/checkouts/{checkoutId}/attributes
Gets the list of attributes specified by checkout Id.
# Get Checkouts
Source: https://docs.kibocommerce.com/api-reference/checkout/get-checkouts
/openapi/openapi_commerce.json get /commerce/checkouts
Retrieves a list of checkouts according to any specified filter criteria and sort options.
# Get Destination
Source: https://docs.kibocommerce.com/api-reference/checkout/get-destination
/openapi/openapi_commerce.json get /commerce/checkouts/{checkoutId}/destinations/{destinationId}
Gets a destination specified by the checkout Id and destination Id.
# Get Destinations
Source: https://docs.kibocommerce.com/api-reference/checkout/get-destinations
/openapi/openapi_commerce.json get /commerce/checkouts/{checkoutId}/destinations
Gets all the destinations specified by the checkout Id.
# Perform Checkout Action
Source: https://docs.kibocommerce.com/api-reference/checkout/perform-checkout-action
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/actions
Perform an action on the checkout. Available actions depend on the current state of the checkout. If in doubt, get a list of available checkout actions first.
# Perform Payment Action
Source: https://docs.kibocommerce.com/api-reference/checkout/perform-payment-action
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/payments/{paymentId}/actions
Sets the action of the specified payment transaction interaction. Available actions depend on the current status of the payment transaction. \r\nIf in doubt, get a list of available payment actions first. Note that for order management-only systems that use No-Operation payment gateways, such as due to the payments being processed by an external storefront or service instead of Kibo, these actions will not actually be performed by Kibo and instead will be automatically marked as a success.
# Process Digital Wallet
Source: https://docs.kibocommerce.com/api-reference/checkout/process-digital-wallet
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/digitalWallet/{digitalWalletType}
Processes the digital wallet sent specified by checkout id and digital wallet type.
# Remove Coupon
Source: https://docs.kibocommerce.com/api-reference/checkout/remove-coupon
/openapi/openapi_commerce.json delete /commerce/checkouts/{checkoutId}/coupons/{couponCode}
Removes a coupon that had been previously applied to the checkout.
# Remove Coupons
Source: https://docs.kibocommerce.com/api-reference/checkout/remove-coupons
/openapi/openapi_commerce.json delete /commerce/checkouts/{checkoutId}/coupons
Removes all coupons that had been previously applied to the checkout.
# Remove Destination
Source: https://docs.kibocommerce.com/api-reference/checkout/remove-destination
/openapi/openapi_commerce.json delete /commerce/checkouts/{checkoutId}/destinations/{destinationId}
Removes a destination specified by checkout Id and destination Id.
# Resend Checkout Confirmation Email
Source: https://docs.kibocommerce.com/api-reference/checkout/resend-checkout-confirmation-email
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/email/resend
Resends email on checkout confirmation.
# Set Shipping Methods
Source: https://docs.kibocommerce.com/api-reference/checkout/set-shipping-methods
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/shippingMethods
Sets the shipping method for specified groupings.
# Split Item
Source: https://docs.kibocommerce.com/api-reference/checkout/split-item
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/items/{itemId}/split
Splits an existing item into two. The new item's quantity will be !:quantity and the original item's quantity will be reduced accordingly.
# Update Checkout
Source: https://docs.kibocommerce.com/api-reference/checkout/update-checkout
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}
Updates the details of a checkout specified by the checkout ID.
# Update Checkout Attribute
Source: https://docs.kibocommerce.com/api-reference/checkout/update-checkout-attribute
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/attributes
Updates the list of checkout attributes specified by checkout id and removes the missing attributes if not passed when removeMissing flag is set.
# Update Checkout Item Gift Information
Source: https://docs.kibocommerce.com/api-reference/checkout/update-checkout-item-gift-information
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/items/{itemId}/updateGiftInfo
Updates the gift information on a checkout item
# Update Delivery Dates of Items in bulk
Source: https://docs.kibocommerce.com/api-reference/checkout/update-delivery-dates-of-items-in-bulk
/openapi/openapi_commerce.json post /commerce/checkouts/{checkoutId}/items/deliverydates
Update delivery dates of items in bulk
# Update Destination
Source: https://docs.kibocommerce.com/api-reference/checkout/update-destination
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/destinations/{destinationId}
Updates a destination specified by checkout Id and destination Id.
# Update Item Destination
Source: https://docs.kibocommerce.com/api-reference/checkout/update-item-destination
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/items/{itemId}/destination/{destinationId}
Associate an item to a destination.
# Update Item Subscription Info
Source: https://docs.kibocommerce.com/api-reference/checkout/update-item-subscription-info
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/items/{itemId}/subscriptionInfo
Updates the subscription info on the Item.
# Update SubstituteInfo on CheckoutItem
Source: https://docs.kibocommerce.com/api-reference/checkout/update-substituteinfo-on-checkoutitem
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/items/{itemId}/upsertSubstituteInfo
Update SubstituteInfo on CheckoutItem
# Update the Delivery Date of the Item
Source: https://docs.kibocommerce.com/api-reference/checkout/update-the-delivery-date-of-the-item
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/items/{itemId}/deliverydate
Update the Delivery Date of the Item
# Upsert Inventory Tags
Source: https://docs.kibocommerce.com/api-reference/checkout/upsert-inventory-tags
/openapi/openapi_commerce.json put /commerce/checkouts/{checkoutId}/items/{itemId}/upsert-inventory-tags
Upsert Inventory Tags
# Add Third Party Payment Workflow
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/add-third-party-payment-workflow
/openapi/openapi_settings.json put /commerce/settings/checkout/paymentsettings/thirdpartyworkflows
Adds a third party payment workflow definition. A third-party payment workflow is a definition of a process by which a third-party payment provider (such as Amazon Payments or PayPal Express) interacts with the Unified eCommerce platform.
# Delete Third Party Payment Workflow
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/delete-third-party-payment-workflow
/openapi/openapi_settings.json delete /commerce/settings/checkout/paymentsettings/thirdpartyworkflows/{fullyQualifiedName}
Deletes a third party payment workflow definition defined for the site
# Get Checkout Settings
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/get-checkout-settings
/openapi/openapi_settings.json get /commerce/settings/checkout
Retrieves all checkout settings defined for the site: Payment settings, such as the payment gateway ID and credentials,supported credit cards,Customer Checkout settings whether login is required and any custom attributes; and Order Processing settings, such as when payment is authorized and captured, and any custom attributes.
# Get Customer Checkout Settings
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/get-customer-checkout-settings
/openapi/openapi_settings.json get /commerce/settings/checkout/customercheckoutsettings
Retrieves existing customer checkout settings including the checkout type, which determines whether the customer must be logged in when placing an order. Also lists any custom customer checkout attributes.
# Get Third Party Payment Workflow With Values
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/get-third-party-payment-workflow-with-values
/openapi/openapi_settings.json get /commerce/settings/checkout/paymentsettings/thirdpartyworkflow/{fullyQualifiedName}
Gets a third party payment workflow specified by workflow definition. A third-party payment workflow is a definition of a process by which a third-party payment provider (such as Amazon Payments or PayPal Express) interacts with the Unified eCommerce platform.
# Get Third Party Payment Workflows
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/get-third-party-payment-workflows
/openapi/openapi_settings.json get /commerce/settings/checkout/paymentsettings/thirdpartyworkflows
Retrieves list of external payment workflow definitions. A third-party payment workflow is a definition of a process by which a third-party payment provider (such as Amazon Payments or PayPal Express) interacts with the Unified eCommerce platform.
# Update Customer Checkout Settings
Source: https://docs.kibocommerce.com/api-reference/checkoutsettings/update-customer-checkout-settings
/openapi/openapi_settings.json put /commerce/settings/checkout/customercheckoutsettings
Modifies existing customer checkout settings. When a shopper starts the process of checking out,the Checkout Service checks these settings to render the checkout page.This is where you can specify whether shoppers must be logged in 'LoginRequired' or not 'LoginOptional' to checkout. You can also update your own customer checkout requirements, for example, to add a tracking code.
# Add Coupon Set
Source: https://docs.kibocommerce.com/api-reference/couponsets/add-coupon-set
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/couponsets
Adds a single CouponSet
# Add Coupons
Source: https://docs.kibocommerce.com/api-reference/couponsets/add-coupons
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/couponsets/{couponSetCode}/couponcodes
Adds coupon codes to a coupon set.
# Assign Discount to Coupon Set
Source: https://docs.kibocommerce.com/api-reference/couponsets/assign-discount-to-coupon-set
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/couponsets/{couponSetCode}/assigneddiscounts
Assigns or associates an existing discount to a specified coupon set. Use the couponSetCode parameter to specify the coupon set.
# Delete Coupon
Source: https://docs.kibocommerce.com/api-reference/couponsets/delete-coupon
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/couponsets/{couponSetCode}/couponcodes/{couponCode}
Deletes a single coupon by its coupon code.
# Delete Coupon Set
Source: https://docs.kibocommerce.com/api-reference/couponsets/delete-coupon-set
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/couponsets/{couponSetCode}
Deletes a CouponSet.
# Delete Coupons
Source: https://docs.kibocommerce.com/api-reference/couponsets/delete-coupons
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/couponsets/{couponSetCode}/couponcodes/remove
Deletes coupons from a coupon set.
# Get Assigned Discounts
Source: https://docs.kibocommerce.com/api-reference/couponsets/get-assigned-discounts
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/couponsets/{couponSetCode}/assigneddiscounts
Retrieves the discountIds of any assigned discounts for the specified coupon set.
# Get Coupon
Source: https://docs.kibocommerce.com/api-reference/couponsets/get-coupon
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/couponsets/{couponSetCode}/couponcodes/{couponCode}
Retrieves a single coupon by its coupon code.
# Get Coupon Set
Source: https://docs.kibocommerce.com/api-reference/couponsets/get-coupon-set
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/couponsets/{couponSetCode}
Returns a single CouponSet
# Get Coupon Sets
Source: https://docs.kibocommerce.com/api-reference/couponsets/get-coupon-sets
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/couponsets
Returns a paged collection of CouponSets
# Get Coupons
Source: https://docs.kibocommerce.com/api-reference/couponsets/get-coupons
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/couponsets/{couponSetCode}/couponcodes
Returns a paged collection of Coupons.
# Get Unique Coupon Set Code
Source: https://docs.kibocommerce.com/api-reference/couponsets/get-unique-coupon-set-code
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/couponsets/unique-code
Returns a random 4 character code that is unique as a coupon set code.
# Unassign Discount from Coupon Set
Source: https://docs.kibocommerce.com/api-reference/couponsets/unassign-discount-from-coupon-set
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/couponsets/{couponSetCode}/assigneddiscounts/{discountId}
Unassigns or disassociates the specified discount with the specified coupon set.
# Update Coupon Set
Source: https://docs.kibocommerce.com/api-reference/couponsets/update-coupon-set
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/couponsets/{couponSetCode}
Update a CouponSet. You can not update the Code or ID once the set is created.
# Validate Unique Coupon Set Code
Source: https://docs.kibocommerce.com/api-reference/couponsets/validate-unique-coupon-set-code
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/couponsets/validate-unique-code
Tests a coupone set code for uniqueness and validity.
# Add Credit
Source: https://docs.kibocommerce.com/api-reference/credit/add-credit
/openapi/openapi_customer.json post /commerce/customer/credits
Adds credit to user account. Store credit can represent a static amount the customer can redeem at any of the tenant's sites, or a gift card registered for a customer account.
# Add Transaction
Source: https://docs.kibocommerce.com/api-reference/credit/add-transaction
/openapi/openapi_customer.json post /commerce/customer/credits/{code}/transactions
Adds a credit transaction.
# Associate Credit To Shopper
Source: https://docs.kibocommerce.com/api-reference/credit/associate-credit-to-shopper
/openapi/openapi_customer.json put /commerce/customer/credits/{code}/associate-to-shopper
Maps credit to the shopper.
# Delete credit
Source: https://docs.kibocommerce.com/api-reference/credit/delete-credit
/openapi/openapi_customer.json delete /commerce/customer/credits/{code}
Deletes a credit.
# Get Audit Entries
Source: https://docs.kibocommerce.com/api-reference/credit/get-audit-entries
/openapi/openapi_customer.json get /commerce/customer/credits/{code}/auditentries
Retrieves a list of audit entries according to any filter criteria and sort options.
# Get credit
Source: https://docs.kibocommerce.com/api-reference/credit/get-credit
/openapi/openapi_customer.json get /commerce/customer/credits/{code}
Get credit specified by code.
# Get Credits
Source: https://docs.kibocommerce.com/api-reference/credit/get-credits
/openapi/openapi_customer.json get /commerce/customer/credits
Retrieves a list of credit collection according to any filter criteria and sort options.
# Get Transactions
Source: https://docs.kibocommerce.com/api-reference/credit/get-transactions
/openapi/openapi_customer.json get /commerce/customer/credits/{code}/transactions
Gets credit transactions according to any filter criteria and sort options.
# Resend Credit Created Email
Source: https://docs.kibocommerce.com/api-reference/credit/resend-credit-created-email
/openapi/openapi_customer.json put /commerce/customer/credits/{code}/Resend-Email
Resend email when credit is created.
# Update Credit
Source: https://docs.kibocommerce.com/api-reference/credit/update-credit
/openapi/openapi_customer.json put /commerce/customer/credits/{code}
Updates a credit specified by a credit code.
# Get Exchange Rates
Source: https://docs.kibocommerce.com/api-reference/currencies/get-exchange-rates
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/currencies/exchangerates
Retrieves a list of currency exchange rates based on the context's currency code.
# Add Currency Localization
Source: https://docs.kibocommerce.com/api-reference/currency/add-currency-localization
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/currency
Adds a new currency localization.
# Bulk Update Currency Exchange Rates
Source: https://docs.kibocommerce.com/api-reference/currency/bulk-update-currency-exchange-rates
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/currency/{currencyCode}/exchangerates
Update multiple exchange rates for a specified currency code.
# Delete Currency Exchange Rate
Source: https://docs.kibocommerce.com/api-reference/currency/delete-currency-exchange-rate
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/currency/{currencyCode}/exchangerates/{toCurrencyCode}
Delete a single exchange rate for a specified currency code and target currency code.
# Delete Currency Localization
Source: https://docs.kibocommerce.com/api-reference/currency/delete-currency-localization
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/currency/{currencyCode}
Deletes the currency localization specified by its currency code.
# Get Currency Exchange Rate
Source: https://docs.kibocommerce.com/api-reference/currency/get-currency-exchange-rate
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/currency/{currencyCode}/exchangerates/{toCurrencyCode}
Retrieves a single exchange rate for a specified currency code and target currency code.
# Get Currency Exchange Rates
Source: https://docs.kibocommerce.com/api-reference/currency/get-currency-exchange-rates
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/currency/{currencyCode}/exchangerates
Retrieves a list of exchange rates for a specified currency code and filter criteria.
# Get Currency Localization
Source: https://docs.kibocommerce.com/api-reference/currency/get-currency-localization
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/currency/{currencyCode}
Gets a single currency localization.
# Get Currency Localizations
Source: https://docs.kibocommerce.com/api-reference/currency/get-currency-localizations
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/currency
Gets all currency localizations.
# Update Currency Exchange Rates
Source: https://docs.kibocommerce.com/api-reference/currency/update-currency-exchange-rates
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/currency/{currencyCode}/exchangerates
Updates the details of a currency localization.
# Update Currency Localization
Source: https://docs.kibocommerce.com/api-reference/currency/update-currency-localization
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/currency/{currencyCode}
Updates the details of a currency localization.
# Add Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account
/openapi/openapi_customer.json post /commerce/customer/accounts
Creates a new customer account.
# Add Account And Login
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account-and-login
/openapi/openapi_customer.json post /commerce/customer/accounts/Add-Account-And-Login
Adds a customer to the account.
# Add Account Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account-attribute
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/attributes
Adds a new account attribute.
# Add Account Card
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account-card
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/cards
Creates a card on the specific customer account.
# Add Account Contact
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account-contact
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/contacts
Creates a new CustomerContact for a customer account, for example, a new shipping address.
# Add Account Contact List
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account-contact-list
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}/contacts
Creates a new CustomerContacts for a customer account in bulk to support adding multiple contacts in a multi-ship scenario.
# Add Account Note
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-account-note
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/notes
Adds a new note to the specified customer account.
# Add Accounts
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-accounts
/openapi/openapi_customer.json post /commerce/customer/accounts/Bulk
Creates multiple new shopper accounts for a specified site. Allows you to create a number of new shopper accounts at one time.
# Add Login To Existing Customer
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-login-to-existing-customer
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/Create-Login
Creates a login for an existing customer and logs them in automatically.
# Add Transaction
Source: https://docs.kibocommerce.com/api-reference/customeraccount/add-transaction
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/transactions
Add a transaction on customer account.
# Change Password
Source: https://docs.kibocommerce.com/api-reference/customeraccount/change-password
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/Change-Password
Changes a shopper's password.
# Change Passwords
Source: https://docs.kibocommerce.com/api-reference/customeraccount/change-passwords
/openapi/openapi_customer.json post /commerce/customer/accounts/Change-Passwords
Changes a collection of shopper passwords
# Create Customer Purchase Order Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/create-customer-purchase-order-account
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/purchaseOrderAccount
Creates a customer's purchase order account.
# Create Purchase Order Transaction
Source: https://docs.kibocommerce.com/api-reference/customeraccount/create-purchase-order-transaction
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/PurchaseOrderTransaction
Creates a purchase order transaction log (for public api use).
# Delete Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/delete-account
/openapi/openapi_customer.json delete /commerce/customer/accounts/{accountId}
Deletes a customer account. A customer account cannot be deleted if any orders exist, past or present. To erase a customer's personal data for a data subject erasure or right-to-deletion request under GDPR, CCPA, and other privacy regulations — including PII attached to existing orders, payments, and shipments — use the Redaction Services two-phase workflow instead.
# Delete Account Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccount/delete-account-attribute
/openapi/openapi_customer.json delete /commerce/customer/accounts/{accountId}/attributes/{attributeFQN}
Deletes an account attribute specified by attributeFQN.
# Delete Account Card
Source: https://docs.kibocommerce.com/api-reference/customeraccount/delete-account-card
/openapi/openapi_customer.json delete /commerce/customer/accounts/{accountId}/cards/{cardId}
Removes a card from the specified customer account.
# Delete Account Contact
Source: https://docs.kibocommerce.com/api-reference/customeraccount/delete-account-contact
/openapi/openapi_customer.json delete /commerce/customer/accounts/{accountId}/contacts/{contactId}
Deletes a CustomerContact for the specified customer account.
# Delete Account Note
Source: https://docs.kibocommerce.com/api-reference/customeraccount/delete-account-note
/openapi/openapi_customer.json delete /commerce/customer/accounts/{accountId}/notes/{noteId}
Removes a note from the specified customer account.
# Get Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}
Retrieves the details of a customer account specified by its unique identifier.
# Get Account Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-attribute
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/attributes/{attributeFQN}
Retrieves the contents of a particular attribute attached to a specified account.
# Get Account Attributes
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-attributes
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/attributes
Retrieves a collection of account attributes according to any specified filter criteria and sort options.
# Get Account Audit Log
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-audit-log
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/AuditLog/Entries
Get Account Audit Log
# Get Account Card
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-card
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/cards/{cardId}
Retrieves a card for the specified customer account and card ID.
# Get Account Cards
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-cards
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/cards
Retrieves a list of cards for the specified customer account.
# Get Account Contact
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-contact
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/contacts/{contactId}
Retrieves the specified CustomerContact for a customer account, for example, a billing or shipping CustomerContact.
# Get Account Contacts
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-contacts
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/contacts
Retrieves a list of contacts for a customer according to any specified filter criteria and sort options.
# Get Account Note
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-note
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/notes/{noteId}
Retrieves the contents of a particular note attached to a specified customer account.
# Get Account Notes
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-notes
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/notes
Retrieves a list of notes added to a customer account according to any specified filter criteria and sort options.
# Get Account Segments
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-account-segments
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/segments
Retrieves a list of segments for the specified account according to any specified filter criteria and sort options.
# Get Accounts
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-accounts
/openapi/openapi_customer.json get /commerce/customer/accounts
Retrieves a list of customer accounts according to any filter criteria and sort options.
# Get Customer Purchase Order Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-customer-purchase-order-account
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/purchaseOrderAccount
Gets a customer's purchase order account.
# Get Customer Purchase Order Transactions
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-customer-purchase-order-transactions
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/PurchaseOrderTransaction
Gets a collection of Purchase order transaction logs associated with a customer account id.
# Get Customers Purchase Order Accounts
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-customers-purchase-order-accounts
/openapi/openapi_customer.json post /commerce/customer/accounts/purchaseOrderAccounts
Gets a collection of customer purchase order accounts.
# Get Login State
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-login-state
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/loginstate
Retrieves the log-in status details of a shopper specified by account Id and user Id.
# Get Login State By Email Address
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-login-state-by-email-address
/openapi/openapi_customer.json post /commerce/customer/accounts/loginstatebyemailaddress
Retrieves the log-in status details of a shopper specified by emailAdress.
# Get Login State By UserName
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-login-state-by-username
/openapi/openapi_customer.json post /commerce/customer/accounts/loginstatebyusername
Retrieves the log-in status details of a shopper specified by userName.
# Get Transactions
Source: https://docs.kibocommerce.com/api-reference/customeraccount/get-transactions
/openapi/openapi_customer.json get /commerce/customer/accounts/{accountId}/transactions
Gets the list of transactions on customer account.
# Recompute Customer Lifetime Value
Source: https://docs.kibocommerce.com/api-reference/customeraccount/recompute-customer-lifetime-value
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/recomputelifetimevalue
Triggers event to recompute customer lifetime value. The lifetime value may not immediately be recalculated, but enters a queue.
# Remove Transaction
Source: https://docs.kibocommerce.com/api-reference/customeraccount/remove-transaction
/openapi/openapi_customer.json delete /commerce/customer/accounts/{accountId}/transactions/{transactionId}
Removes a transaction on customer account.
# Reset Password
Source: https://docs.kibocommerce.com/api-reference/customeraccount/reset-password
/openapi/openapi_customer.json post /commerce/customer/accounts/Reset-Password
Resets the password for a shopper specified by username or emailAddress.
# Retrieve Current Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/retrieve-current-account
/openapi/openapi_customer.json get /commerce/customer/accounts/current
Retrieves the details of a the current logged in customer account
# Set Login Locked
Source: https://docs.kibocommerce.com/api-reference/customeraccount/set-login-locked
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/Set-Login-Locked
Sets a flag indicating whether the customers login is locked or unlocked.
# Set Password Change Required
Source: https://docs.kibocommerce.com/api-reference/customeraccount/set-password-change-required
/openapi/openapi_customer.json post /commerce/customer/accounts/{accountId}/Set-Password-Change-Required
Sets a flag indicating whether the customers must change their password before logging in again.
# Update Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-account
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}
Modifies an existing customer account, for example, to change the primary billing contact or change whether to accept marketing material. ote that attempting to disable an account by using the below PUT call to change the isActive parameter is unsupported, and attempts to do so will be ignored by the API. Instead, make a POST call to api/commerce/customer/accounts/{accountId}/action and provide only { "actionName": "DisableAccount" } in the request body. This will successfully disable the account and the isActive flag will be automatically set as false.
# Update Account Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-account-attribute
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}/attributes/{attributeFQN}
Modifies an existing attribute for an account.
# Update Account Card
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-account-card
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}/cards/{cardId}
Updates a card on the specific customer account.
# Update Account Contact
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-account-contact
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}/contacts/{contactId}
Updates a CustomerContact for a specified customer account, for example to update addresses or change which CustomerContact is the primary CustomerContact for billing.
# Update Account Note
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-account-note
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}/notes/{noteId}
Modifies an existing note for a customer account.
# Update Customer Purchase Order Account
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-customer-purchase-order-account
/openapi/openapi_customer.json put /commerce/customer/accounts/{accountId}/purchaseOrderAccount
Updates a customer's purchase order account.
# Update Forgotten Password
Source: https://docs.kibocommerce.com/api-reference/customeraccount/update-forgotten-password
/openapi/openapi_customer.json post /commerce/customer/accounts/Update-Forgotten-Password
Updates the password for a shopper who has requested a password change and provided the new password and confirmation code.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccountattributedefinitions/create-attribute
/openapi/openapi_customer.json post /commerce/customer/accountattributedefinition/attributes
Create a new customer attribute.
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccountattributedefinitions/get-attribute
/openapi/openapi_customer.json get /commerce/customer/accountattributedefinition/attributes/{attributeFQN}
Get a customer attribute by its attributeFQN.
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/customeraccountattributedefinitions/get-attribute-vocabulary-values
/openapi/openapi_customer.json get /commerce/customer/accountattributedefinition/attributes/{attributeFQN}/VocabularyValues
Retrieves the details of attribute vocabulary values.
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/customeraccountattributedefinitions/get-attributes
/openapi/openapi_customer.json get /commerce/customer/accountattributedefinition/attributes
Retrieves the details of attributes.
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/customeraccountattributedefinitions/update-attribute
/openapi/openapi_customer.json put /commerce/customer/accountattributedefinition/attributes/{attributeFQN}
Update a customer attribute.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/customerattributedefinition/create-attribute
/openapi/openapi_customer.json post /commerce/customer/attributedefinition/attributes
Customer attributes are custom attributes that you can apply to customer accounts to add further definition for special uses, such as marketing campaigns, or discounts.
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/customerattributedefinition/get-attribute
/openapi/openapi_customer.json get /commerce/customer/attributedefinition/attributes/{attributeFQN}
Customer attributes are custom attributes that you can apply to customer accounts to add further definition for special uses, such as marketing campaigns, or discounts.
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/customerattributedefinition/get-attribute-vocabulary-values
/openapi/openapi_customer.json get /commerce/customer/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Retrieves the details of attribute vocabulary values.
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/customerattributedefinition/get-attributes
/openapi/openapi_customer.json get /commerce/customer/attributedefinition/attributes
Customer attributes are custom attributes that you can apply to customer accounts to add further definition for special uses, such as marketing campaigns, or discounts.
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/customerattributedefinition/update-attribute
/openapi/openapi_customer.json put /commerce/customer/attributedefinition/attributes/{attributeFQN}
Customer attributes are custom attributes that you can apply to customer accounts to add further definition for special uses, such as marketing campaigns, or discounts.
# Add Segments Accounts
Source: https://docs.kibocommerce.com/api-reference/customersegment/add-segments-accounts
/openapi/openapi_customer.json post /commerce/customer/segments/{id}/accounts
Adds segments to an account.
# Adds Segment
Source: https://docs.kibocommerce.com/api-reference/customersegment/adds-segment
/openapi/openapi_customer.json post /commerce/customer/segments
Creates a new segment. Merchants create segments of customers, for example,
to offer discounts to particular groups or assign VIP status to a set of customers.
# Delete Segment
Source: https://docs.kibocommerce.com/api-reference/customersegment/delete-segment
/openapi/openapi_customer.json delete /commerce/customer/segments/{id}
Deletes a segement specified by its unique code. Note that the group is deleted in all accounts that contain this segment.
# Get Segment
Source: https://docs.kibocommerce.com/api-reference/customersegment/get-segment
/openapi/openapi_customer.json get /commerce/customer/segments/{id}
Retrieves a segment specified the segment Id.
# Get Segments
Source: https://docs.kibocommerce.com/api-reference/customersegment/get-segments
/openapi/openapi_customer.json get /commerce/customer/segments
Retrieves a list of all segments defined for the site according to any specified filter criteria and sort options.
# Remove Segment Account
Source: https://docs.kibocommerce.com/api-reference/customersegment/remove-segment-account
/openapi/openapi_customer.json delete /commerce/customer/segments/{id}/accounts/{accountId}
Removes single account from a segment.
# Update Segment
Source: https://docs.kibocommerce.com/api-reference/customersegment/update-segment
/openapi/openapi_customer.json put /commerce/customer/segments/{id}
Update the code, name, or description of an existing segment.
# Get Customer Set
Source: https://docs.kibocommerce.com/api-reference/customerset/get-customer-set
/openapi/openapi_customer.json get /commerce/customer/customerSets/{code}
Retrieves the name of a customer group specified the customer group ID.
# Get Customer Sets
Source: https://docs.kibocommerce.com/api-reference/customerset/get-customer-sets
/openapi/openapi_customer.json get /commerce/customer/customerSets
Retrieves a list of all customerSets defined for the site according to any specified filter criteria and sort options.
# Create Survey
Source: https://docs.kibocommerce.com/api-reference/customersurvey/create-survey
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/surveys
Create a customer survey for a shipment.
# Get Customer Survey
Source: https://docs.kibocommerce.com/api-reference/customersurvey/get-customer-survey
/openapi/openapi_fulfillment.json get /commerce/shipments/surveys/{id}
Get a specific customer survey by ID.
# Get Surveys
Source: https://docs.kibocommerce.com/api-reference/customersurvey/get-surveys
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/surveys
Get the customer surveys of a shipment.
# Add Visit
Source: https://docs.kibocommerce.com/api-reference/customervisit/add-visit
/openapi/openapi_customer.json post /commerce/customer/visits
Adds visit info on the customer.
# Get Visit
Source: https://docs.kibocommerce.com/api-reference/customervisit/get-visit
/openapi/openapi_customer.json get /commerce/customer/visits/{visitId}
Gets visit info specified by visit Id.
# Get Visits
Source: https://docs.kibocommerce.com/api-reference/customervisit/get-visits
/openapi/openapi_customer.json get /commerce/customer/visits
Gets a collection of visit info specified by filter and sort order.
# Updates Visit
Source: https://docs.kibocommerce.com/api-reference/customervisit/updates-visit
/openapi/openapi_customer.json put /commerce/customer/visits/{visitId}
Updates an existing visit on the customer.
# Create Developer User Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/developeradminauthticket/create-developer-user-auth-ticket
/openapi/openapi_user.json post /platform/developer/authtickets
Authenticates a user for a particular tenant given a set of user credentials adn a tenantId.
# Delete User Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/developeradminauthticket/delete-user-auth-ticket
/openapi/openapi_user.json delete /platform/developer/authtickets
Logs out a user by deleting the refresh token
# Refresh Developer Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/developeradminauthticket/refresh-developer-auth-ticket
/openapi/openapi_user.json put /platform/developer/authtickets
Reauthenticates the current user for a different tenant. If the user does not have access to the tenant, the operation fails.
# Create Discount
Source: https://docs.kibocommerce.com/api-reference/discounts/create-discount
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/discounts
Creates a discount. This current version of the Discounts API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access discount data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Discount
Source: https://docs.kibocommerce.com/api-reference/discounts/delete-discount
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/discounts/{discountId}
Deletes a discount specified by its discount ID.
# Generate Random Coupon
Source: https://docs.kibocommerce.com/api-reference/discounts/generate-random-coupon
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discounts/generate-random-coupon
Generates a random code for a coupon.
# Get Auto Add Target
Source: https://docs.kibocommerce.com/api-reference/discounts/get-auto-add-target
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/autoaddtarget/{discountId}
Retrieves the auto add target for the specified discountId.
# Get Discount
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discounts/{discountId}
Retrieves the details of a single discount. This current version of the Discounts API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access discount data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Discount by Code
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount-by-code
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/code/{code}
Retrieves a discount by discount code.
# Get Discount by Coupon Code
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount-by-coupon-code
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/couponCode/{couponCode}
Retrieves a discount by coupon code.
# Get Discount by ID
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount-by-id
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/id/{id}
Retrieves a discount by discountId.
# Get Discount Content
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount-content
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discounts/{discountId}/content
Retrieves the localized content specified for the specified discount.
# Get Discount Tags
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount-tags
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discounts/{discountId}/tags
Retrieves all tags associated to a discount
# Get Discount Target
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discount-target
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discounts/{discountId}/target
Retrieves the discount target, that is which products, categories, or shipping methods are eligible for the discount.
# Get Discounts
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discounts
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discounts
Retrieves a list of discounts according to any specified filter criteria and sort options. This current version of the Discounts API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access discount data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Discounts by Label
Source: https://docs.kibocommerce.com/api-reference/discounts/get-discounts-by-label
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/label/{label}
Retrieves a list of discounts by label.
# Get Item Discounts
Source: https://docs.kibocommerce.com/api-reference/discounts/get-item-discounts
/openapi/openapi_pricing.json post /commerce/catalog/storefront/discounts/products
Retrieves a list of discounts that appear on the storefront according to specified filter criteria.
# Get Item Discounts by Product
Source: https://docs.kibocommerce.com/api-reference/discounts/get-item-discounts-by-product
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/products/{productCode}
Retrieves a list of discounts that appear on the storefront according to specified filter criteria.
# Get Order Level Discounts
Source: https://docs.kibocommerce.com/api-reference/discounts/get-order-level-discounts
/openapi/openapi_pricing.json post /commerce/catalog/storefront/discounts/orders
Retrieves a list of order level discounts that appear on the storefront according to specified filter criteria.
# Get Secure Discount by Code
Source: https://docs.kibocommerce.com/api-reference/discounts/get-secure-discount-by-code
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/secure/code/{code}
Retrieves a non-public discount by discount code. These can only be accessed by users with the Discount Read behavior.
# Get Secure Discount by Coupon Code
Source: https://docs.kibocommerce.com/api-reference/discounts/get-secure-discount-by-coupon-code
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/secure/couponCode/{couponCode}
Retrieves a non-public discount by coupon code. These can only be accessed by users with the Discount Read behavior.
# Get Secure Discount by ID
Source: https://docs.kibocommerce.com/api-reference/discounts/get-secure-discount-by-id
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/secure/id/{id}
Retrieves a non-public discount by discountId. These can only be accessed by users with the Discount Read behavior.
# Get Secure Discounts by Label
Source: https://docs.kibocommerce.com/api-reference/discounts/get-secure-discounts-by-label
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/secure/label/{label}
Retrieves non-public discounts by label. These can only be accessed by users with the Discount Read behavior.
# Update Discount
Source: https://docs.kibocommerce.com/api-reference/discounts/update-discount
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/discounts/{discountId}
Modifies a discount. This current version of the Discounts API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access discount data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Discount Content
Source: https://docs.kibocommerce.com/api-reference/discounts/update-discount-content
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/discounts/{discountId}/content
Modifies the localized content for the specified discount. Allows you to rename the discount without modifying any other discount properties.
# Update Discount Tags
Source: https://docs.kibocommerce.com/api-reference/discounts/update-discount-tags
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/discounts/tags
Modifies tags of the discount. The original tags are overwritten.
# Update Discount Target
Source: https://docs.kibocommerce.com/api-reference/discounts/update-discount-target
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/discounts/{discountId}/target
Modifies properties of the discount target, for example, the dollar amount, or percentage off the price.
# Validate Discount Expression
Source: https://docs.kibocommerce.com/api-reference/discounts/validate-discount-expression
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/discounts/expressions/validate
Validate a discount expression.
# Get Discount Settings
Source: https://docs.kibocommerce.com/api-reference/discountsettings/get-discount-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/discountsettings/{catalogId}
Retrieves the discount settings of a particular catalog.
# Update Discount Settings
Source: https://docs.kibocommerce.com/api-reference/discountsettings/update-discount-settings
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/discountsettings/{catalogId}
Updates the discount settings of a particular catalog.
# List Reservation Disruptions
Source: https://docs.kibocommerce.com/api-reference/disruptionevents/list-reservation-disruptions
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/disruptions/reservations
List Reservation Disruptions
# List Run Events
Source: https://docs.kibocommerce.com/api-reference/disruptionevents/list-run-events
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/runs/{runId}/events
List Run Events
# List Shipment Disruptions
Source: https://docs.kibocommerce.com/api-reference/disruptionevents/list-shipment-disruptions
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/disruptions/shipments
List Shipment Disruptions
# Create DocumentList
Source: https://docs.kibocommerce.com/api-reference/documentlist/create-documentlist
/openapi/openapi_content.json post /content/documentlists
Create DocumentList
# Delete Document List
Source: https://docs.kibocommerce.com/api-reference/documentlist/delete-document-list
/openapi/openapi_content.json delete /content/documentlists/{documentListName}
Delete Document List
# Get Document List
Source: https://docs.kibocommerce.com/api-reference/documentlist/get-document-list
/openapi/openapi_content.json get /content/documentlists/{documentListName}
Get Document List. The document list can only be accessed if the API context is inclusive of the document list's scope. A document list always belongs to a tenant context, denoted by the scopeType and scopeId fields. For example, if a list belongs to Catalog 123 then it is denoted by scopeType=catalog and scopeId=123.
# Get Document Lists
Source: https://docs.kibocommerce.com/api-reference/documentlist/get-document-lists
/openapi/openapi_content.json get /content/documentlists
Retrieve a paged documentListName of all document lists
# Update Document List
Source: https://docs.kibocommerce.com/api-reference/documentlist/update-document-list
/openapi/openapi_content.json put /content/documentlists/{documentListName}
Update Document List. The document list can only be accessed if the API context is inclusive of the document list's scope. A document list always belongs to a tenant context, denoted by the scopeType and scopeId fields. For example, if a list belongs to Catalog 123 then it is denoted by scopeType=catalog and scopeId=123.
# Create Document List Type
Source: https://docs.kibocommerce.com/api-reference/documentlisttype/create-document-list-type
/openapi/openapi_content.json post /content/documentlistTypes
Create Document List Type. Creating a new documentListType will tell the Content service to immediately create a document list of the new type within the set scopeType. For instance, a scopeType of "site" will create a list in each site for the tenant. Any defaultDocuments defined for the type will be created within each list, which will be addressable via the type's fully qualified name (FQN) and will use the type's defined views, usages, and metadata by default.
# Get Document List Type
Source: https://docs.kibocommerce.com/api-reference/documentlisttype/get-document-list-type
/openapi/openapi_content.json get /content/documentlistTypes/{documentListTypeFQN}
Get Document List Type
# Get Document List Types
Source: https://docs.kibocommerce.com/api-reference/documentlisttype/get-document-list-types
/openapi/openapi_content.json get /content/documentlistTypes
Get Document List Types. The list type denotes a content type for that list of folders, sub-folders, and documents. The immutable document list types that are defined out-of-the-box are pages, siteSnippets, files, siteSettings, catalogContent, pageTemplateContent, emailTemplateContent, and entityEditors.
# Update Document List Type
Source: https://docs.kibocommerce.com/api-reference/documentlisttype/update-document-list-type
/openapi/openapi_content.json put /content/documentlistTypes/{documentListTypeFQN}
Update Document List Type
# Create Property Type
Source: https://docs.kibocommerce.com/api-reference/documentpropertytype/create-property-type
/openapi/openapi_content.json post /content/propertytypes
Create Property Type. The immutable property types that are defined out-of-the-box are hidden, page_type_definition, string, int, dropzones, boolean, and datetime.
# Delete Property Type
Source: https://docs.kibocommerce.com/api-reference/documentpropertytype/delete-property-type
/openapi/openapi_content.json delete /content/propertytypes/{propertyTypeName}
Delete Property Type
# Get Property Type
Source: https://docs.kibocommerce.com/api-reference/documentpropertytype/get-property-type
/openapi/openapi_content.json get /content/propertytypes/{propertyTypeName}
Get Property Type
# Get Property Types
Source: https://docs.kibocommerce.com/api-reference/documentpropertytype/get-property-types
/openapi/openapi_content.json get /content/propertytypes
Retrieves a PagedCollection of PropertyTypes
# Update Property Type
Source: https://docs.kibocommerce.com/api-reference/documentpropertytype/update-property-type
/openapi/openapi_content.json put /content/propertytypes/{propertyTypeName}
Update Property Type
# Delete Document Drafts
Source: https://docs.kibocommerce.com/api-reference/documentpublishing/delete-document-drafts
/openapi/openapi_content.json post /content/documentpublishing/draft
Remove draft of each Document associated with te id in documentIds. Send empty body to remove all drafts
# Get Document Draft Summaries
Source: https://docs.kibocommerce.com/api-reference/documentpublishing/get-document-draft-summaries
/openapi/openapi_content.json get /content/documentpublishing/draft
Get Document Draft Summaries
# Publish Documents
Source: https://docs.kibocommerce.com/api-reference/documentpublishing/publish-documents
/openapi/openapi_content.json put /content/documentpublishing/active
Publishes draft of each Document associated with the id in documentIds. Send empty body to publish all drafts
# Add Publish Set Items
Source: https://docs.kibocommerce.com/api-reference/documentpublishset/add-publish-set-items
/openapi/openapi_content.json put /content/publishsets/{code}/items
Adds a set of documents by id to a publish set.
# Delete Publish Set
Source: https://docs.kibocommerce.com/api-reference/documentpublishset/delete-publish-set
/openapi/openapi_content.json post /content/publishsets/{code}
Adds a set of documents by id to a publish set.
# Get Publish Set
Source: https://docs.kibocommerce.com/api-reference/documentpublishset/get-publish-set
/openapi/openapi_content.json get /content/publishsets
Returns a List of current Publishing sets with counts of drafts in each.
# Get Publish Set Items
Source: https://docs.kibocommerce.com/api-reference/documentpublishset/get-publish-set-items
/openapi/openapi_content.json get /content/publishsets/{code}/items
Retrieve a paged collection of publish set Items.
# Copy Document
Source: https://docs.kibocommerce.com/api-reference/documents/copy-document
/openapi/openapi_content.json put /content/documentlists/{documentListName}/documents/copy
Copy Document
# Create Document
Source: https://docs.kibocommerce.com/api-reference/documents/create-document
/openapi/openapi_content.json post /content/documentlists/{documentListName}/documents
Create Document. However, if you are creating an empty folder in the files list then you only need to provide the name, documentTypeFQN, and listFQN fields - replace the name value with the full path of your folder.
# Delete Document
Source: https://docs.kibocommerce.com/api-reference/documents/delete-document
/openapi/openapi_content.json delete /content/documentlists/{documentListName}/documents/{documentId}
Delete Document
# Delete Document Content
Source: https://docs.kibocommerce.com/api-reference/documents/delete-document-content
/openapi/openapi_content.json delete /content/documentlists/{documentListName}/documents/{documentId}/content
Delete Document Content
# Delete Document Content by Path
Source: https://docs.kibocommerce.com/api-reference/documents/delete-document-content-by-path
/openapi/openapi_content.json delete /content/documentlists/{documentListName}/documentTree/{documentName}/content
Delete Document Content by Path
# Delete Documents
Source: https://docs.kibocommerce.com/api-reference/documents/delete-documents
/openapi/openapi_content.json delete /content/documentlists/{documentListName}/documents
Delete Documents
# Get Document
Source: https://docs.kibocommerce.com/api-reference/documents/get-document
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documents/{documentId}
Get Document
# Get Document by Path
Source: https://docs.kibocommerce.com/api-reference/documents/get-document-by-path
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documentTree/{documentName}
Retrieves a specific Document within the specified ContentCollection using the specified document name, unique within a specific folder with the specified documentId, version, and status.
# Get Document Content
Source: https://docs.kibocommerce.com/api-reference/documents/get-document-content
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documents/{documentId}/content
Get Document Content
# Get Document Content by Path
Source: https://docs.kibocommerce.com/api-reference/documents/get-document-content-by-path
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documentTree/{documentName}/content
Returns transformations on a document. For example, resizing an image.
# Get Document Content Headers
Source: https://docs.kibocommerce.com/api-reference/documents/get-document-content-headers
/openapi/openapi_content.json head /content/documentlists/{documentListName}/documents/{documentId}/content
Get Document Content Headers
# Get Document Content Headers by Path
Source: https://docs.kibocommerce.com/api-reference/documents/get-document-content-headers-by-path
/openapi/openapi_content.json head /content/documentlists/{documentListName}/documentTree/{documentName}/content
Get Document Content Headers by Path
# Get Documents
Source: https://docs.kibocommerce.com/api-reference/documents/get-documents
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documents
Get Documents. To search documents along a particular path, use the filter path such as in "folder1\folder2\". If no path is provided, then the query will be a global search as it searches from the root of the tree hierarchy.
# Get Resized Image
Source: https://docs.kibocommerce.com/api-reference/documents/get-resized-image
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documents/{documentId}/transform
Returns transformations on a document. For example, resizing an image.
# Get Resized Image by Path
Source: https://docs.kibocommerce.com/api-reference/documents/get-resized-image-by-path
/openapi/openapi_content.json get /content/documentlists/{documentListName}/documentTree/{documentName}/transform
Returns transformations on a document. For example, resizing an image. By Path
# Move Document
Source: https://docs.kibocommerce.com/api-reference/documents/move-document
/openapi/openapi_content.json put /content/documentlists/{documentListName}/documents/move
Move Document. This updates the path on all documents within a given source path to a new destination path, such as when moving documents between folders. Individual document moves should be made through the UpdateDocument operation instead.
# Patch Document
Source: https://docs.kibocommerce.com/api-reference/documents/patch-document
/openapi/openapi_content.json patch /content/documentlists/{documentListName}/documents/{documentId}
Patch Document
# Update Document
Source: https://docs.kibocommerce.com/api-reference/documents/update-document
/openapi/openapi_content.json put /content/documentlists/{documentListName}/documents/{documentId}
Update Document
# Update Document Content
Source: https://docs.kibocommerce.com/api-reference/documents/update-document-content
/openapi/openapi_content.json put /content/documentlists/{documentListName}/documents/{documentId}/content
Update Document Content
# Update Document Content by Path
Source: https://docs.kibocommerce.com/api-reference/documents/update-document-content-by-path
/openapi/openapi_content.json put /content/documentlists/{documentListName}/documentTree/{documentName}/content
Update Document Content by Path
# Create Document Type
Source: https://docs.kibocommerce.com/api-reference/documenttype/create-document-type
/openapi/openapi_content.json post /content/documenttypes
Create Document Type. All documents have a Document Type that describes the schema that the document must implement and its associated metadata, and is validated whenever a document is created or modified. The immutable types defined out-of-the-box are web_page, entityEditor, document, image, snippets, productContent, categoryContent, pageTemplateContent, emailTemplateContent, and folder.
# Get Document Type
Source: https://docs.kibocommerce.com/api-reference/documenttype/get-document-type
/openapi/openapi_content.json get /content/documenttypes/{documentTypeName}
Get Document Type
# Get Document Types
Source: https://docs.kibocommerce.com/api-reference/documenttype/get-document-types
/openapi/openapi_content.json get /content/documenttypes
Get Document Types. All documents have a Document Type that describes the schema that the document must implement and its associated metadata, and is validated whenever a document is created or modified. The immutable types defined out-of-the-box are web_page, entityEditor, document, image, snippets, productContent, categoryContent, pageTemplateContent, emailTemplateContent, and folder.
# Update Document Type
Source: https://docs.kibocommerce.com/api-reference/documenttype/update-document-type
/openapi/openapi_content.json put /content/documenttypes/{documentTypeName}
Update Document Type
# Generates an EDI 810 Invoice for the specified shipment
Source: https://docs.kibocommerce.com/api-reference/dropship/generates-an-edi-810-invoice-for-the-specified-shipment
/openapi/openapi_dropship.json get /commerce/dropship/invoice/{shipmentNumber}
Generates an EDI 810 Invoice for the specified shipment
# Retrieve EDI 850 Purchase Order
Source: https://docs.kibocommerce.com/api-reference/dropship/retrieve-edi-850-purchase-order
/openapi/openapi_dropship.json get /commerce/dropship/purchaseorder/{shipmentNumber}
Generates an EDI 850 Purchase Order (returned as JSON) for the specified shipment, resolving the vendor, contracted pricing, and ship-to address from the shipment's fulfillment location. See the Dropship Developer Guide for the complete segment mapping, validation rules, and workflow.
# Translate Shipment
Source: https://docs.kibocommerce.com/api-reference/dropship/translate-shipment
/openapi/openapi_dropship.json get /commerce/dropship/translate/{shipmentNumber}
Translates a shipment into a lightweight response containing vendor SKU mappings and contracted pricing per item. See the Dropship Developer Guide for field details and behavior.
# Add Entity
Source: https://docs.kibocommerce.com/api-reference/entities/add-entity
/openapi/openapi_entities.json post /platform/entitylists/{entityListFullName}/entities
Insert an Entity into an EntityList instance
# Delete Entity
Source: https://docs.kibocommerce.com/api-reference/entities/delete-entity
/openapi/openapi_entities.json delete /platform/entitylists/{entityListFullName}/entities/{id}
Delete an existing Entity from an EntityList instance
# Get Entities
Source: https://docs.kibocommerce.com/api-reference/entities/get-entities
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/entities
Get a filtered collection of Entities from an EntityList instance
# Get Entity
Source: https://docs.kibocommerce.com/api-reference/entities/get-entity
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/entities/{id}
Get a specific Entity from an EntityList instance
# Get View Entities
Source: https://docs.kibocommerce.com/api-reference/entities/get-view-entities
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/views/{viewName}/entities
Get a filtered collection of Entities for a ListView on an EntityList
# Get View Entity
Source: https://docs.kibocommerce.com/api-reference/entities/get-view-entity
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/views/{viewName}/entities/{entityId}
Get a specific Entity in a ListView on an EntityList
# Update Entity
Source: https://docs.kibocommerce.com/api-reference/entities/update-entity
/openapi/openapi_entities.json put /platform/entitylists/{entityListFullName}/entities/{id}
Update an existing Entity in an EntityList instance
# Get Entity Container
Source: https://docs.kibocommerce.com/api-reference/entitycontainers/get-entity-container
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/entityContainers/{id}
Get a specific Entity Container from an EntityList instance
# Get Entity Containers
Source: https://docs.kibocommerce.com/api-reference/entitycontainers/get-entity-containers
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/entityContainers
Get a filtered collection of Entity Containers from an Entity List instance
# Get Entity View Container
Source: https://docs.kibocommerce.com/api-reference/entitycontainers/get-entity-view-container
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/views/{viewName}/entityContainers/{entityId}
Get an Entity Container for a specific Entity in a ListView on an EntityList
# Get Entity View Containers
Source: https://docs.kibocommerce.com/api-reference/entitycontainers/get-entity-view-containers
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/views/{viewName}/entityContainers
Get a filtered collection of Entity Containers for a ListView on an EntityList
# Add EntityList
Source: https://docs.kibocommerce.com/api-reference/entitylists/add-entitylist
/openapi/openapi_entities.json post /platform/entitylists
Create a new EntityList for a specific tenant.
# Delete EntityList
Source: https://docs.kibocommerce.com/api-reference/entitylists/delete-entitylist
/openapi/openapi_entities.json delete /platform/entitylists/{entityListFullName}
Delete an existing EntityList for a specific tenant. This will also delete all Entities in all instances of this EntityList for the tenant.
# Get EntityList
Source: https://docs.kibocommerce.com/api-reference/entitylists/get-entitylist
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}
Get an existing EntityList definition for a specific tenant
# Get EntityLists
Source: https://docs.kibocommerce.com/api-reference/entitylists/get-entitylists
/openapi/openapi_entities.json get /platform/entitylists
Get a filtered list of EntityLists for a specific tenant.
# Update Entitylist
Source: https://docs.kibocommerce.com/api-reference/entitylists/update-entitylist
/openapi/openapi_entities.json put /platform/entitylists/{entityListFullName}
Update an existing Entitylist for a specific tenant.
# Get Event
Source: https://docs.kibocommerce.com/api-reference/event/get-event
/openapi/openapi_event.json get /event/pull/{eventId}
Retrieves the details of a single event.
# Get Events
Source: https://docs.kibocommerce.com/api-reference/event/get-events
/openapi/openapi_event.json get /event/pull
Retrieves a list of events according to any specified filter criteria and sort options.
# Get Delivery Attempt Summaries
Source: https://docs.kibocommerce.com/api-reference/eventsubscription/get-delivery-attempt-summaries
/openapi/openapi_event.json get /event/push/subscriptions/{subscriptionId}/deliveryattempts
Get delivery attempts for the specified subscription
# Get Delivery Attempt Summaries All Subscriptions
Source: https://docs.kibocommerce.com/api-reference/eventsubscription/get-delivery-attempt-summaries-all-subscriptions
/openapi/openapi_event.json get /event/push/subscriptions/deliveryattempts
Get delivery attempts
# Get Delivery Attempt Summary
Source: https://docs.kibocommerce.com/api-reference/eventsubscription/get-delivery-attempt-summary
/openapi/openapi_event.json get /event/push/subscriptions/{subscriptionId}/deliveryattempts/{processId}
Get delivery attempt summary
# Get Subscriptions
Source: https://docs.kibocommerce.com/api-reference/eventsubscription/get-subscriptions
/openapi/openapi_event.json get /event/push/subscriptions
Retrieves a list of events according to any specified filter criteria and sort options.
# Create Export Job
Source: https://docs.kibocommerce.com/api-reference/export/create-export-job
/openapi/openapi_importexport.json post /platform/data/export
Creates a new export job. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Delete Export Job
Source: https://docs.kibocommerce.com/api-reference/export/delete-export-job
/openapi/openapi_importexport.json delete /platform/data/export/{id}
Deletes an existing export job. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Get Export Job
Source: https://docs.kibocommerce.com/api-reference/export/get-export-job
/openapi/openapi_importexport.json get /platform/data/export/{id}
Retrieves an export job by ID. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Get Export Jobs
Source: https://docs.kibocommerce.com/api-reference/export/get-export-jobs
/openapi/openapi_importexport.json get /platform/data/export
Retrieves a list of all export jobs. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Create Export Settings
Source: https://docs.kibocommerce.com/api-reference/exportinventory/create-export-settings
/openapi/openapi_inventory.json post /commerce/inventory/v1/export/create
Creates entirely new export configurations for both FTP and S3 settings. This call allows you to specify all the values for the Export Settings object, such as file type and specific location groups or sites (which cannot be edited through FTP- or S3-specific endpoints). This is the initial setup request required to configure inventory export.
# Create Export Settings FTP
Source: https://docs.kibocommerce.com/api-reference/exportinventory/create-export-settings-ftp
/openapi/openapi_inventory.json post /commerce/inventory/v1/export/ftp/create
Creates new FTP settings and adds them to an existing Export Settings object, which may be useful if you want the export to go to a new endpoint instead of the one originally set up (or if the export needs to go to multiple endpoints). This call will not function unless you have performed the initial Create Export Settings request first.
# Create Export Settings S3
Source: https://docs.kibocommerce.com/api-reference/exportinventory/create-export-settings-s3
/openapi/openapi_inventory.json post /commerce/inventory/v1/export/s3/create
Creates new S3 settings and adds them to an existing Export Settings object, which may be useful if you want the export to go to a new endpoint instead of the one originally set up (or if the export needs to go to multiple endpoints). This call will not function unless you have performed the initial Create Export Settings request first.
# Delete Export Settings
Source: https://docs.kibocommerce.com/api-reference/exportinventory/delete-export-settings
/openapi/openapi_inventory.json delete /commerce/inventory/v1/export/{exportSettingsName}
Deletes the entire Export Settings object, including any FTP or S3 configurations within it.
# Delete Export Settings FTP
Source: https://docs.kibocommerce.com/api-reference/exportinventory/delete-export-settings-ftp
/openapi/openapi_inventory.json delete /commerce/inventory/v1/export/ftp/{exportSettingsName}/{exportSettingsFTPName}
Deletes the specified FTP settings object. Not specifying the FTP Name/ID will delete all FTP settings within the Export Settings. This will not delete the entire Export Settings object.
# Delete Export Settings S3
Source: https://docs.kibocommerce.com/api-reference/exportinventory/delete-export-settings-s3
/openapi/openapi_inventory.json delete /commerce/inventory/v1/export/s3/{exportSettingsName}/{exportSettingsS3Name}
Deletes the specified S3 settings object. Not specifying the S3 Name/ID will delete all S3 settings within the Export Settings. This will not delete the entire Export Settings object.
# Get Export Settings
Source: https://docs.kibocommerce.com/api-reference/exportinventory/get-export-settings
/openapi/openapi_inventory.json get /commerce/inventory/v1/export
Get an export settings
# Run Export
Source: https://docs.kibocommerce.com/api-reference/exportinventory/run-export
/openapi/openapi_inventory.json post /commerce/inventory/v1/export
Run Export Settings Job
# Update Export Settings
Source: https://docs.kibocommerce.com/api-reference/exportinventory/update-export-settings
/openapi/openapi_inventory.json post /commerce/inventory/v1/export/update
Updates the entire Export Settings object, including FTP and S3 configurations as well as file type and specific location groups or sites (which cannot be edited through FTP- or S3-specific endpoints).
# Update Export Settings FTP
Source: https://docs.kibocommerce.com/api-reference/exportinventory/update-export-settings-ftp
/openapi/openapi_inventory.json post /commerce/inventory/v1/export/ftp/update
Updates the FTP settings within an existing Export Settings object.
# Update Export Settings S3
Source: https://docs.kibocommerce.com/api-reference/exportinventory/update-export-settings-s3
/openapi/openapi_inventory.json post /commerce/inventory/v1/export/s3/update
Updates the S3 settings within an existing Export Settings object. Note that you cannot update location groups or sites with this request - you must use the full Update Export Settings request instead.
# Add Facet
Source: https://docs.kibocommerce.com/api-reference/facets/add-facet
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/facets
Adds a new Facet to a category in a catalog.
# Delete Facet
Source: https://docs.kibocommerce.com/api-reference/facets/delete-facet
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/facets/{facetId}
Deletes the Facet definition from the store.
# Get Facet
Source: https://docs.kibocommerce.com/api-reference/facets/get-facet
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/facets/{facetId}
Retrieves the details of a Facet definition.
# Get Facet Category List
Source: https://docs.kibocommerce.com/api-reference/facets/get-facet-category-list
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/facets/category
Retrieves a list of configured, and optionally available, Facet configurations for the specified category.
# Get Facet Category List (Legacy)
Source: https://docs.kibocommerce.com/api-reference/facets/get-facet-category-list-legacy
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/facets/category/{categoryId}
Retrieves a list of configured, and optionally available, Facet configurations for the specified category.
# Get facets
Source: https://docs.kibocommerce.com/api-reference/facets/get-facets
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/facets
Retrieves the list of Facet Definition
# Update Facet
Source: https://docs.kibocommerce.com/api-reference/facets/update-facet
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/facets/{facetId}
Modifies a Facet definition.
# Update Facet Set
Source: https://docs.kibocommerce.com/api-reference/facets/update-facet-set
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/facets/set/edit
Modifies a Facet definition.
# Get Field Type Definitions
Source: https://docs.kibocommerce.com/api-reference/fieldtypedefinition/get-field-type-definitions
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/fieldTypes/{language}
Get Field Type Definitions
# Get File
Source: https://docs.kibocommerce.com/api-reference/filebasedpackage/get-file
/openapi/openapi_appdevelopement.json get /platform/appdev/filebasedpackage/packages/{applicationKey}
Retrieve an application package file.
# Download Files
Source: https://docs.kibocommerce.com/api-reference/files/download-files
/openapi/openapi_importexport.json get /platform/data/files/{id}/content
Downloads specific files by ID
# Get File
Source: https://docs.kibocommerce.com/api-reference/files/get-file
/openapi/openapi_importexport.json get /platform/data/files/{id}
Retrieves file information by ID
# Get Public Link
Source: https://docs.kibocommerce.com/api-reference/files/get-public-link
/openapi/openapi_importexport.json post /platform/data/files/{id}/generatelink
Generates a public link for the files
# Upload Files
Source: https://docs.kibocommerce.com/api-reference/files/upload-files
/openapi/openapi_importexport.json post /platform/data/files
Uploads files to the system
# Get Features
Source: https://docs.kibocommerce.com/api-reference/fulfillment/get-features
/openapi/openapi_fulfillment.json get /commerce/fulfillment/features
Get Features
# Get Public Settings
Source: https://docs.kibocommerce.com/api-reference/fulfillment/get-public-settings
/openapi/openapi_fulfillment.json get /commerce/fulfillment/settings
Retrive the public fulfillment settings.
# Get Tenant Attributes
Source: https://docs.kibocommerce.com/api-reference/fulfillment/get-tenant-attributes
/openapi/openapi_fulfillment.json get /commerce/fulfillment/tenantAttributes
Get Tenant Attributes
# Create Fulfillment Settings
Source: https://docs.kibocommerce.com/api-reference/fulfillmentsettings/create-fulfillment-settings
/openapi/openapi_settings.json post /commerce/settings/fulfillment/fulfillmentsettings
Creates fulfillment settings for the site, which includes bpm settings, ship to store, back order days etc.
# Get Fulfillment Settings
Source: https://docs.kibocommerce.com/api-reference/fulfillmentsettings/get-fulfillment-settings
/openapi/openapi_settings.json get /commerce/settings/fulfillment/fulfillmentsettings
Retrieves existing fulfillment settings defined on the site
# Update Fulfillment Settings
Source: https://docs.kibocommerce.com/api-reference/fulfillmentsettings/update-fulfillment-settings
/openapi/openapi_settings.json put /commerce/settings/fulfillment/fulfillmentsettings
Modifies existing fulfillment settings for the site, which includes bpm settings, ship to store, back order days etc.
# Create Future Shipment for Items
Source: https://docs.kibocommerce.com/api-reference/futureshipment/create-future-shipment-for-items
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/futureItems
Create a future shipment for future items.
# Create Future Shipments For Future Allocatable Items
Source: https://docs.kibocommerce.com/api-reference/futureshipment/create-future-shipments-for-future-allocatable-items
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/futureAllocatableItems
Create Future Shipments For Future Allocatable Items
# Future Shipment To Ready
Source: https://docs.kibocommerce.com/api-reference/futureshipment/future-shipment-to-ready
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/futureToReady
Move a Future shipment to Ready.
# Update Future Shipment Date
Source: https://docs.kibocommerce.com/api-reference/futureshipment/update-future-shipment-date
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/futureUpdateDate
Update a future shipment's expected date.
# Create future shipment rebalancing rule
Source: https://docs.kibocommerce.com/api-reference/futureshipmentrebalancingrules/create-future-shipment-rebalancing-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/futureshipmentrebalancing
Creates a new future shipment rebalancing rule.
# Delete future shipment rebalancing rule
Source: https://docs.kibocommerce.com/api-reference/futureshipmentrebalancingrules/delete-future-shipment-rebalancing-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/futureshipmentrebalancing/{code}
Deletes a future shipment rebalancing rule by code.
# Get future shipment rebalancing rule by code
Source: https://docs.kibocommerce.com/api-reference/futureshipmentrebalancingrules/get-future-shipment-rebalancing-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/futureshipmentrebalancing/{code}
Gets a future shipment rebalancing rule details by code.
# Get future shipment rebalancing rules
Source: https://docs.kibocommerce.com/api-reference/futureshipmentrebalancingrules/get-future-shipment-rebalancing-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/futureshipmentrebalancing
Gets a collection of future shipment rebalancing rules according to any specified filter criteria and sort options.
# Update future shipment rebalancing rule
Source: https://docs.kibocommerce.com/api-reference/futureshipmentrebalancingrules/update-future-shipment-rebalancing-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/futureshipmentrebalancing/{code}
Updates an existing future shipment rebalancing rule.
# Update future shipment rebalancing rule rank
Source: https://docs.kibocommerce.com/api-reference/futureshipmentrebalancingrules/update-future-shipment-rebalancing-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/futureshipmentrebalancing/{code}/rank
Updates the rank for a future shipment rebalancing rule and rearranges the ranks of all other rules accordingly.
# Adds Taxable Territory
Source: https://docs.kibocommerce.com/api-reference/generalsettings/adds-taxable-territory
/openapi/openapi_settings.json post /commerce/settings/general/taxableterritories
Creates taxble territories for the site.
# Create Custom Route Settings
Source: https://docs.kibocommerce.com/api-reference/generalsettings/create-custom-route-settings
/openapi/openapi_settings.json post /commerce/settings/general/customroutes
Creates a new custom route settings. Custom routing allows you to display SEO-friendly URLs on your site that map behind-the-scenes to resources such as a product page or a search results page. With custom routing, you gain advanced control over the URL structures on your site and can more visibly highlight the products or categories your shoppers are interested in purchasing.
# Delete Custom Route Settings
Source: https://docs.kibocommerce.com/api-reference/generalsettings/delete-custom-route-settings
/openapi/openapi_settings.json delete /commerce/settings/general/customroutes
Deletes custom route settings.
# Get Custom Route Settings
Source: https://docs.kibocommerce.com/api-reference/generalsettings/get-custom-route-settings
/openapi/openapi_settings.json get /commerce/settings/general/customroutes
Gets custom route settings. Custom routing allows you to display SEO-friendly URLs on your site that map behind-the-scenes to resources such as a product page or a search results page. With custom routing, you gain advanced control over the URL structures on your site and can more visibly highlight the products or categories your shoppers are interested in purchasing.
# Get General Settings
Source: https://docs.kibocommerce.com/api-reference/generalsettings/get-general-settings
/openapi/openapi_settings.json get /commerce/settings/general
Retrieves list of general settings for the site, which includes settings like theme, email, address validation etc.
# Get Taxable Territories
Source: https://docs.kibocommerce.com/api-reference/generalsettings/get-taxable-territories
/openapi/openapi_settings.json get /commerce/settings/general/taxableterritories
Retrieves list of taxble territories for the site.
# Update Custom Route Settings
Source: https://docs.kibocommerce.com/api-reference/generalsettings/update-custom-route-settings
/openapi/openapi_settings.json put /commerce/settings/general/customroutes
Updates custom route settings. Custom routing allows you to display SEO-friendly URLs on your site that map behind-the-scenes to resources such as a product page or a search results page. With custom routing, you gain advanced control over the URL structures on your site and can more visibly highlight the products or categories your shoppers are interested in purchasing.
# Update General Settings
Source: https://docs.kibocommerce.com/api-reference/generalsettings/update-general-settings
/openapi/openapi_settings.json put /commerce/settings/general
Updates general settings for the site, which includes settings like theme, email, address validation etc
# Update Taxable Territories
Source: https://docs.kibocommerce.com/api-reference/generalsettings/update-taxable-territories
/openapi/openapi_settings.json put /commerce/settings/general/taxableterritories
Updates taxble territories for the site.
# Item Gift Receipt Update
Source: https://docs.kibocommerce.com/api-reference/giftreceipt/item-gift-receipt-update
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/itemGiftReceipt
Item Gift Receipt Update
# Shipment Gift Receipt Update
Source: https://docs.kibocommerce.com/api-reference/giftreceipt/shipment-gift-receipt-update
/openapi/openapi_fulfillment.json put /commerce/shipments/{orderId}/shipmentGiftReceipt
Shipment Gift Receipt Update
# Get Application Build Jobs
Source: https://docs.kibocommerce.com/api-reference/headlessapp/get-application-build-jobs
/openapi/openapi_appdevelopement.json get /platform/appdev/headless-app/builds/{branchName}
Get the builds of a specific code branch for a Kibo Hosted Headless application.\r\nA Kibo site must be first linked to a headless hosted application before using this API.
# Get Application Build Log
Source: https://docs.kibocommerce.com/api-reference/headlessapp/get-application-build-log
/openapi/openapi_appdevelopement.json get /platform/appdev/headless-app/builds/{branchName}/logs/{jobId}
Get the build logs of a specifc code branch and build for a Kibo Hosted Headless application.\r\nA Kibo site must be first linked to a headless hosted application before using this API.
# Get Runtime Logs
Source: https://docs.kibocommerce.com/api-reference/headlessapp/get-runtime-logs
/openapi/openapi_appdevelopement.json get /platform/appdev/headless-app/logs/runtime
Get the runtime logs, as s3 objects, for a Kibo Hosted Headless application.
A Kibo site must be first linked to a headless hosted application before using this API.
# Download Histories
Source: https://docs.kibocommerce.com/api-reference/history/download-histories
/openapi/openapi_audit_logs.json get /history/{rightHistoryId}/{leftHistoryId}/download
Downloads the entities as a ZIP file by their history IDs.
# Download History
Source: https://docs.kibocommerce.com/api-reference/history/download-history
/openapi/openapi_audit_logs.json get /history/{historyId}/download
Downloads the entity as a JSON file by its history ID.
# Get History
Source: https://docs.kibocommerce.com/api-reference/history/get-history
/openapi/openapi_audit_logs.json get /history
Retrieves a collection of history records with optional paging parameters. Paging parameters include startIndex, pageSize, sortBy, filter, q, and qLimit.
# Get History by ID
Source: https://docs.kibocommerce.com/api-reference/history/get-history-by-id
/openapi/openapi_audit_logs.json get /history/{historyId}
Retrieves a history record by its ID.
# Get History Diff
Source: https://docs.kibocommerce.com/api-reference/history/get-history-diff
/openapi/openapi_audit_logs.json get /history/{historyId}/diff
Retrieves diff for history by ID or entity type. Retrieves the modified file(s) of given history compared to the previous. version of entity
# Create Import Job
Source: https://docs.kibocommerce.com/api-reference/import/create-import-job
/openapi/openapi_importexport.json post /platform/data/import
Creates a new import job. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Delete Import Job
Source: https://docs.kibocommerce.com/api-reference/import/delete-import-job
/openapi/openapi_importexport.json delete /platform/data/import/{id}
Deletes an existing import job. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Get Import Job
Source: https://docs.kibocommerce.com/api-reference/import/get-import-job
/openapi/openapi_importexport.json get /platform/data/import/{id}
Retrieves an import job by ID. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Get Import Jobs
Source: https://docs.kibocommerce.com/api-reference/import/get-import-jobs
/openapi/openapi_importexport.json get /platform/data/import
Retrieves a list of all import jobs. For detailed usage, file format specifications, and field references, see the [Import/Export API Overview](/pages/import-export-api-overview).
# Add In Stock Notification Subscription
Source: https://docs.kibocommerce.com/api-reference/instocknotificationsubscription/add-in-stock-notification-subscription
/openapi/openapi_customer.json post /commerce/instocknotifications
Creates a new notification subscription.
# Delete In Stock Notification Subscription
Source: https://docs.kibocommerce.com/api-reference/instocknotificationsubscription/delete-in-stock-notification-subscription
/openapi/openapi_customer.json delete /commerce/instocknotifications/{id}
Deletes an in stock notification subscription.
# Get In Stock Notification Subscription
Source: https://docs.kibocommerce.com/api-reference/instocknotificationsubscription/get-in-stock-notification-subscription
/openapi/openapi_customer.json get /commerce/instocknotifications/{id}
Retrieves the details of an inventory back in stock notification.
# Get In Stock Notification Subscriptions
Source: https://docs.kibocommerce.com/api-reference/instocknotificationsubscription/get-in-stock-notification-subscriptions
/openapi/openapi_customer.json get /commerce/instocknotifications
Retrieves a list of inventory back in stock notification subscriptions according to any filter criteria and sort options.
# Aggregate
Source: https://docs.kibocommerce.com/api-reference/inventory/aggregate
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/aggregate
Aggregates inventory.
# Get Inventory (POST)
Source: https://docs.kibocommerce.com/api-reference/inventory/get-inventory-post
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory
Queries for specified inventory at given location. To call the version of this API with RIS (real-time inventory service) data, use the /commerce/realtime-inventory/v5/inventory endpoint instead.
# Allocate Inventory
Source: https://docs.kibocommerce.com/api-reference/inventoryallocation/allocate-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/allocate
Allocates inventory based on the given request
# Deallocate Inventory
Source: https://docs.kibocommerce.com/api-reference/inventoryallocation/deallocate-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/deallocate
As the Refresh Inventory call does not clear allocated inventory, you can use this Deallocate Inventory call if you have items stuck in "Allocated" status. This requires details about the shipment and which specific line items need to be deallocated. For examples on how to find shipments with allocated inventory and perform a deallocation on them, see the Inventory API guide.
# Fulfill Inventory
Source: https://docs.kibocommerce.com/api-reference/inventoryallocation/fulfill-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/fulfill
Fulfills inventory based on the given request
# Transition Cart
Source: https://docs.kibocommerce.com/api-reference/inventoryallocation/transition-cart
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/transitionCart
Transitions a cart allocation into a normal order/shipment allocation
# Update Inventory Allocation
Source: https://docs.kibocommerce.com/api-reference/inventoryallocation/update-inventory-allocation
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/items/{lineId}/updateInventoryAllocation
Update Inventory Allocation
# Create Bin
Source: https://docs.kibocommerce.com/api-reference/inventorybin/create-bin
/openapi/openapi_inventory.json post /commerce/inventory/v1/bin
Create a bin
# Get Bin Statuses
Source: https://docs.kibocommerce.com/api-reference/inventorybin/get-bin-statuses
/openapi/openapi_inventory.json get /commerce/inventory/v1/bin/binStatuses
Get list of bin statuses
# Get Bin Types
Source: https://docs.kibocommerce.com/api-reference/inventorybin/get-bin-types
/openapi/openapi_inventory.json get /commerce/inventory/v1/bin/binTypes
Get list of bin types
# Get Bins
Source: https://docs.kibocommerce.com/api-reference/inventorybin/get-bins
/openapi/openapi_inventory.json get /commerce/inventory/v1/bin
Get a list of bins
# Load Inventory
Source: https://docs.kibocommerce.com/api-reference/inventorybin/load-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v1/bin/loadInventory
Loads bin inventory for designated bins
# Search Bins
Source: https://docs.kibocommerce.com/api-reference/inventorybin/search-bins
/openapi/openapi_inventory.json post /commerce/inventory/v1/bin/searchInventory
Search bins for a inventory by bin name or any product identifier
# Update Bin
Source: https://docs.kibocommerce.com/api-reference/inventorybin/update-bin
/openapi/openapi_inventory.json post /commerce/inventory/v1/bin/{bin_id}
Update the designated bin
# Update Bins
Source: https://docs.kibocommerce.com/api-reference/inventorybin/update-bins
/openapi/openapi_inventory.json post /commerce/inventory/v1/bin/updateBins
Update the designated bins
# Block Assignment
Source: https://docs.kibocommerce.com/api-reference/inventoryblockassignment/block-assignment
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/blockAssignment
Setting the blockAssignment flag to true for the product based on the given request
# Delete Fetch Config
Source: https://docs.kibocommerce.com/api-reference/inventoryfetchfileconfig/delete-fetch-config
/openapi/openapi_inventory.json delete /commerce/inventory/v1/config/fetchfile/{fetchFileConfigID}
Deletes a fetch file configuration.
# Get Fetch Config
Source: https://docs.kibocommerce.com/api-reference/inventoryfetchfileconfig/get-fetch-config
/openapi/openapi_inventory.json get /commerce/inventory/v1/config/fetchfile
Get the Fetch File Configs for the current tenant
# Save Fetch Config
Source: https://docs.kibocommerce.com/api-reference/inventoryfetchfileconfig/save-fetch-config
/openapi/openapi_inventory.json post /commerce/inventory/v1/config/fetchfile
Save a new Fetch File Configuration.
# Test Connection
Source: https://docs.kibocommerce.com/api-reference/inventoryfetchfileconfig/test-connection
/openapi/openapi_inventory.json get /commerce/inventory/v1/config/fetchfile/testConnection/{fetchFileConfigID}
Attempts to connect to a fetch file endpoint and lists current files if successful
# Adjust Future Date
Source: https://docs.kibocommerce.com/api-reference/inventoryfuturedate/adjust-future-date
/openapi/openapi_inventory.json put /adjustFutureDate/{futureInventoryID}
Adjust future_date of future inventory
# Delete All Old Inventory
Source: https://docs.kibocommerce.com/api-reference/inventoryjob/delete-all-old-inventory
/openapi/openapi_inventory.json delete /commerce/inventory/v1/deleteOldInventory/allSilo/{months}
Deletes older records from inventory table of all silos
# Delete Old Inventory
Source: https://docs.kibocommerce.com/api-reference/inventoryjob/delete-old-inventory
/openapi/openapi_inventory.json delete /commerce/inventory/v1/deleteOldInventory/{months}
Deletes older records from inventory table
# Get Job
Source: https://docs.kibocommerce.com/api-reference/inventoryjob/get-job
/openapi/openapi_inventory.json get /commerce/inventory/v1/queue/{jobID}
Get the specified inventory job. Use this call to monitor the status of inventory upload, refresh, adjust, or deletion jobs. Once you have a job ID — returned by endpoints such as Delete Inventory, Delete Items, Refresh Inventory, or Adjust Inventory — continue polling this endpoint until the job reaches a terminal status (`SUCCESS` or `FAILED`). For polling patterns and monitoring guidance during bulk inventory deletions, see the Bulk Inventory Deletion guide.
# Get Jobs
Source: https://docs.kibocommerce.com/api-reference/inventoryjob/get-jobs
/openapi/openapi_inventory.json get /commerce/inventory/v1/queue
Get the requested jobs.
# Get Location
Source: https://docs.kibocommerce.com/api-reference/inventorylocation/get-location
/openapi/openapi_inventory.json get /commerce/inventory/v1/location/{locationCode}
Get Locations
# Get Location Groups
Source: https://docs.kibocommerce.com/api-reference/inventorylocation/get-location-groups
/openapi/openapi_inventory.json get /commerce/inventory/v1/location/{locationGroupCode}
Get LocationGroups
# Get Locations
Source: https://docs.kibocommerce.com/api-reference/inventorylocation/get-locations
/openapi/openapi_inventory.json get /commerce/inventory/v1/location
Get Locations
# Save Location
Source: https://docs.kibocommerce.com/api-reference/inventorylocation/save-location
/openapi/openapi_inventory.json post /commerce/inventory/v1/location
Save Location
# Get Location Groups
Source: https://docs.kibocommerce.com/api-reference/inventorylocationgroup/get-location-groups
/openapi/openapi_inventory.json get /commerce/inventory/v1/locationGroup
Get LocationGroups
# Get Order Item Information
Source: https://docs.kibocommerce.com/api-reference/inventoryorderitem/get-order-item-information
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/getOrderItemInformation
Retrieves the information for a specific order item
# Create Inventory Settings
Source: https://docs.kibocommerce.com/api-reference/inventorysettings/create-inventory-settings
/openapi/openapi_settings.json post /commerce/settings/inventory/inventorySettings
Creates inventory settings for the site
# Get Inventory Settings
Source: https://docs.kibocommerce.com/api-reference/inventorysettings/get-inventory-settings
/openapi/openapi_settings.json get /commerce/settings/inventory/inventorySettings
Retrieves existing inventory settings for the site which contain inventory export job settings.
# Update Inventory Settings
Source: https://docs.kibocommerce.com/api-reference/inventorysettings/update-inventory-settings
/openapi/openapi_settings.json put /commerce/settings/inventory/inventorySettings
Modifies existing inventory settings
# Update Tenant Silo Config
Source: https://docs.kibocommerce.com/api-reference/inventorysilo/update-tenant-silo-config
/openapi/openapi_inventory.json post /commerce/inventory/v1/silo/siloConfig
Updates tenant silo config
# Create Tag
Source: https://docs.kibocommerce.com/api-reference/inventorytag/create-tag
/openapi/openapi_inventory.json post /commerce/inventory/v1/tagCategory/{tagCategoryName}/tag
Create a tag
# Delete Tag
Source: https://docs.kibocommerce.com/api-reference/inventorytag/delete-tag
/openapi/openapi_inventory.json delete /commerce/inventory/v1/tagCategory/{tagCategoryName}/tag/{tagValue}
Delete a Tag
# Get Tag
Source: https://docs.kibocommerce.com/api-reference/inventorytag/get-tag
/openapi/openapi_inventory.json get /commerce/inventory/v1/tagCategory/{tagCategoryName}/tag/{tagValue}
Get a tag
# Update Tag
Source: https://docs.kibocommerce.com/api-reference/inventorytag/update-tag
/openapi/openapi_inventory.json put /commerce/inventory/v1/tagCategory/{tagCategoryName}/tag/{tagValue}
Update the designated tag
# Delete Tag Category
Source: https://docs.kibocommerce.com/api-reference/inventorytagcategory/delete-tag-category
/openapi/openapi_inventory.json delete /commerce/inventory/v1/tagCategory/{tagCategoryName}
Delete a Tag category
# Get Tag Category
Source: https://docs.kibocommerce.com/api-reference/inventorytagcategory/get-tag-category
/openapi/openapi_inventory.json get /commerce/inventory/v1/tagCategory/{tagCategoryName}
Get a tag category
# Get Tag Category All
Source: https://docs.kibocommerce.com/api-reference/inventorytagcategory/get-tag-category-all
/openapi/openapi_inventory.json get /commerce/inventory/v1/tagCategory
Get all tag categories for a tenant
# Update Tag Category
Source: https://docs.kibocommerce.com/api-reference/inventorytagcategory/update-tag-category
/openapi/openapi_inventory.json put /commerce/inventory/v1/tagCategory/{tagCategoryName}
Update the designated tag category
# B2B Order Release
Source: https://docs.kibocommerce.com/api-reference/job/b2b-order-release
/openapi/openapi_commerce.json post /commerce/jobs/b2bOrderRelease
Triggers on-demand B2B Order Release job.
# Add ListView
Source: https://docs.kibocommerce.com/api-reference/listviews/add-listview
/openapi/openapi_entities.json post /platform/entitylists/{entityListFullName}/views
Create a new ListView definition for a specific EntityList for a specific tenant
# Delete ListView
Source: https://docs.kibocommerce.com/api-reference/listviews/delete-listview
/openapi/openapi_entities.json delete /platform/entitylists/{entityListFullName}/views/{viewName}
Delete an existing ListView definition for a specific EntityList for a specific tenant
# Get ListView
Source: https://docs.kibocommerce.com/api-reference/listviews/get-listview
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/views/{viewName}
Returns a specific ListView definition for a specific EntityList for a specific tenant
# Get ListViews
Source: https://docs.kibocommerce.com/api-reference/listviews/get-listviews
/openapi/openapi_entities.json get /platform/entitylists/{entityListFullName}/views
Get all of the defined ListViews for a specific EntityList for a specific tenant
# Update ListView
Source: https://docs.kibocommerce.com/api-reference/listviews/update-listview
/openapi/openapi_entities.json put /platform/entitylists/{entityListFullName}/views/{viewName}
Update an existing ListView definition for a specific EntityList for a specific tenant
# Get Curbside Location
Source: https://docs.kibocommerce.com/api-reference/location/get-curbside-location
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/CS/location
Get the Curbside Location for the Site. If the location is not associated with a location type configured for the delivery location usage type (CS), the operation returns an error.
# Get Delivery Location
Source: https://docs.kibocommerce.com/api-reference/location/get-delivery-location
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/DL/location
Gets a specific Delivery Location for the site. If the location is not associated with a location type configured for the delivery location usage type (DL), the operation returns an error.
# Get Delivery Locations
Source: https://docs.kibocommerce.com/api-reference/location/get-delivery-locations
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/DL/locations
Gets the delivery Locations for the site
# Get Direct Ship Location
Source: https://docs.kibocommerce.com/api-reference/location/get-direct-ship-location
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/DS/location
Get the Direct Ship Location for the Site. This location acts as an origin address from which order packages will ship, as well as the location where product reservations are created when order items are submitted with the direct ship fulfillment type (DS). If the direct ship location usage type is not configured for this site, the operation returns an error.
# Get In Store Pickup Location
Source: https://docs.kibocommerce.com/api-reference/location/get-in-store-pickup-location
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/SP/locations/{locationCode}
Get a specific in store pickup Location for the Site. If the location is not associated with a location type configured for the in-store pickup location usage type (SP), the operation returns an error.
# Get In Store Pickup Locations
Source: https://docs.kibocommerce.com/api-reference/location/get-in-store-pickup-locations
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/SP/locations
Gets the in store pickup Locations for the site. For example, an application could use this operation to provide a store finder feature based on the shopper's GPS coordinates.
# Get Location
Source: https://docs.kibocommerce.com/api-reference/location/get-location
/openapi/openapi_location_storefront.json get /commerce/storefront/locations/{locationCode}
Get a Location by locationCode.
# Get Locations In Usage Type
Source: https://docs.kibocommerce.com/api-reference/location/get-locations-in-usage-type
/openapi/openapi_location_storefront.json get /commerce/storefront/locationUsageTypes/{locationUsageType}/locations
Get the Locations for the Site associated with the locationUsageType.
# Add Location
Source: https://docs.kibocommerce.com/api-reference/locationadmin/add-location
/openapi/openapi_location_admin.json post /commerce/admin/locations
Add a new location.
# Add Location Attribute
Source: https://docs.kibocommerce.com/api-reference/locationadmin/add-location-attribute
/openapi/openapi_location_admin.json post /commerce/admin/locations/{locationCode}/attributes
Add a new attribute to a location.
# Create Cutoff Time Override
Source: https://docs.kibocommerce.com/api-reference/locationadmin/create-cutoff-time-override
/openapi/openapi_location_admin.json post /commerce/admin/locations/cutoffoverrides
Creates a new Cut Off Time override.
# Delete Cutoff Time Override
Source: https://docs.kibocommerce.com/api-reference/locationadmin/delete-cutoff-time-override
/openapi/openapi_location_admin.json delete /commerce/admin/locations/cutoffoverrides/{overrideId}
Deletes a Cut Off Time override.
# Get Cutoff Time Override by Id
Source: https://docs.kibocommerce.com/api-reference/locationadmin/get-cutoff-time-override-by-id
/openapi/openapi_location_admin.json get /commerce/admin/locations/cutoffoverrides/{overrideId}
Retrieves a Cut Off Time override by its ID.
# Get Cutoff Time Overrides
Source: https://docs.kibocommerce.com/api-reference/locationadmin/get-cutoff-time-overrides
/openapi/openapi_location_admin.json get /commerce/admin/locations/cutoffoverrides
Gets all Cut Off Time overrides. Location and/or Date Range and/or FulfillmentType can be used to filter the results. For a single date, pass only the fromDate parameter.
# Get Location
Source: https://docs.kibocommerce.com/api-reference/locationadmin/get-location
/openapi/openapi_location_admin.json get /commerce/admin/locations/{locationCode}
Get a location by its unique locationCode.
# Get Location Attribute
Source: https://docs.kibocommerce.com/api-reference/locationadmin/get-location-attribute
/openapi/openapi_location_admin.json get /commerce/admin/locations/{locationCode}/attributes/{fullyQualifiedName}
Get a specific attribute from a location.
# Get Location Cut Off Time
Source: https://docs.kibocommerce.com/api-reference/locationadmin/get-location-cut-off-time
/openapi/openapi_location_admin.json post /commerce/admin/locations/{locationCode}/cutofftime
Gets an override if available, otherwise returns CutoffTime from Location
# Get Locations
Source: https://docs.kibocommerce.com/api-reference/locationadmin/get-locations
/openapi/openapi_location_admin.json get /commerce/admin/locations
Get locations with optional filtering and paging.
# Partially Update Location
Source: https://docs.kibocommerce.com/api-reference/locationadmin/partially-update-location
/openapi/openapi_location_admin.json patch /commerce/admin/locations/{locationCode}
Update specific fields of a location using RFC 6902 JSON Patch format.
# Remove Location Attribute
Source: https://docs.kibocommerce.com/api-reference/locationadmin/remove-location-attribute
/openapi/openapi_location_admin.json delete /commerce/admin/locations/{locationCode}/attributes/{fullyQualifiedName}
Remove an attribute from a location.
# Update Location
Source: https://docs.kibocommerce.com/api-reference/locationadmin/update-location
/openapi/openapi_location_admin.json put /commerce/admin/locations/{locationCode}
Update a location by providing its locationCode.
# Update Location Attribute
Source: https://docs.kibocommerce.com/api-reference/locationadmin/update-location-attribute
/openapi/openapi_location_admin.json put /commerce/admin/locations/{locationCode}/attributes/{fullyQualifiedName}
Update an existing attribute for a location.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/locationattributedefinitions/create-attribute
/openapi/openapi_location_admin.json post /commerce/admin/locations/attributedefinition/attributes
Create a new location attribute.
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/locationattributedefinitions/get-attribute
/openapi/openapi_location_admin.json get /commerce/admin/locations/attributedefinition/attributes/{attributeFQN}
Get Attribute
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/locationattributedefinitions/get-attribute-vocabulary-values
/openapi/openapi_location_admin.json get /commerce/admin/locations/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Retrieves the details of attribute vocabulary values.
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/locationattributedefinitions/get-attributes
/openapi/openapi_location_admin.json get /commerce/admin/locations/attributedefinition/attributes
Retrieves the details of attributes.
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/locationattributedefinitions/update-attribute
/openapi/openapi_location_admin.json put /commerce/admin/locations/attributedefinition/attributes/{attributeFQN}
Update a location attribute.
# Add location codes to a location group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/add-location-codes-to-a-location-group
/openapi/openapi_location_admin.json post /commerce/admin/locationGroups/{locationGroupCode}/locationCodes
Add location codes to a location group
# Add Location Group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/add-location-group
/openapi/openapi_location_admin.json post /commerce/admin/locationGroups
Add a location group.
# Delete Location Group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/delete-location-group
/openapi/openapi_location_admin.json delete /commerce/admin/locationGroups/{locationGroupCode}
Deletes a location group specified by location group code.
# Get Location Group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/get-location-group
/openapi/openapi_location_admin.json get /commerce/admin/locationGroups/{locationGroupCode}
Gets a location group by code.
# Get Location Groups
Source: https://docs.kibocommerce.com/api-reference/locationgroup/get-location-groups
/openapi/openapi_location_admin.json get /commerce/admin/locationGroups
Gets a collection of location groups.
# Partially Update Location Group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/partially-update-location-group
/openapi/openapi_location_admin.json patch /commerce/admin/locationGroups/{locationGroupCode}
Update specific fields of a location group using RFC 6902 JSON Patch format.
# Remove location codes from a location group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/remove-location-codes-from-a-location-group
/openapi/openapi_location_admin.json delete /commerce/admin/locationGroups/{locationGroupCode}/locationCodes
Remove location codes from a location group
# Update Location Group
Source: https://docs.kibocommerce.com/api-reference/locationgroup/update-location-group
/openapi/openapi_location_admin.json put /commerce/admin/locationGroups/{locationGroupCode}
Update an existing location group.
# Get Location Group Configuration
Source: https://docs.kibocommerce.com/api-reference/locationgroupconfiguration/get-location-group-configuration
/openapi/openapi_location_admin.json get /commerce/admin/locationGroupConfiguration/{locationGroupCode}
Get this tenants Location Group Configuration Values by locationGroupCode.
# Get Location Group Configuration by Location
Source: https://docs.kibocommerce.com/api-reference/locationgroupconfiguration/get-location-group-configuration-by-location
/openapi/openapi_location_admin.json get /commerce/admin/locationGroupConfiguration/location/{locationCode}
Get this tenants Location Group Configuration Values by Location Code.
# Set Location Group Configuration
Source: https://docs.kibocommerce.com/api-reference/locationgroupconfiguration/set-location-group-configuration
/openapi/openapi_location_admin.json put /commerce/admin/locationGroupConfiguration/{locationGroupCode}
Set this tenants Location Group Configuration Values.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/locationinventoryattributedefinition/create-attribute
/openapi/openapi_location_admin.json post /commerce/admin/locationsInventory/attributedefinition/attributes
Create Attribute
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/locationinventoryattributedefinition/get-attribute
/openapi/openapi_location_admin.json get /commerce/admin/locationsInventory/attributedefinition/attributes/{attributeFQN}
Get Attribute
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/locationinventoryattributedefinition/get-attribute-vocabulary-values
/openapi/openapi_location_admin.json get /commerce/admin/locationsInventory/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Get Attribute Vocabulary Values
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/locationinventoryattributedefinition/get-attributes
/openapi/openapi_location_admin.json get /commerce/admin/locationsInventory/attributedefinition/attributes
Get Attributes
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/locationinventoryattributedefinition/update-attribute
/openapi/openapi_location_admin.json put /commerce/admin/locationsInventory/attributedefinition/attributes/{attributeFQN}
Update Attribute
# Get Location Usage
Source: https://docs.kibocommerce.com/api-reference/locationsettings/get-location-usage
/openapi/openapi_location_admin.json get /commerce/settings/locationUsages/{code}
Get a locationUsage for the Site.
# Get Location Usages
Source: https://docs.kibocommerce.com/api-reference/locationsettings/get-location-usages
/openapi/openapi_location_admin.json get /commerce/settings/locationUsages
Get the locationUsages for the site.
# Update Location Usage Async
Source: https://docs.kibocommerce.com/api-reference/locationsettings/update-location-usage-async
/openapi/openapi_location_admin.json put /commerce/settings/locationUsages/{code}
Update a locationUsage for the Site.
# Add Location Type Async
Source: https://docs.kibocommerce.com/api-reference/locationtype/add-location-type-async
/openapi/openapi_location_admin.json post /commerce/admin/locationtypes
Create a LocationType.
# Delete Location Type
Source: https://docs.kibocommerce.com/api-reference/locationtype/delete-location-type
/openapi/openapi_location_admin.json delete /commerce/admin/locationtypes/{locationTypeCode}
Delete Location Type.
# Get Location Type
Source: https://docs.kibocommerce.com/api-reference/locationtype/get-location-type
/openapi/openapi_location_admin.json get /commerce/admin/locationtypes/{locationTypeCode}
Get a LocationType.
# Get Location Types
Source: https://docs.kibocommerce.com/api-reference/locationtype/get-location-types
/openapi/openapi_location_admin.json get /commerce/admin/locationtypes
Get a collection of LocationTypes.
# Get Location Types Paginated
Source: https://docs.kibocommerce.com/api-reference/locationtype/get-location-types-paginated
/openapi/openapi_location_admin.json get /commerce/admin/locationtypes/withpagination
Get a collection of LocationTypes.
# Update Location Type
Source: https://docs.kibocommerce.com/api-reference/locationtype/update-location-type
/openapi/openapi_location_admin.json put /commerce/admin/locationtypes/{locationTypeCode}
Update a LocationType.
# Create Manifest
Source: https://docs.kibocommerce.com/api-reference/manifest/create-manifest
/openapi/openapi_fulfillment.json post /commerce/fulfillment/shipping/manifests
Generate a shipping manifest.
# Get Eligible Shipments
Source: https://docs.kibocommerce.com/api-reference/manifest/get-eligible-shipments
/openapi/openapi_fulfillment.json get /commerce/fulfillment/shipping/manifests/eligibleShipments
Retrieve a list of shipments eligible for shipping manifests.
# Get Manifest
Source: https://docs.kibocommerce.com/api-reference/manifest/get-manifest
/openapi/openapi_fulfillment.json get /commerce/fulfillment/shipping/manifests/{manifestId}
Retrieve a shipping manifest by ID.
# Get Manifests
Source: https://docs.kibocommerce.com/api-reference/manifest/get-manifests
/openapi/openapi_fulfillment.json get /commerce/fulfillment/shipping/manifests
Retrieve shipping manifests.
# Get Master Catalog
Source: https://docs.kibocommerce.com/api-reference/mastercatalogpublishsettings/get-master-catalog
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/mastercatalogs/{masterCatalogId}
Retrieves a specific master catalog by its Id.
# Get Master Catalogs
Source: https://docs.kibocommerce.com/api-reference/mastercatalogpublishsettings/get-master-catalogs
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/mastercatalogs
Retrieves all master catalogs.
# Update Master Catalog
Source: https://docs.kibocommerce.com/api-reference/mastercatalogpublishsettings/update-master-catalog
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/mastercatalogs/{masterCatalogId}
Update the publishing mode of a master catalog
# Adjust
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/adjust
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/adjust
Adjusts the inventory count for a product at a location. It is different from Inventory Refresh because rather than stating the total quantity of the product, this adjustment specifies the amount of change in the form of increments and decrements (+/-). Increments do not require a + sign and may be sent as a simple integer, but decrements must include the – sign. For example, there would be a -2 quantity for an item if there were two fewer than in the previous count, a 2 quantity if there were two more, and a 0 quantity if there were no change.
These requests are placed into a queue of jobs that are processed one at a time. Due to this, the best practice is to submit fewer requests with more items per call, rather than numerous requests with a small number of items each. However, unlike the Refresh API that accepts a maximum of 12000 items per call, this Adjust API only accepts up to 1000 items. If you exceed that limit, a Bad Request error will be returned.
**Recommended:** Consider using the [Smart Adjust](/api-reference/modifyinventory/smart-adjust-inventory) endpoint instead, which automatically routes requests to sync or async processing based on payload size.
# Delete Future Inventory
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/delete-future-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/deleteFutureInventory
Deletes future inventory.
# Delete Inventory
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/delete-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/delete
Deletes inventory for a single product identifier (by `partNumber`, `upc`, or `sku`) across all or selected locations. Supports basic regex operators in the identifier field, making it well-suited for pattern-based deletion — for example, removing all products whose part number starts with a given prefix. The operation is asynchronous: the endpoint returns immediately with a list of job IDs (one per affected location) which you can monitor using the Get Job API. Use `dryRun: true` to preview the scope of deletion before executing. For step-by-step guidance including dry run workflow, job monitoring, and self-throttling patterns, see the Bulk Inventory Deletion guide.
# Delete Items
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/delete-items
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/deleteItems
Deletes inventory for multiple products in a single request. Accepts an array of up to 1,000 product identifiers per request (each specified by `partNumber`, `upc`, or `sku`); the recommended batch size is 500 items. The operation is asynchronous — the endpoint returns immediately with one job ID per affected location for progress tracking. Use `dryRun: true` to preview deletion scope before executing. For batch sizing, self-throttling patterns, step-by-step execution workflow, and job monitoring guidance, see the Bulk Inventory Deletion guide.
# Redistribute Inventory Across Tags
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/redistribute-inventory-across-tags
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/redistribute
Create jobs to redistribute inventory across tags for the given tenant
# Refresh
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/refresh
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/refresh
Sets the inventory count for products at a particular location. These requests are placed into a queue of jobs that are processed one at a time. Due to this, the best practice is to submit fewer requests with more items per call, rather than numerous requests with a small number of items each. Unlike the Adjust API that only accepts a maximum of 1000 items per call, this Refresh API can accept up to 12000 items. However, Kibo recommends batches of 3000 items.
**Recommended:** Consider using the [Smart Refresh](/api-reference/modifyinventory/smart-refresh-inventory) endpoint instead, which automatically routes requests to sync or async processing based on payload size.
# Smart Adjust Inventory
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/smart-adjust-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/smart-adjust/
Dynamically routes inventory adjustment requests to synchronous or asynchronous processing based on payload size. Smaller payloads are generally processed synchronously and return immediate results. Larger payloads are processed asynchronously and return a job ID for tracking. The request schema is identical to the standard Adjust API. For more information, see the Smart Inventory APIs guide.
# Smart Refresh Inventory
Source: https://docs.kibocommerce.com/api-reference/modifyinventory/smart-refresh-inventory
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/smart-refresh/
Dynamically routes inventory refresh requests to synchronous or asynchronous processing based on payload size. Smaller payloads are generally processed synchronously and return immediate results. Larger payloads are processed asynchronously and return a job ID for tracking. The request schema is identical to the standard Refresh API. For more information, see the Smart Inventory APIs guide.
# Add Validation Result
Source: https://docs.kibocommerce.com/api-reference/order/add-validation-result
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/validationresults
Adds a validation result to an order from an external system. This endpoint is used by asynchronous validators that review orders after submission and push results back into Kibo — for example, a fraud service that processes orders in a background queue. The validationId and createdDate fields are required. The status value (Pass, Review, Fail, or Error) determines whether the order proceeds to fulfillment or is held in PendingReview. See the Order Validators and Fraud Check Applications guide for the full schema, status effects, and implementation guidance.
# Adds Extended Properties
Source: https://docs.kibocommerce.com/api-reference/order/adds-extended-properties
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/extendedproperties
Adds extended properties.
# Add/Update Alternate Contact
Source: https://docs.kibocommerce.com/api-reference/order/addupdate-alternate-contact
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/upsertalternatecontact
Add/update an alternate contact.
# Apply Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/apply-adjustment
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/adjustment
Apply a pricing adjustment to the order.
# Apply Coupon
Source: https://docs.kibocommerce.com/api-reference/order/apply-coupon
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/coupons/{couponCode}
Apply a coupon to the order.
# Apply Handling Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/apply-handling-adjustment
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/adjustment/handling
Apply a handling adjustment to the order.
# Apply Package to Order
Source: https://docs.kibocommerce.com/api-reference/order/apply-package-to-order
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/packages
Applies a package to an existing order.
# Apply Shipping Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/apply-shipping-adjustment
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/adjustment/shipping
Apply a shipping adjustment to the order specified by order Id.
# Auto Capture Payments
Source: https://docs.kibocommerce.com/api-reference/order/auto-capture-payments
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/payments/autocapture
Amount to capture is total of fulfilled shipments - order adjustment - amount already captured.
# Cancel Order
Source: https://docs.kibocommerce.com/api-reference/order/cancel-order
/openapi/openapi_commerce.json put /commerce/orders/cancel/{orderId}
Cancel an order with the cancel reason.
# Change Order Price List
Source: https://docs.kibocommerce.com/api-reference/order/change-order-price-list
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/priceList
Changes the pricelist associated with an order.The desired price list code should be specified on the ApiContext.
# Change Order UserId
Source: https://docs.kibocommerce.com/api-reference/order/change-order-userid
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/users
Changes the User ID associated with an order.
# Create A Shipment
Source: https://docs.kibocommerce.com/api-reference/order/create-a-shipment
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments
Creates a shipment by grouping together multiple packages into logical shipments
# Create Digital Package
Source: https://docs.kibocommerce.com/api-reference/order/create-digital-package
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/digitalpackages
Apply a digital package to the order.
# Create line-level attributes on an order item; skips FQNs that already exist
Source: https://docs.kibocommerce.com/api-reference/order/create-line-level-attributes-on-an-order-item;-skips-fqns-that-already-exist
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/items/{orderItemId}/attributes
Create line-level attributes on an order item; skips FQNs that already exist.
# Create Order
Source: https://docs.kibocommerce.com/api-reference/order/create-order
/openapi/openapi_commerce.json post /commerce/orders
Creates a new order for no-cart quick-ordering scenarios. The full API payload required integration with the ecommerce front-end.
# Create Order Attributes
Source: https://docs.kibocommerce.com/api-reference/order/create-order-attributes
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/attributes
Adds a attributeSet to the order. This is an internal attributeSet that the merchant might want to add to an order.
# Create Order Item
Source: https://docs.kibocommerce.com/api-reference/order/create-order-item
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/items
Adds a product or other item to the cart of the current shopper.
# Create Order Note
Source: https://docs.kibocommerce.com/api-reference/order/create-order-note
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/notes
Adds a note to the order. This is an internal note that the merchant might want to add to an order.
# Create Payment Action
Source: https://docs.kibocommerce.com/api-reference/order/create-payment-action
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/payments/actions
Sets the action of the specified payment transaction interaction. Available actions depend on the current status of the payment transaction.If in doubt, get a list of available payment actions first.
# Create Pickup
Source: https://docs.kibocommerce.com/api-reference/order/create-pickup
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/pickups
Apply a pickup to the order.
# Create Refund
Source: https://docs.kibocommerce.com/api-reference/order/create-refund
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/refunds
Apply a refund to the order.
# Creates attributes on a shipment
Source: https://docs.kibocommerce.com/api-reference/order/creates-attributes-on-a-shipment
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/attributes
Creates attributes on a shipment.
# Delete a single line-level attribute from an order item by FQN
Source: https://docs.kibocommerce.com/api-reference/order/delete-a-single-line-level-attribute-from-an-order-item-by-fqn
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/items/{orderItemId}/attributes/{attributeFqn}
Delete a single line-level attribute from an order item by FQN.
# Delete An Existing Order Shipment
Source: https://docs.kibocommerce.com/api-reference/order/delete-an-existing-order-shipment
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/shipments/{shipmentId}
Deletes an existing order shipment.
# Delete Digital Package
Source: https://docs.kibocommerce.com/api-reference/order/delete-digital-package
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/digitalpackages/{digitalPackageId}
Delete an order digital package.
# Delete Extended Properties
Source: https://docs.kibocommerce.com/api-reference/order/delete-extended-properties
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/extendedproperties
Delete extended properties on the order.
# Delete Extended Property
Source: https://docs.kibocommerce.com/api-reference/order/delete-extended-property
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/extendedproperties/{key}
Removes a particular order item from the order of the current shopper.
# Delete Order Data
Source: https://docs.kibocommerce.com/api-reference/order/delete-order-data
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/data/{orderDataId}
Delete Value of the given Key in the OrderData bag.
# Delete Order Draft
Source: https://docs.kibocommerce.com/api-reference/order/delete-order-draft
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/draft
Deletes a draft version of an order.
# Delete Order Item
Source: https://docs.kibocommerce.com/api-reference/order/delete-order-item
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/items/{orderItemId}
Removes a particular order item from the order of the current shopper.
# Delete Order Item Data
Source: https://docs.kibocommerce.com/api-reference/order/delete-order-item-data
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/item/{orderItemId}/data/{orderItemDataId}
Deletes the Value of the given Key in the OrderItem Data bag.
# Delete Order Note
Source: https://docs.kibocommerce.com/api-reference/order/delete-order-note
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/notes/{noteId}
Deletes a specific order note on an order.
# Delete Order Package
Source: https://docs.kibocommerce.com/api-reference/order/delete-order-package
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/packages/{packageId}
Delete an order package.
# Delete Pickup
Source: https://docs.kibocommerce.com/api-reference/order/delete-pickup
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/pickups/{pickupId}
Delete an order pickup.
# Deletes attributes from a shipment
Source: https://docs.kibocommerce.com/api-reference/order/deletes-attributes-from-a-shipment
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/shipments/{shipmentNumber}/attributes
Deletes attributes from a shipment.
# Evaluate Order Rollup Status
Source: https://docs.kibocommerce.com/api-reference/order/evaluate-order-rollup-status
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/evaluaterollupstatus
Evaluate Order Rollup Status
# Get all line-level attributes for an order item
Source: https://docs.kibocommerce.com/api-reference/order/get-all-line-level-attributes-for-an-order-item
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/items/{orderItemId}/attributes
Get all line-level attributes for an order item.
# Get Available Actions
Source: https://docs.kibocommerce.com/api-reference/order/get-available-actions
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/actions
Retrieves available order actions which depends on the status of the order.Possible actions can be Create, Submit, SetAsProcessing, Close or Cancel.
# Get Available Digital Package Fulfillment Actions
Source: https://docs.kibocommerce.com/api-reference/order/get-available-digital-package-fulfillment-actions
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/digitalpackages/{digitalPackageId}/actions
Get available digital package fulfillment actions.
# Get Available Payment Actions
Source: https://docs.kibocommerce.com/api-reference/order/get-available-payment-actions
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/payments/{paymentId}/actions
Retrieves available payment actions which depends on the status of the order's payment transaction.
Possible actions can be "Create," "Capture," "Void," "AuthCapture," or "ReceiveCheck."
# Get Available Pickup Fulfillment Actions
Source: https://docs.kibocommerce.com/api-reference/order/get-available-pickup-fulfillment-actions
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/pickups/{pickupId}/actions
Get the available pickup fulfillment actions.
# Get Available Shipment Methods
Source: https://docs.kibocommerce.com/api-reference/order/get-available-shipment-methods
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/shipments/methods
Retrieves available shipping methods. Typically used to display available shipping method options on the checkout page.
# Get Billing Info
Source: https://docs.kibocommerce.com/api-reference/order/get-billing-info
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/billinginfo
Retrieves the customer's billing address.If paying by credit card, it retrieves the card's number, expiration date, card holder's name and billing address.
# Get Digital Package
Source: https://docs.kibocommerce.com/api-reference/order/get-digital-package
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/digitalpackages/{digitalPackageId}
Get an order digital package.
# Get Extended Properties
Source: https://docs.kibocommerce.com/api-reference/order/get-extended-properties
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/extendedproperties
Get extended properties on an order.
# Get Fulfillment Info
Source: https://docs.kibocommerce.com/api-reference/order/get-fulfillment-info
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/fulfillmentinfo
Retrieves an order's fulfillment information specified by order ID.
# Get Order
Source: https://docs.kibocommerce.com/api-reference/order/get-order
/openapi/openapi_commerce.json get /commerce/orders/{orderId}
Retrieves the details of an order specified by the order ID.
# Get Order Attributes
Source: https://docs.kibocommerce.com/api-reference/order/get-order-attributes
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/attributes
Retrieves a list of all attribute sets for an order.
# Get Order Cancel Reasons
Source: https://docs.kibocommerce.com/api-reference/order/get-order-cancel-reasons
/openapi/openapi_commerce.json get /commerce/orders/cancel/reasons
Gets order cancellation reasons based on a category.
# Get Order Data
Source: https://docs.kibocommerce.com/api-reference/order/get-order-data
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/data
Retrieves all the values in the Order Data bag
# Get Order Item
Source: https://docs.kibocommerce.com/api-reference/order/get-order-item
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/items/{orderItemId}
Retrieves the details of a single order item.
# Get Order Item Data
Source: https://docs.kibocommerce.com/api-reference/order/get-order-item-data
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/item/{orderItemId}/data
Retrieves a specific value in the OrderItem Data bag.
# Get Order Item Via LineId
Source: https://docs.kibocommerce.com/api-reference/order/get-order-item-via-lineid
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/items/{lineId}
Retrieves the details of a single order item via its line id.
# Get Order Items
Source: https://docs.kibocommerce.com/api-reference/order/get-order-items
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/items
Retrieves the details of all items in an order specified by order Id.
# Get Order Note
Source: https://docs.kibocommerce.com/api-reference/order/get-order-note
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/notes/{noteId}
Retrieves a specific order note from an order.
# Get Order Notes
Source: https://docs.kibocommerce.com/api-reference/order/get-order-notes
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/notes
Retrieves a list of all notes for an order.
# Get Order Package
Source: https://docs.kibocommerce.com/api-reference/order/get-order-package
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/packages/{packageId}
Get an order package.
# Get Order Package Label
Source: https://docs.kibocommerce.com/api-reference/order/get-order-package-label
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/packages/{packageId}/label
Get an order package label
# Get Order Returnable Items
Source: https://docs.kibocommerce.com/api-reference/order/get-order-returnable-items
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/returnableitems
Provides fulfillment information for order items such as quantity ordered, fulfilled, and returned. Indicates which items are eligible for return.
# Get Orders
Source: https://docs.kibocommerce.com/api-reference/order/get-orders
/openapi/openapi_commerce.json get /commerce/orders
Retrieves a list of orders according to any specified filter criteria and sort options.
# Get Payment
Source: https://docs.kibocommerce.com/api-reference/order/get-payment
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/payments/{paymentId}
Retrieves a specific payment transaction from the order.
# Get Payments
Source: https://docs.kibocommerce.com/api-reference/order/get-payments
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/payments
Retrieves payment transactions for an order. Allows filtering and sorting.
# Get Pickup
Source: https://docs.kibocommerce.com/api-reference/order/get-pickup
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/pickups/{pickupId}
Gets a specified pickup on the order.
# Get Queued Historical Order
Source: https://docs.kibocommerce.com/api-reference/order/get-queued-historical-order
/openapi/openapi_commerce.json get /commerce/orders/queuedorders/historical/{orderId}
Retrieves the details of a historical order specified by the order ID.
# Get Queued Historical Orders
Source: https://docs.kibocommerce.com/api-reference/order/get-queued-historical-orders
/openapi/openapi_commerce.json get /commerce/orders/queuedorders/historical
Retrieves a list of queued historical orders according to any specified filter criteria and sort options.
# Get Queued Order
Source: https://docs.kibocommerce.com/api-reference/order/get-queued-order
/openapi/openapi_commerce.json get /commerce/orders/queuedorders/{orderId}
RRetrieves the details of an order specified by the order ID.
# Get Queued Orders
Source: https://docs.kibocommerce.com/api-reference/order/get-queued-orders
/openapi/openapi_commerce.json get /commerce/orders/queuedorders
Retrieves a list of queuedorders according to any specified filter criteria and sort options.
# Get Refund Reasons
Source: https://docs.kibocommerce.com/api-reference/order/get-refund-reasons
/openapi/openapi_commerce.json get /commerce/orders/refunds/refundreasons
Gets all the refund reasons.
# Get Shipment
Source: https://docs.kibocommerce.com/api-reference/order/get-shipment
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/shipments/{shipmentId}
Allows a shipment to be retrieved for the order. This API only applies to previous version of eCommerce. Get the Kibo shipment documentation here
# Get Taxable Orders
Source: https://docs.kibocommerce.com/api-reference/order/get-taxable-orders
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/taxableorders
Gets an order divided up into "TaxableOrders" based on the source and delivery locations of the order items. Generally used for the purpose of splitting it into multiple taxable orders in order to fulfill the order in multiple locations.
# Get Validation Results
Source: https://docs.kibocommerce.com/api-reference/order/get-validation-results
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/validationresults
Retrieves all validation results stored on an order. Each result represents the outcome of an order validator capability — such as a fraud check — that was called when the order was submitted. Results include the validator status (Pass, Review, Fail, or Error), validator type, and any messages returned by the validator. See the Order Validators and Fraud Check Applications guide for full details on how validation results affect order state.
# Gets all attributes for a shipment
Source: https://docs.kibocommerce.com/api-reference/order/gets-all-attributes-for-a-shipment
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/shipments/{shipmentNumber}/attributes
Gets all attributes for a shipment.
# Perform Fulfillment Action
Source: https://docs.kibocommerce.com/api-reference/order/perform-fulfillment-action
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/fulfillment/actions
Sets the fulfillment action to 'Ship'. To ship an order, the order must have a customer name, the 'Open' or 'OpenAdProcessing' status, full shipping address, and shipping method.
# Perform Order Action
Source: https://docs.kibocommerce.com/api-reference/order/perform-order-action
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/actions
Set an action on the order. Available actions depend on the current status of the order. If in doubt, get a list of available order actions first.
# Perform Payment Action
Source: https://docs.kibocommerce.com/api-reference/order/perform-payment-action
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/payments/{paymentId}/actions
Performs a specific payment action. Available actions depend on the current status of the payment transaction. If in doubt, get a list of available payment actions first.
# Price Order
Source: https://docs.kibocommerce.com/api-reference/order/price-order
/openapi/openapi_commerce.json post /commerce/orders/price
Order price.
# Process Digital Wallet
Source: https://docs.kibocommerce.com/api-reference/order/process-digital-wallet
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/digitalWallet/{digitalWalletType}
Process digital wallet (used to hold 3rd party payment and shipping information) on the order.
# Process Return Rules
Source: https://docs.kibocommerce.com/api-reference/order/process-return-rules
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/processreturnrules
Applies the return rules to the shipment items and responds if items are eligible for return. Provides fulfillment information for order items such as quantity ordered, fulfilled, and returned. Indicates which items are eligible for return.
# Remove Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/remove-adjustment
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/adjustment
Removes an adjustment that had been previously applied to the order.
# Remove Alternate Contact
Source: https://docs.kibocommerce.com/api-reference/order/remove-alternate-contact
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/removealternatecontact
Remove alternate contact from order and shipments.
# Remove Coupon
Source: https://docs.kibocommerce.com/api-reference/order/remove-coupon
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/coupons/{couponCode}
Removes a coupon that had been previously applied to the order.
# Remove Coupons
Source: https://docs.kibocommerce.com/api-reference/order/remove-coupons
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/coupons
Removes all coupons that had been previously applied to the order.
# Remove Handling Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/remove-handling-adjustment
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/adjustment/handling
Removes a coupon that had been previously applied to the order.
# Remove Shipping Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/remove-shipping-adjustment
/openapi/openapi_commerce.json delete /commerce/orders/{orderId}/adjustment/shipping
Removes an adjustment that had been previously applied to the order.
# Reprice Canceled Shipment
Source: https://docs.kibocommerce.com/api-reference/order/reprice-canceled-shipment
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/repricecanceledshipment
Reprices a fully canceled shipment or when the last item is canceled.
# Reprice Shipment
Source: https://docs.kibocommerce.com/api-reference/order/reprice-shipment
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/reprice
Allows a shipment to be repriced.
# Reprice Substitutes
Source: https://docs.kibocommerce.com/api-reference/order/reprice-substitutes
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/repricesubstitutes
Reprice substitute items in shipments.
# Resend Gateway Gift Card Email
Source: https://docs.kibocommerce.com/api-reference/order/resend-gateway-gift-card-email
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/giftcard/{giftcardId}/resend
Resend gateway giftcard email.
# Resend Order Confirmation Email
Source: https://docs.kibocommerce.com/api-reference/order/resend-order-confirmation-email
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/email/resend
Resend order confirmation email specified by the Order Id. The only supported actionName for the request body is SubmitOrder.
# Resend Package Fulfillment Email
Source: https://docs.kibocommerce.com/api-reference/order/resend-package-fulfillment-email
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/fulfillment/email/resend
Resends the package fulfillment email.
# Resend Refund Email
Source: https://docs.kibocommerce.com/api-reference/order/resend-refund-email
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/refunds/{refundId}
Resend refund email.
# Retrieves Available Fulfillment Actions
Source: https://docs.kibocommerce.com/api-reference/order/retrieves-available-fulfillment-actions
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/packages/{packageId}/actions
Retrieves the available fulfillment actions.
# Set Billing Info
Source: https://docs.kibocommerce.com/api-reference/order/set-billing-info
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/billinginfo
Adds a payment source to the order.
# Set Fulfillment Info
Source: https://docs.kibocommerce.com/api-reference/order/set-fulfillment-info
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/fulfillmentinfo
Modifies an order's fulfillment information. For example, to update the fulfillment address, estimated delivery date, or the merchant's fulfillment cost.
# Sms Opt Out
Source: https://docs.kibocommerce.com/api-reference/order/sms-opt-out
/openapi/openapi_commerce.json put /commerce/orders/sms/optout/{siteId}
Opting out from the sms notifications.
# Split Order Into Shipment
Source: https://docs.kibocommerce.com/api-reference/order/split-order-into-shipment
/openapi/openapi_commerce.json get /commerce/orders/{orderId}/converttoship
Split Order Into Shipment
# Split Shipments
Source: https://docs.kibocommerce.com/api-reference/order/split-shipments
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/split
Allows spliting an existing shipment.
# Update Digital Package
Source: https://docs.kibocommerce.com/api-reference/order/update-digital-package
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/digitalpackages/{digitalPackageId}
Updates a digital package on the order.
# Update Extended Property
Source: https://docs.kibocommerce.com/api-reference/order/update-extended-property
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/extendedproperties/{key}
Updated specific extended property
# Update Item Duty
Source: https://docs.kibocommerce.com/api-reference/order/update-item-duty
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/dutyAmount/{dutyAmount}
Updates the duty amount of an order item in the order.
# Update Item Fulfillment
Source: https://docs.kibocommerce.com/api-reference/order/update-item-fulfillment
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/fulfillment
Updates the fulfillment method and/or location of an individual order item in the order of the current shopper.
# Update Item Product Price
Source: https://docs.kibocommerce.com/api-reference/order/update-item-product-price
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/price/{price}
Updates the price of an individual order item in the order.
# Update Item Quantity
Source: https://docs.kibocommerce.com/api-reference/order/update-item-quantity
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/quantity/{quantity}
Updates the quantity of an individual order item in the order.
# Update Order
Source: https://docs.kibocommerce.com/api-reference/order/update-order
/openapi/openapi_commerce.json put /commerce/orders/{orderId}
Updates an existing order. The fields that can be modified depend on the current state of the order and the `updateMode` used.
## Update Modes
| Mode | Value | Description |
|------|-------|-------------|
| `ApplyToOriginal` | (default) | Applies changes directly to the order. For accepted orders, the order must pass editability checks or the call will be rejected (except for `ExternalId` on partial orders). |
| `ApplyToDraft` | `ApplyToDraft` | Applies changes to a draft copy of the order. The original order is not modified. A draft is automatically created if one does not exist. The draft has `Status=Pending` and passes editability checks, so all editable fields can be set on the draft. |
| `ApplyAndCommit` | `ApplyAndCommit` | Applies changes to the draft and then commits the draft back to the original order. For accepted orders, this creates new shipments from the draft order items. |
## Editability Rules
An order is considered **not editable** when any of the following are true:
- The order has been accepted (`AcceptedDate` is set, meaning shipments have been created).
- The order status is not one of: `Pending`, `PendingReview`, or `PendingShipment`.
- The order is a partial/split order in a non-`Pending`/non-`PendingShipment` status.
When the order is not editable and `updateMode=ApplyToOriginal`, the API will return a `403 Forbidden` error, **except** for the `ExternalId` field on partial orders (see below).
When `updateMode=ApplyToDraft`, the changes are applied to the draft copy which is always in `Pending` status, so the editability restriction does not block the update.
## Fields Updated by UpdateOrder
### Always Updated (Regardless of Order Status)
These fields are copied from the request body to the order on every call, whether the order is pre-acceptance or post-acceptance (when using draft mode):
| Field | Notes |
|-------|-------|
| `Email` | Overwrites the existing value. |
| `SourceDevice` | Overwrites the existing value. |
| `AcceptsMarketing` | Only updated if the incoming value is non-null; otherwise the existing value is preserved. |
| `VisitId` | Overwrites the existing value. |
| `WebSessionId` | Overwrites the existing value. |
| `CustomerInteractionType` | Overwrites the existing value. |
| `ShopperNotes` | Overwrites the existing value. |
| `AlternateContact` | Overwrites the existing value. |
| `ShipmentCreationOffset` | Validated: must be `-1` or a positive integer from `1` to `7200`. |
| `ParentOrderId` | Validated: cannot be set to the order's own ID; the referenced parent order must exist. |
| `ExternalId` | Can be set or changed, but **cannot be cleared** once set. If the incoming value is null or empty, the existing value is preserved. |
| `FulfillmentInfo` | Updated via `SetFulfillmentInfoAsync` if a non-null value is provided. |
### Conditionally Updated
| Field | Condition | Notes |
|-------|-----------|-------|
| `UserId` | Only if `CustomerAccountId` is null **and** `UserId` is currently blank on the order. | Once set, `UserId` cannot be changed via this API. |
| `CustomerAccountId` | Only if `CustomerAccountId` is currently null on the order. | Once set, `CustomerAccountId` cannot be changed via this API. If not yet set and the caller is not an anonymous shopper, a customer account is created or looked up automatically. |
| `DutyAmount` | Only if the order is in a **modifiable** status (not `Completed`, `Cancelled`, `Null`, or `Abandoned`). | If the order is in a terminal status and the incoming `DutyAmount` differs from the existing value, a `cannotUpdateDutyAmount` validation error is thrown. If the duty total changes, the pricing pipeline is re-executed. |
| `BillingInfo` | Only if the order has **not** been accepted (`HasBeenAccepted = false`). | Ignored on accepted orders. Use the dedicated [Set Billing Info](/api-reference/order/set-billing-info) API instead. |
| `IPAddress` | Only for **offline** orders (`Type = Offline`). | For online orders, the IP address is set from the client request automatically (pre-submission only). |
| `OriginalCartId` | Only for **offline** orders, and only if a non-empty value is provided. | Used for cart takeover scenarios. |
### Post-Acceptance Discount Exclusions
When the order **has** been accepted, the API supports updating **discount exclusions** on existing order-level and shipping-level discounts:
- `OrderDiscounts` -- each discount's exclusion flag can be toggled via `UpdateDiscountExclusion`.
- `ShippingDiscounts` -- each discount's exclusion flag can be toggled via `UpdateDiscountExclusion`.
If any discount exclusion is changed, the pricing pipeline is re-executed to recalculate totals.
This is the **only** pricing-related modification available on accepted orders through this endpoint (outside of draft mode).
### ExternalId on Non-Editable Partial Orders
As a special case, if the order fails editability checks (e.g., it is a partial/split order that has been accepted) but the request body includes a non-empty `ExternalId`, the `ExternalId` is updated and the order is saved immediately. No other fields are modified and no pricing pipeline is executed. This is the only field that bypasses the editability restriction outside of draft mode.
## Draft Mode Behavior (ApplyToDraft / ApplyAndCommit)
When `updateMode=ApplyToDraft`:
1. The system retrieves or creates a draft copy of the order. The draft is a separate embedded document with `Status=Pending` and `IsDraft=true`.
2. All field updates listed above are applied to the **draft**, not the original order.
3. The draft is persisted. The original order is unchanged.
4. The draft is returned in the response.
When `updateMode=ApplyAndCommit`:
1. The same field updates are applied to the draft.
2. After updates, the system calls `CreateShipmentsFromDraftOrder`, which:
- Validates the order is in draft mode and has items.
- Splits the draft order into shipments via the fulfillment routing engine.
- Evaluates and updates the rollup status on the original order.
- Adds a `PostSubmitItemsAdded` change message to the original order.
- Clears the draft from the original order.
3. The updated original order (with new shipments) is returned.
## Pricing Pipeline
The update order pricing pipeline is re-executed when:
- `DutyAmount` changes (and the order is in a modifiable status).
- A discount exclusion is toggled on an accepted order.
When the pipeline runs, it recalculates order totals, taxes, and applied discounts.
## Summary: What Can You Update on an Accepted Order with Shipments?
### Directly (updateMode=ApplyToOriginal)
| Updatable | Field |
|-----------|-------|
| Yes | `Email` |
| Yes | `SourceDevice` |
| Yes | `AcceptsMarketing` |
| Yes | `VisitId` |
| Yes | `WebSessionId` |
| Yes | `CustomerInteractionType` |
| Yes | `ShopperNotes` |
| Yes | `AlternateContact` |
| Yes | `ShipmentCreationOffset` |
| Yes | `ParentOrderId` |
| Yes | `ExternalId` (set/change only, not clear) |
| Yes | `FulfillmentInfo` |
| Yes | `DutyAmount` (if order is not in terminal status) |
| Yes | `OrderDiscounts` / `ShippingDiscounts` (exclusion flag only) |
| **No** | `BillingInfo` (ignored after acceptance; use [Set Billing Info](/api-reference/order/set-billing-info)) |
| **No** | `UserId` (locked once set) |
| **No** | `CustomerAccountId` (locked once set) |
| **No** | `IPAddress` (online orders only, pre-submission only) |
| **No** | `Items` (use draft mode or the dedicated Order Items API) |
### Via Draft Mode (updateMode=ApplyToDraft then ApplyAndCommit)
All of the above fields, plus the ability to modify items on the draft and commit them as new shipments on the original order.
# Update Order Attributes
Source: https://docs.kibocommerce.com/api-reference/order/update-order-attributes
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/attributes
Updates a specific order attribute set of an order.
# Update Order Data
Source: https://docs.kibocommerce.com/api-reference/order/update-order-data
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/data/{orderDataId}
Insert / Updates the Value of the given Key in the OrderData bag.
# Update Order Discount
Source: https://docs.kibocommerce.com/api-reference/order/update-order-discount
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/discounts/{discountId}
Update existing discount on the order.
# Update Order Item Data
Source: https://docs.kibocommerce.com/api-reference/order/update-order-item-data
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/item/{orderItemId}/data/{orderItemDataId}
Insert / Updates the Value of the given Key in the OrderItem Data bag.
# Update Order Item Discount
Source: https://docs.kibocommerce.com/api-reference/order/update-order-item-discount
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/discounts/{discountId}
Update a discount on the order item to ignore or unignore it.
# Update Order Item Gift Information
Source: https://docs.kibocommerce.com/api-reference/order/update-order-item-gift-information
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/updateGiftInfo
Updates the gift information on an order item
# Update Order Item Subscription Info
Source: https://docs.kibocommerce.com/api-reference/order/update-order-item-subscription-info
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/subscriptionInfo
Update a subscription info on the order item, applies only to Draft Order.
# Update Order Note
Source: https://docs.kibocommerce.com/api-reference/order/update-order-note
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/notes/{noteId}
Updates a specific order note for an order.
# Update Order Package
Source: https://docs.kibocommerce.com/api-reference/order/update-order-package
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/packages/{packageId}
Updates an order package.
# Update Order Restrictions
Source: https://docs.kibocommerce.com/api-reference/order/update-order-restrictions
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/updateorderrestrictions
Updates the flags for restricting edits and/or cancellations by users without override user behaviors.
# Update Pickup
Source: https://docs.kibocommerce.com/api-reference/order/update-pickup
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/pickups/{pickupId}
Updates pickup details on the order.
# Update Shipment Adjustments
Source: https://docs.kibocommerce.com/api-reference/order/update-shipment-adjustments
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/adjustments
Updates adjustments on shipments.
# Update Shipment and Multiple Shipment Items Adjustment
Source: https://docs.kibocommerce.com/api-reference/order/update-shipment-and-multiple-shipment-items-adjustment
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/adjustments/bulk
Updates shipment and shipment items adjustment.
# Update Shipment Item
Source: https://docs.kibocommerce.com/api-reference/order/update-shipment-item
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/{shipmentNumber}/item/{itemId}/adjustments
Updates shipment item with new shipment adjustment.
# Update Shipping and Suggestions
Source: https://docs.kibocommerce.com/api-reference/order/update-shipping-and-suggestions
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/UpdateShippingAndSuggestions
Updates the shipping and suggestions information of an individual order item in the order.
# Update the Delivery Date of Order Item
Source: https://docs.kibocommerce.com/api-reference/order/update-the-delivery-date-of-order-item
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/deliverydate
Updates the Delivery Date of a particular Order Item
# Updated Extended Properties
Source: https://docs.kibocommerce.com/api-reference/order/updated-extended-properties
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/extendedproperties
Update extended properties.
# Updates attributes on a shipment
Source: https://docs.kibocommerce.com/api-reference/order/updates-attributes-on-a-shipment
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/shipments/{shipmentNumber}/attributes
Updates attributes on a shipment.
# Updates SubstituteInfo on OrderItem
Source: https://docs.kibocommerce.com/api-reference/order/updates-substituteinfo-on-orderitem
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/upsertSubstituteInfo
Updates SubstituteInfo on OrderItem
# Upsert Gift Message
Source: https://docs.kibocommerce.com/api-reference/order/upsert-gift-message
/openapi/openapi_commerce.json post /commerce/orders/{orderId}/shipments/upsertgiftmessage
Upserts the gift message on a shipment
# Upsert Inventory Tags on OrderItem
Source: https://docs.kibocommerce.com/api-reference/order/upsert-inventory-tags-on-orderitem
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/upsertInventoryTags
You need to pass in all tags everytime
# Upsert line-level attributes on an order item
Source: https://docs.kibocommerce.com/api-reference/order/upsert-line-level-attributes-on-an-order-item
/openapi/openapi_commerce.json put /commerce/orders/{orderId}/items/{orderItemId}/attributes
Upsert line-level attributes on an order item.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/orderattributedefinitions/create-attribute
/openapi/openapi_commerce.json post /commerce/orders/attributedefinition/attributes
Create a new attribute.
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/orderattributedefinitions/get-attribute
/openapi/openapi_commerce.json get /commerce/orders/attributedefinition/attributes/{attributeFQN}
Get an order attribute by its attributeFQN.
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/orderattributedefinitions/get-attribute-vocabulary-values
/openapi/openapi_commerce.json get /commerce/orders/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Retrieves the details of attribute vocabulary values.
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/orderattributedefinitions/get-attributes
/openapi/openapi_commerce.json get /commerce/orders/attributedefinition/attributes
Retrieves the details of attributes.
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/orderattributedefinitions/update-attribute
/openapi/openapi_commerce.json put /commerce/orders/attributedefinition/attributes/{attributeFQN}
Update an order attribute.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/orderlineattributedefinition/create-attribute
/openapi/openapi_commerce.json post /commerce/orders/lineitems/attributedefinition/attributes
Create Attribute
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/orderlineattributedefinition/get-attribute
/openapi/openapi_commerce.json get /commerce/orders/lineitems/attributedefinition/attributes/{attributeFQN}
Get Attribute
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/orderlineattributedefinition/get-attribute-vocabulary-values
/openapi/openapi_commerce.json get /commerce/orders/lineitems/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Get Attribute Vocabulary Values
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/orderlineattributedefinition/get-attributes
/openapi/openapi_commerce.json get /commerce/orders/lineitems/attributedefinition/attributes
Get Attributes
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/orderlineattributedefinition/update-attribute
/openapi/openapi_commerce.json put /commerce/orders/lineitems/attributedefinition/attributes/{attributeFQN}
Update Attribute
# Create Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingcustomdatalist/create-custom-data-list
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/filterDataLists
Create Custom Data List
# Delete Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingcustomdatalist/delete-custom-data-list
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/filterDataLists/{listId}
Delete Custom Data List
# Export List Entries As Csv
Source: https://docs.kibocommerce.com/api-reference/orderroutingcustomdatalist/export-list-entries-as-csv
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/filterDataLists/{listId}/download
Export List Entries As Csv
# Get Custom Data List By Id
Source: https://docs.kibocommerce.com/api-reference/orderroutingcustomdatalist/get-custom-data-list-by-id
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/filterDataLists/{listId}
Get Custom Data List By Id
# List Custom Data Lists
Source: https://docs.kibocommerce.com/api-reference/orderroutingcustomdatalist/list-custom-data-lists
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/filterDataLists
List Custom Data Lists
# Update Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingcustomdatalist/update-custom-data-list
/openapi/openapi_orderrouting.json put /commerce/orders/orderrouting/api/v1/filterDataLists/{listId}
Update Custom Data List
# Create Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingdatalist/create-custom-data-list
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/dataList
Create Custom Data List
# Delete Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingdatalist/delete-custom-data-list
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/dataList/{dataListID}
Deletes a custom data list.
# Get Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingdatalist/get-custom-data-list
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/dataList/{dataListID}
Get Custom Data List
# Update Custom Data List
Source: https://docs.kibocommerce.com/api-reference/orderroutingdatalist/update-custom-data-list
/openapi/openapi_orderrouting.json put /commerce/orders/orderrouting/api/v1/dataList/{dataListID}
Update Custom Data List
# Suggest Routing With EDD
Source: https://docs.kibocommerce.com/api-reference/orderroutingedd/suggest-routing-with-edd
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/routing/edd/suggestion
Suggest Routing With EDD
# Delete Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/delete-filter
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/filter/delete/{filterID}
Deletes a filter
# Get Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/get-filter
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/filter/{filterID}
Retrieves a filter by ID.
# Save Criteria Set Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/save-criteria-set-filter
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/filter/criteriaSet
Saves a criteria set filter.
# Save Custom Data List Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/save-custom-data-list-filter
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/filter/customDataListFilter
Saves a custom data list filter.
# Save Custom Data Value Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/save-custom-data-value-filter
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/filter/customDataValueFilter
Saves a custom data value filter.
# Test Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/test-filter
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/filter/testcriteria
Tests a filter.
# Test Set Filter
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilter/test-set-filter
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/filter/testset
Tests a set filter.
# Get Filter Attributes
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilterdata/get-filter-attributes
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/filter-attributes
Get Filter Attributes
# Get Filter Logical Groups For Scenario
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilterdata/get-filter-logical-groups-for-scenario
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/scenarios/{scenarioId}/filterLogicalGroups
Get Filter Logical Groups For Scenario
# Get Filter Operators
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilterdata/get-filter-operators
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/filter-operators
Get Filter Operators
# Get Filter Types
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilterdata/get-filter-types
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/filter-types
Get Filter Types
# Get Filters For Scenario
Source: https://docs.kibocommerce.com/api-reference/orderroutingfilterdata/get-filters-for-scenario
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/scenarios/{scenarioId}/filters
Get Filters For Scenario
# Delete Group
Source: https://docs.kibocommerce.com/api-reference/orderroutinggroup/delete-group
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/group/delete/{groupID}
Delete Group
# Get Group
Source: https://docs.kibocommerce.com/api-reference/orderroutinggroup/get-group
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/group/{groupID}
Retrieves a routing group by ID.
# Save Group
Source: https://docs.kibocommerce.com/api-reference/orderroutinggroup/save-group
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/group
Saves a routing group.
# Set Group Filters
Source: https://docs.kibocommerce.com/api-reference/orderroutinggroup/set-group-filters
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/group/{groupID}/setFilters
Sets a routing group's filters.
# Set Group Sorts
Source: https://docs.kibocommerce.com/api-reference/orderroutinggroup/set-group-sorts
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/group/{groupID}/setSorts
Sets a routing group's sorting options.
# Test Group
Source: https://docs.kibocommerce.com/api-reference/orderroutinggroup/test-group
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/group/test
Tests a routing group.
# Get Location by Location Code
Source: https://docs.kibocommerce.com/api-reference/orderroutinglocation/get-location-by-location-code
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/location/{locationCode}
Retrieve a specific location by its location code.
# Get Locations
Source: https://docs.kibocommerce.com/api-reference/orderroutinglocation/get-locations
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/location
Retrieve a list of locations.
# Create Scenario
Source: https://docs.kibocommerce.com/api-reference/orderroutingscenario/create-scenario
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios
Create Scenario
# Delete Scenario
Source: https://docs.kibocommerce.com/api-reference/orderroutingscenario/delete-scenario
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios/{scenarioID}
Delete Scenario
# Export Scenarios To Csv
Source: https://docs.kibocommerce.com/api-reference/orderroutingscenario/export-scenarios-to-csv
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios/export/csv
Export Scenarios To Csv
# Get Scenario By Id
Source: https://docs.kibocommerce.com/api-reference/orderroutingscenario/get-scenario-by-id
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios/{scenarioID}
Get Scenario By Id
# Import Scenarios From Csv
Source: https://docs.kibocommerce.com/api-reference/orderroutingscenario/import-scenarios-from-csv
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios/import/csv
Import Scenarios From Csv
# Update Scenario
Source: https://docs.kibocommerce.com/api-reference/orderroutingscenario/update-scenario
/openapi/openapi_orderrouting.json put /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios/{scenarioID}
Update Scenario
# Delete Filter Attribute
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/delete-filter-attribute
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/settings/filterAttributes/{attributeName}
Deletes a filter attribute.
# Delete Order Routing Settings
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/delete-order-routing-settings
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/settings
Remove order routing settings.
# Get Filter Attribute
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/get-filter-attribute
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/settings/filterAttributes/{attributeName}
Retrieve an order routing filter attribute based on its name.
# Get Filter Attributes
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/get-filter-attributes
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/settings/filterAttributes
Retrieves a list of order routing filter attributes.
# Get Order Routing Settings
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/get-order-routing-settings
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/settings
Retrieve a list of order routing settings.
# Save Filter Attribute
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/save-filter-attribute
/openapi/openapi_orderrouting.json put /commerce/orders/orderrouting/api/v1/settings/filterAttributes
Saves an order routing filter attribute.
# Save Order Routing Settings
Source: https://docs.kibocommerce.com/api-reference/orderroutingsettings/save-order-routing-settings
/openapi/openapi_orderrouting.json put /commerce/orders/orderrouting/api/v1/settings
Save order routing settings.
# Create Strategy
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/create-strategy
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/strategies
Create Strategy
# Delete Strategy
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/delete-strategy
/openapi/openapi_orderrouting.json delete /commerce/orders/orderrouting/api/v1/strategies/{strategyID}
Delete Strategy
# Get Candidate Sort Strategies
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/get-candidate-sort-strategies
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/candidateSortStrategies
Get Candidate Sort Strategies
# Get Fail Over Actions
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/get-fail-over-actions
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/failOverActions
Get Fail Over Actions
# Get Order Types
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/get-order-types
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/orderTypes
Get Order Types
# Get Sort Criteria
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/get-sort-criteria
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/sortCriteria
Get Sort Criteria
# Get Strategy By Id
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/get-strategy-by-id
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/{strategyID}
Get Strategy By Id
# List All Strategies
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/list-all-strategies
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies
List All Strategies
# List Scenarios By Strategy
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/list-scenarios-by-strategy
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/{strategyID}/scenarios
List Scenarios By Strategy
# Update Strategy
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategy/update-strategy
/openapi/openapi_orderrouting.json put /commerce/orders/orderrouting/api/v1/strategies/{strategyID}
Update Strategy
# Export Strategy
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategyexport/export-strategy
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/strategies/{strategyId}/export
Export Strategy
# Import Strategy
Source: https://docs.kibocommerce.com/api-reference/orderroutingstrategyexport/import-strategy
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/strategies/import
Import Strategy
# Clone Package
Source: https://docs.kibocommerce.com/api-reference/package/clone-package
/openapi/openapi_appdevelopement.json post /platform/appdev/apppackages/{applicationKey}/clone/{packageName}
Use this operation to clone an existing package.
# Create New Core Package
Source: https://docs.kibocommerce.com/api-reference/package/create-new-core-package
/openapi/openapi_appdevelopement.json post /platform/appdev/apppackages/create
Save as new version of the application core with only a release package included.
# Create Package
Source: https://docs.kibocommerce.com/api-reference/package/create-package
/openapi/openapi_appdevelopement.json post /platform/appdev/apppackages/project
Create a new application package.
# Get Application Summary Children
Source: https://docs.kibocommerce.com/api-reference/package/get-application-summary-children
/openapi/openapi_appdevelopement.json get /platform/appdev/apppackages/apps/{appId}
Get a list of application summaries.
# Get Application Summary Parents
Source: https://docs.kibocommerce.com/api-reference/package/get-application-summary-parents
/openapi/openapi_appdevelopement.json get /platform/appdev/apppackages/collection
Get a collection of application summaries.
# Get Package
Source: https://docs.kibocommerce.com/api-reference/package/get-package
/openapi/openapi_appdevelopement.json get /platform/appdev/apppackages/{applicationKey}
Retrieve a package and its associated application.
# Get Package Behaviors
Source: https://docs.kibocommerce.com/api-reference/package/get-package-behaviors
/openapi/openapi_appdevelopement.json get /platform/appdev/apppackages/{packageId}/behaviors
Retrieve a list of application package behaviors.
# Get Packages
Source: https://docs.kibocommerce.com/api-reference/package/get-packages
/openapi/openapi_appdevelopement.json get /platform/appdev/apppackages/applications/{applicationKey}/packages
Use this operation to retieve all packages for a given applicationKey.
# Update Package
Source: https://docs.kibocommerce.com/api-reference/package/update-package
/openapi/openapi_appdevelopement.json put /platform/appdev/apppackages/{applicationKey}
Update an application package.
# Update Package Behaviors
Source: https://docs.kibocommerce.com/api-reference/package/update-package-behaviors
/openapi/openapi_appdevelopement.json post /platform/appdev/apppackages/{packageId}/behaviors
Update a package's behaviors.
# Add Package To Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/add-package-to-package-consolidation
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/packages/{packageConsolidationId}/add/{packageId}
Add Package To Package Consolidation
# Add Tracking For Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/add-tracking-for-consolidation
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/packages/tracking
Add Tracking For Consolidation
# Add Tracking for Existing Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/add-tracking-for-existing-package-consolidation
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/packages/{packageConsolidationId}/tracking
Add Tracking For Consolidation
# Create Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/create-package-consolidation
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/consolidated/packages
Create Package Consolidation
# Delete Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/delete-package-consolidation
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/consolidated/packages/{packageConsolidationId}
Delete Package Consolidation
# Get Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/get-package-consolidation
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/consolidated/packages/{packageConsolidationId}
Get Package Consolidation
# Remove All Package Consolidations From Shipment
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/remove-all-package-consolidations-from-shipment
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/consolidated/packages/remove/bulk
Remove All Package Consolidations From Shipment
# Remove Shipment From Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/remove-shipment-from-package-consolidation
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/consolidated/packages/{packageConsolidationId}/remove
Remove Shipment From Package Consolidation
# Remove Specific Package from Package Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/remove-specific-package-from-package-consolidation
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/consolidated/packages/{packageConsolidationId}/remove/{packageId}
Remove Shipment From Package Consolidation
# Save Cartonization For Consolidation
Source: https://docs.kibocommerce.com/api-reference/packageconsolidation/save-cartonization-for-consolidation
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/consolidated/packages/cartonization/save
Save Cartonization For Consolidation
# Get Cart Packing Suggestions
Source: https://docs.kibocommerce.com/api-reference/packingsuggestion/get-cart-packing-suggestions
/openapi/openapi_fulfillment.json post /commerce/shipments/cartonization/packingSuggestions
Get Cart Packing Suggestions
# Get Cartonization Rejection Reasons
Source: https://docs.kibocommerce.com/api-reference/packingsuggestion/get-cartonization-rejection-reasons
/openapi/openapi_fulfillment.json get /commerce/shipments/cartonization/rejectionReasons
Get Cartonization Rejection Reasons
# Get Packing Suggestions
Source: https://docs.kibocommerce.com/api-reference/packingsuggestion/get-packing-suggestions
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/cartonization/packingSuggestions
Get Packing Suggestions
# Reject Packing Suggestion
Source: https://docs.kibocommerce.com/api-reference/packingsuggestion/reject-packing-suggestion
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/cartonization/reject
Reject Packing Suggestion
# Create a payment invoice
Source: https://docs.kibocommerce.com/api-reference/paymentinvoicemanagement/create-a-payment-invoice
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/invoice
Creates a payment invoice for the specified shipment
# Delete payment invoice
Source: https://docs.kibocommerce.com/api-reference/paymentinvoicemanagement/delete-payment-invoice
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/invoice
Removes the payment invoice from the specified shipment
# Get payment invoice
Source: https://docs.kibocommerce.com/api-reference/paymentinvoicemanagement/get-payment-invoice
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/invoice
Retrieves the payment invoice for the specified shipment
# Partially update a payment invoice
Source: https://docs.kibocommerce.com/api-reference/paymentinvoicemanagement/partially-update-a-payment-invoice
/openapi/openapi_fulfillment.json patch /commerce/shipments/{shipmentNumber}/invoice
Partially updates the payment invoice on the specified shipment
# Update a payment invoice
Source: https://docs.kibocommerce.com/api-reference/paymentinvoicemanagement/update-a-payment-invoice
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/invoice
Updates the payment invoice on the specified shipment
# Close Pick Wave
Source: https://docs.kibocommerce.com/api-reference/pickwave/close-pick-wave
/openapi/openapi_fulfillment.json put /commerce/pickwaves/{pickWaveNumber}/closed
Close an existing pick wave.
# Create Pick Wave
Source: https://docs.kibocommerce.com/api-reference/pickwave/create-pick-wave
/openapi/openapi_fulfillment.json post /commerce/pickwaves
Create a new pick wave.
# Create Rule Based Pick Wave
Source: https://docs.kibocommerce.com/api-reference/pickwave/create-rule-based-pick-wave
/openapi/openapi_fulfillment.json post /commerce/pickwaves/rule-based
Create Rule Based Pick Wave
# Get Open Pick Waves
Source: https://docs.kibocommerce.com/api-reference/pickwave/get-open-pick-waves
/openapi/openapi_fulfillment.json get /commerce/pickwaves/open/{fulfillmentLocationCode}
Get a list of open pick waves at a specific location.
# Get Pick Wave
Source: https://docs.kibocommerce.com/api-reference/pickwave/get-pick-wave
/openapi/openapi_fulfillment.json get /commerce/pickwaves/{pickWaveNumber}
Retrieve pick wave details by its ID number.
# Get Pick Wave Details
Source: https://docs.kibocommerce.com/api-reference/pickwave/get-pick-wave-details
/openapi/openapi_fulfillment.json get /commerce/pickwaves/{pickWaveNumber}/pickWaveDetails
Get pick wave details for a specific wave.
# Get Shipments In Pick Wave
Source: https://docs.kibocommerce.com/api-reference/pickwave/get-shipments-in-pick-wave
/openapi/openapi_fulfillment.json get /commerce/pickwaves/{pickWaveNumber}/shipments
Get a list of shipments included in a pick wave.
# Is Pick Wave Enabled
Source: https://docs.kibocommerce.com/api-reference/pickwave/is-pick-wave-enabled
/openapi/openapi_fulfillment.json get /commerce/pickwaves/enabled/{locationCode}
Is Pick Wave Enabled
# Render Order Pick Sheets
Source: https://docs.kibocommerce.com/api-reference/pickwave/render-order-pick-sheets
/openapi/openapi_fulfillment.json get /commerce/pickwaves/{pickWaveNumber}/order-pick-sheets/html
Render order pick sheets in HTML.
# Render Pick Wave
Source: https://docs.kibocommerce.com/api-reference/pickwave/render-pick-wave
/openapi/openapi_fulfillment.json get /commerce/pickwaves/{pickWaveNumber}/rendition/html
Render pick wave information in HTML.
# Evaluate Pick Wave Rules
Source: https://docs.kibocommerce.com/api-reference/pickwaveruleevaluate/evaluate-pick-wave-rules
/openapi/openapi_catalog_admin.json post /commerce/rules/pickwave/evaluate
Evaluate the pick wave rules for given products and shipment rules
# Create Pick Wave Rule
Source: https://docs.kibocommerce.com/api-reference/pickwaverules/create-pick-wave-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/pickwave
Creates a new pick wave rule.
# Delete Pick Wave Rule
Source: https://docs.kibocommerce.com/api-reference/pickwaverules/delete-pick-wave-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/pickwave/{code}
Deletes a pick wave rule by code.
# Get Pick Wave Rule by Code
Source: https://docs.kibocommerce.com/api-reference/pickwaverules/get-pick-wave-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/pickwave/{code}
Gets a pick wave rule details by code.
# Get Pick Wave Rules
Source: https://docs.kibocommerce.com/api-reference/pickwaverules/get-pick-wave-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/pickwave
Gets a collection of pick wave rules according to any specified filter criteria and sort options.
# Update Pick Wave Rule
Source: https://docs.kibocommerce.com/api-reference/pickwaverules/update-pick-wave-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/pickwave/{code}
Updates an existing pick wave rule.
# Add Price List Entry
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/add-price-list-entry
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/pricelists/{priceListCode}/entries
Adds an entry to a price list.
# Bulk Add Price List Entries
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/bulk-add-price-list-entries
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/pricelists/bulkaddentries
Add bulk price list entries. By default, any single error will cause the entire batch to fail. If desired, set allowPartialSuccess=true to allow valid entries to be completed even if others in the batch fail.
# Bulk Delete Price List Entries
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/bulk-delete-price-list-entries
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/pricelists/bulkdeleteentries
Deletes up to 5000 price list entries in bulk. By default, any single error will cause the entire batch to fail. If desired, set allowPartialSuccess=true to allow valid entries to be completed even if others in the batch fail.
# Bulk Update Price List Entries.
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/bulk-update-price-list-entries
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/pricelists/bulkupdateentries
Updates up to 5000 price list entries in bulk. By default, any single error will cause the entire batch to fail. If desired, set allowPartialSuccess=true to allow valid entries to be completed even if others in the batch fail.
This method performs an upsert, which will add missing entries if they do not exist. It can be used in place of Bulk Add Price List Entries to simplify application logic when the desired behavior is to update an entry or add the entry if it does not exist.
Disable the publishEvents parameter to prevent publishing the event related to updating price list entries in the system. Disabling this property helps you prevent performance delays if you expect the event to trigger the re-indexing of a large number of products, or if you want to postpone the operations of other applications and services listening for the event. Disable the invalidateCache parameter if you expect to encounter unacceptable performance hits related to clearing the cache for each product in the price list entries.
# Delete Price List Entry by Currency
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/delete-price-list-entry-by-currency
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/pricelists/{priceListCode}/entries/{productCode}/{currencyCode}
Deletes a price liste entry for a particular product and currency code.
# Get Price List Entries
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/get-price-list-entries
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/pricelists/{priceListCode}/entries
Retrieves the entries within a price list.
# Get Price List Entries by Currency
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/get-price-list-entries-by-currency
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/pricelists/{priceListCode}/entries/{productCode}/{currencyCode}
Retrieves price list entries for a particular product and currency code.
# Update Price List Entry by Currency
Source: https://docs.kibocommerce.com/api-reference/pricelistentries/update-price-list-entry-by-currency
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/pricelists/{priceListCode}/entries/{productCode}/{currencyCode}
Updates price list entry for a particular product and currency code.
# Add Price List
Source: https://docs.kibocommerce.com/api-reference/pricelists/add-price-list
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/pricelists
Creates a price list.
# Delete Price List
Source: https://docs.kibocommerce.com/api-reference/pricelists/delete-price-list
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/pricelists/{priceListCode}
Deletes a price list by its code.
# Get Price List
Source: https://docs.kibocommerce.com/api-reference/pricelists/get-price-list
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/pricelists/{priceListCode}
Retrieves a price list by its code.
# Get Price Lists
Source: https://docs.kibocommerce.com/api-reference/pricelists/get-price-lists
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/pricelists
Retrieve a list of all price lists.
# Update Price List
Source: https://docs.kibocommerce.com/api-reference/pricelists/update-price-list
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/pricelists/{priceListCode}
Updates a price list by its code.
# Add Localized Content
Source: https://docs.kibocommerce.com/api-reference/productattributes/add-localized-content
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/LocalizedContent
Creates product attribute localized content
# Add Product Attribute
Source: https://docs.kibocommerce.com/api-reference/productattributes/add-product-attribute
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/attributes
Create a new attribute. The attribute name, attribute type, input type, and data type are required. This current version of the Attributes API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access attribute data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Vocabulary Value
Source: https://docs.kibocommerce.com/api-reference/productattributes/add-vocabulary-value
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Creates product attribute vocabulary values
# Add Vocabulary Value Localized Content
Source: https://docs.kibocommerce.com/api-reference/productattributes/add-vocabulary-value-localized-content
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}/LocalizedContent
Creates vocabulary value localized content
# Delete Localized Content by Locale Code
Source: https://docs.kibocommerce.com/api-reference/productattributes/delete-localized-content-by-locale-code
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/LocalizedContent/{localeCode}
Deletes localized content by its locale code
# Delete Product Attribute
Source: https://docs.kibocommerce.com/api-reference/productattributes/delete-product-attribute
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}
Deletes a product attribute by its FQN
# Delete Vocabulary Value
Source: https://docs.kibocommerce.com/api-reference/productattributes/delete-vocabulary-value
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}
Deletes a product attribute vocabulary value
# Delete Vocabulary Value Localized Content by Locale Code
Source: https://docs.kibocommerce.com/api-reference/productattributes/delete-vocabulary-value-localized-content-by-locale-code
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}/LocalizedContent/{localeCode}
Delete product attribute vocabulary value localized content by its locale code
# Get Attribute Type Rules
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-attribute-type-rules
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/typerules
Retrieves a paged list of attribute type rules according to any specified filter criteria and sort options.
# Get Localized Content
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-localized-content
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/LocalizedContent
Retrieves product attribute localized content
# Get Localized Content by Locale Code
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-localized-content-by-locale-code
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/LocalizedContent/{localeCode}
Retrieves localized content by its locale code
# Get Product Attribute
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-product-attribute
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}
Retrieves a product attribute by its FQN. This current version of the Attributes API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access attribute data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Attributes.
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-product-attributes
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes
Get product attributes. This current version of the Attributes API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access attribute data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Vocabulary Value
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-vocabulary-value
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}
Retrieves a product attribute vocabulary value
# Get Vocabulary Value Localized Content
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-vocabulary-value-localized-content
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}/LocalizedContent
Retrieves vocabulary value localized content
# Get Vocabulary Value Localized Content by Locale Code
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-vocabulary-value-localized-content-by-locale-code
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}/LocalizedContent/{localeCode}
Get product attribute vocabulary value localized content by its locale code
# Get Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/productattributes/get-vocabulary-values
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Retrieves product attribute vocabulary values
# Update Localized Content
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-localized-content
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/LocalizedContent
Updates product attribute localized content
# Update Localized Content by Locale Code
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-localized-content-by-locale-code
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/LocalizedContent/{localeCode}
Updates localized content by its locale code
# Update Product Attribute
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-product-attribute
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}
Updates a product attribute by its FQN. This current version of the Attributes API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access attribute data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Vocabulary Value
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-vocabulary-value
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}
Updates a product attribute vocabulary value
# Update Vocabulary Value Localized Content
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-vocabulary-value-localized-content
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}/LocalizedContent
Updates vocabulary value localized content
# Update Vocabulary Value Localized Content by Locale Code
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-vocabulary-value-localized-content-by-locale-code
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues/{value}/LocalizedContent/{localeCode}
Update product attribute vocabulary value localized content by its locale code
# Update Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/productattributes/update-vocabulary-values
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Updates product attribute vocabulary values
# Add Extra Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productextras/add-extra-localized-delta-price
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}/Values/{value}/localizedDeltaPrice
Add a extra value localized delta price. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Product Extra
Source: https://docs.kibocommerce.com/api-reference/productextras/add-product-extra
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/Extras
Add extra. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Extra Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productextras/delete-extra-localized-delta-price
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}/Values/{value}/localizedDeltaPrice/{currencyCode}
Delete extra value localized delta price.
# Delete Product Extra
Source: https://docs.kibocommerce.com/api-reference/productextras/delete-product-extra
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}
Delete extra
# Get Extra Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productextras/get-extra-localized-delta-price
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}/Values/{value}/localizedDeltaPrice
Get extra value localized delta price. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Extra Localized Delta Price by Currency
Source: https://docs.kibocommerce.com/api-reference/productextras/get-extra-localized-delta-price-by-currency
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}/Values/{value}/localizedDeltaPrice/{currencyCode}
Get extra value localized delta price. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Extra
Source: https://docs.kibocommerce.com/api-reference/productextras/get-product-extra
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}
Get individual extra. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Extras
Source: https://docs.kibocommerce.com/api-reference/productextras/get-product-extras
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Extras
Get extras for the product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Extra Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productextras/update-extra-localized-delta-price
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}/Values/{value}/localizedDeltaPrice
Update extra value localized delta price. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Extra Localized Delta Price by Currency
Source: https://docs.kibocommerce.com/api-reference/productextras/update-extra-localized-delta-price-by-currency
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}/Values/{value}/localizedDeltaPrice/{currencyCode}
Update extra value localized delta price. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product Extra
Source: https://docs.kibocommerce.com/api-reference/productextras/update-product-extra
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Extras/{attributeFQN}
Update extra. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Product Option
Source: https://docs.kibocommerce.com/api-reference/productoptions/add-product-option
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/Options
Add an option to a product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Product Option
Source: https://docs.kibocommerce.com/api-reference/productoptions/delete-product-option
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/Options/{attributeFQN}
Delete a individual option for a product.
# Get Product Option
Source: https://docs.kibocommerce.com/api-reference/productoptions/get-product-option
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Options/{attributeFQN}
Get an individual option for a product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Options
Source: https://docs.kibocommerce.com/api-reference/productoptions/get-product-options
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Options
Get options for a product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product Option
Source: https://docs.kibocommerce.com/api-reference/productoptions/update-product-option
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Options/{attributeFQN}
Update an individual option for a product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Product Property
Source: https://docs.kibocommerce.com/api-reference/productproperties/add-product-property
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/Properties
Add a property to a product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Product Property Localized Content
Source: https://docs.kibocommerce.com/api-reference/productproperties/add-product-property-localized-content
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}/values/{value}/LocalizedContent
Add property value localized content.
# Delete Product Property
Source: https://docs.kibocommerce.com/api-reference/productproperties/delete-product-property
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}
Delete a specific product property.
# Delete Product Property Localized Content by Locale
Source: https://docs.kibocommerce.com/api-reference/productproperties/delete-product-property-localized-content-by-locale
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}/values/{value}/LocalizedContent/{localeCode}
Delete property value localized content by locale code.
# Get Product Properties
Source: https://docs.kibocommerce.com/api-reference/productproperties/get-product-properties
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Properties
Get properties for a product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Property
Source: https://docs.kibocommerce.com/api-reference/productproperties/get-product-property
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}
Get a specific product property. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Property Localized Content by Locale
Source: https://docs.kibocommerce.com/api-reference/productproperties/get-product-property-localized-content-by-locale
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}/values/{value}/LocalizedContent/{localeCode}
Get property value localized content.
# Get Product Property Localized Contents
Source: https://docs.kibocommerce.com/api-reference/productproperties/get-product-property-localized-contents
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}/values/{value}/LocalizedContent
Get property value localized content.
# Update Product Property
Source: https://docs.kibocommerce.com/api-reference/productproperties/update-product-property
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}
Update a specific product property. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product Property Localized Content
Source: https://docs.kibocommerce.com/api-reference/productproperties/update-product-property-localized-content
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}/values/{value}/LocalizedContent
Update property value localized content.
# Update Product Property Localized Content by Locale
Source: https://docs.kibocommerce.com/api-reference/productproperties/update-product-property-localized-content-by-locale
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/Properties/{attributeFQN}/values/{value}/LocalizedContent/{localeCode}
Update property value localized content by locale code.
# Assign Products to Publish Sets
Source: https://docs.kibocommerce.com/api-reference/productpublishing/assign-products-to-publish-sets
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/publishing/publishsets
Assign products to publish sets.
# Delete Publish Set
Source: https://docs.kibocommerce.com/api-reference/productpublishing/delete-publish-set
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/publishing/publishsets/{publishSetCode}
Removes all details about a PublishSet from the product service. If the discardDrafts param is true, it also deletes the product drafts.
# Get Publish Set
Source: https://docs.kibocommerce.com/api-reference/productpublishing/get-publish-set
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/publishing/publishsets/{publishSetCode}
Retrieves the details of a single PublishSet.
# Get Publish Sets
Source: https://docs.kibocommerce.com/api-reference/productpublishing/get-publish-sets
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/publishing/publishsets
Retrieves a list of PublishSets including the product counts.
# Publish Draft Products
Source: https://docs.kibocommerce.com/api-reference/productpublishing/publish-draft-products
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/publishing/publishdrafts
Publis draft products.
# Endpoint used to apply updates for product type
Source: https://docs.kibocommerce.com/api-reference/productquickedit/endpoint-used-to-apply-updates-for-product-type
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/quickedit/products/producttype
Endpoint used to apply updates for product type
# Quick Edit Product in Catalog
Source: https://docs.kibocommerce.com/api-reference/productquickedit/quick-edit-product-in-catalog
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/quickedit/products/productincatalog
Updates products in catalog through quick edit. Values will be
added, not replaced. The Quick Edit APIs are designed primarily for the Quick Edit UI. They are not advised for bulk product updates through a batch job. For efficiently updating your catalog through a batch job, use the Import Export APIs or the Catalog Administration APIs directly.
# Quick Edit Products
Source: https://docs.kibocommerce.com/api-reference/productquickedit/quick-edit-products
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/quickedit/products
Applies top level product updates. The Quick Edit APIs are designed primarily for the Quick Edit UI. They are not advised for bulk product updates through a batch job. For efficiently updating your catalog through a batch job, use the Import Export APIs or the Catalog Administration APIs directly.
# Quick Edit Properties
Source: https://docs.kibocommerce.com/api-reference/productquickedit/quick-edit-properties
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/quickedit/products/properties
Updates product properties through quick edits. Values will be added, not replaced. The Quick Edit APIs are designed primarily for the Quick Edit UI. They are not advised for bulk product updates through a batch job. For efficiently updating your catalog through a batch job, use the Import Export APIs or the Catalog Administration APIs directly.
# Preview Product Rule
Source: https://docs.kibocommerce.com/api-reference/productrule/preview-product-rule
/openapi/openapi_catalog_storefront.json post /commerce/rules/product/evaluate/preview
Previews a new product rule by searching for products in the admin index that meet the rule criteria
# Create Product Rule
Source: https://docs.kibocommerce.com/api-reference/productrules/create-product-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/product
Creates a new product rule.
# Delete Product Rules
Source: https://docs.kibocommerce.com/api-reference/productrules/delete-product-rules
/openapi/openapi_catalog_admin.json delete /commerce/rules/product/{code}
Delete a product rules.
# Get Expression Field Definition
Source: https://docs.kibocommerce.com/api-reference/productrules/get-expression-field-definition
/openapi/openapi_catalog_admin.json get /commerce/rules/product/product-rule-fields
Get expression field definition
# Get Product Rule by Code
Source: https://docs.kibocommerce.com/api-reference/productrules/get-product-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/product/{code}
Retrieves the details of a single product rule.
# Get Product Rules
Source: https://docs.kibocommerce.com/api-reference/productrules/get-product-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/product
Retrieves a list of product rules according to any specified filter criteria and sort options.
# Update Product Rule
Source: https://docs.kibocommerce.com/api-reference/productrules/update-product-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/product/{code}
Update an existing product rules.
# Validate Expression
Source: https://docs.kibocommerce.com/api-reference/productrules/validate-expression
/openapi/openapi_catalog_admin.json post /commerce/rules/product/validate
Validate the expression for a product rules
# Get Product Rule Usages
Source: https://docs.kibocommerce.com/api-reference/productruleusages/get-product-rule-usages
/openapi/openapi_catalog_admin.json get /commerce/rules/product/{code}/usages
Retrieves the usages of a product rule across rule types.
# Add Product
Source: https://docs.kibocommerce.com/api-reference/products/add-product
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products
Creates a new product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Add Product in Catalogs
Source: https://docs.kibocommerce.com/api-reference/products/add-product-in-catalogs
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/ProductInCatalogs
Add a product to catalogs. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Change product type.
Source: https://docs.kibocommerce.com/api-reference/products/change-product-type
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/changeproducttype
Change a product's product type. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Product
Source: https://docs.kibocommerce.com/api-reference/products/delete-product
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}
Deletes the product specified by its product code.
# Delete Product in Catalog
Source: https://docs.kibocommerce.com/api-reference/products/delete-product-in-catalog
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/ProductInCatalogs/{catalogId}
Delete a product in a particular catalog.
# Get Product
Source: https://docs.kibocommerce.com/api-reference/products/get-product
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}
Retrieves details about a product based on the specified response group. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product in Catalog
Source: https://docs.kibocommerce.com/api-reference/products/get-product-in-catalog
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/ProductInCatalogs/{catalogId}
Retrieves a product in a particular catalog. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Products
Source: https://docs.kibocommerce.com/api-reference/products/get-products
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products
Retrieves a list of products according to any specified filter criteria and sort options. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Products in Catalogs
Source: https://docs.kibocommerce.com/api-reference/products/get-products-in-catalogs
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/ProductInCatalogs
Retrieve products in catalogs. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Secure Item Discounts
Source: https://docs.kibocommerce.com/api-reference/products/get-secure-item-discounts
/openapi/openapi_pricing.json post /commerce/catalog/storefront/discounts/secure/products
Retrieves a list of non-public discounts according to specified filter criteria. These can only be accessed by users with the Discount Read behavior.
# Get Secure Item Discounts by Product
Source: https://docs.kibocommerce.com/api-reference/products/get-secure-item-discounts-by-product
/openapi/openapi_pricing.json get /commerce/catalog/storefront/discounts/secure/products/{productCode}
Retrieves a list of non-public discounts according to specified filter criteria. These can only be accessed by users with the Discount Read behavior.
# Get Secure Order Discounts
Source: https://docs.kibocommerce.com/api-reference/products/get-secure-order-discounts
/openapi/openapi_pricing.json post /commerce/catalog/storefront/discounts/secure/orders
Retrieves a list of non-public discounts according to specified filter criteria. These can only be accessed by users with the Discount Read behavior.
# Rename Product Codes
Source: https://docs.kibocommerce.com/api-reference/products/rename-product-codes
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/Actions/RenameProductCodes
Action that allows productCodes to be renamed.
# Update Product
Source: https://docs.kibocommerce.com/api-reference/products/update-product
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}
Modifies an existing product. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product in Catalog
Source: https://docs.kibocommerce.com/api-reference/products/update-product-in-catalog
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/ProductInCatalogs/{catalogId}
Update a product in a particular catalog. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product in Catalogs
Source: https://docs.kibocommerce.com/api-reference/products/update-product-in-catalogs
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/ProductInCatalogs
Updates existing products across your catalogs. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Suggested Search Terms
Source: https://docs.kibocommerce.com/api-reference/productsearch/get-suggested-search-terms
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/suggest
Suggests possible search terms as the shopper enters search text. In Unified Commerce, a Suggest2 API exists that returns results based on the returnFields option defined in the search settings. The same request structure and response as documented here is supported by both the /suggest and /suggest2 API endpoints, so either one can be used for this purpose with the same data.
# Gets Random Access Cursors
Source: https://docs.kibocommerce.com/api-reference/productsearch/gets-random-access-cursors
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/randomAccessCursor
Generate a list of cursors that then allows you to retrieve all products with efficient deep paging.\r\n\t\t\tOptionally provide a query and/or filter to generate a cursor for a subset of products.\r\n\t\t\tAfter retrieving the cursor, provide a cursorMark to the cursorMark argument of the /search or /getProducts operations.\r\n\t\t\tYou may provide cursorMarks in any order or even in parallel operations.
# Gets Suggested Search Terms 2
Source: https://docs.kibocommerce.com/api-reference/productsearch/gets-suggested-search-terms-2
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/suggest2
Suggests possible search terms as the shopper enters search text. In Unified Commerce, a Suggest2 API exists that returns results based on the returnFields option defined in the search settings. The same request structure and response as documented here is supported by both the /suggest and /suggest2 API endpoints, so either one can be used for this purpose with the same data.
# Search Debug
Source: https://docs.kibocommerce.com/api-reference/productsearch/search-debug
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/searchDebug
Searches the items displayed on the storefront for products or product options that the shopper types in a search query. Used for debugging.
# Search Products
Source: https://docs.kibocommerce.com/api-reference/productsearch/search-products
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/search
Searches the categories displayed on the storefront for products or product options that the shopper types in a search query.
# Search Suggestion Debug
Source: https://docs.kibocommerce.com/api-reference/productsearch/search-suggestion-debug
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/suggestdebug
Comma delimited list of suggestion groups that should be returned. The default is everything. e.g. categories, products.
# Site Search
Source: https://docs.kibocommerce.com/api-reference/productsearch/site-search
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/siteSearch
Searches the items displayed on the storefront.
# Type Ahead Search
Source: https://docs.kibocommerce.com/api-reference/productsearch/type-ahead-search
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/productsearch/visualsearch
Searches the items displayed on the storefront.
# Add Product
Source: https://docs.kibocommerce.com/api-reference/productsv1/add-product
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/productsV1
Creates a new product. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Add Product in Catalogs
Source: https://docs.kibocommerce.com/api-reference/productsv1/add-product-in-catalogs
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/productsV1/{productCode}/ProductInCatalogs
Adds a new product to your catalogs. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Get Product
Source: https://docs.kibocommerce.com/api-reference/productsv1/get-product
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/productsV1/{productCode}
Retrieves details about a product based on the specified response group. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Get Product in Catalog
Source: https://docs.kibocommerce.com/api-reference/productsv1/get-product-in-catalog
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/productsV1/{productCode}/ProductInCatalogs/{catalogId}
Retrieves a product in a particular catalog. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Get Products
Source: https://docs.kibocommerce.com/api-reference/productsv1/get-products
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/productsV1
Retrieves a list of products according to any specified filter criteria and sort options. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Get Products in Catalogs
Source: https://docs.kibocommerce.com/api-reference/productsv1/get-products-in-catalogs
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/productsV1/{productCode}/ProductInCatalogs
Retrieve existing products across all catalog. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Update Product
Source: https://docs.kibocommerce.com/api-reference/productsv1/update-product
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/productsV1/{productCode}
Modifies an existing product. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Update Product in Catalog
Source: https://docs.kibocommerce.com/api-reference/productsv1/update-product-in-catalog
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/productsV1/{productCode}/ProductInCatalogs/{catalogId}
Updates products in a particular catalog. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Update Products in Catalogs
Source: https://docs.kibocommerce.com/api-reference/productsv1/update-products-in-catalogs
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/productsV1/{productCode}/ProductInCatalogs
Updates existing products across your catalogs. This is the legacy version of the Products API, which allows you to access product data that hasn't yet been rewritten to the newer API model with localizedContent. If possible, Kibo recommends calling the /products endpoint with an x-api-version header set to "1" instead of using this V1 endpoint (as it may be deprecated at some point). This is only necessary if you upgraded your implementation to use the new API version by default to support multi-locale catalogs.
# Add Product Type
Source: https://docs.kibocommerce.com/api-reference/producttypes/add-product-type
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/producttypes
Get product type by Id.
# Add Product Type Extra
Source: https://docs.kibocommerce.com/api-reference/producttypes/add-product-type-extra
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Extras
Add a product type extra.
# Add Product Type Option
Source: https://docs.kibocommerce.com/api-reference/producttypes/add-product-type-option
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Options
Add a product option to a product type.
# Add Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/add-product-type-property
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Properties
Add a property to a product type.
# Add Variant Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/add-variant-product-type-property
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/VariantProperties
Add a variant property to a product type.
# Delete Product Type
Source: https://docs.kibocommerce.com/api-reference/producttypes/delete-product-type
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}
Delete product type.
# Delete Product Type Extra
Source: https://docs.kibocommerce.com/api-reference/producttypes/delete-product-type-extra
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Extras/{attributeFQN}
Delete a product type extra.
# Delete Product Type Option
Source: https://docs.kibocommerce.com/api-reference/producttypes/delete-product-type-option
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Options/{attributeFQN}
Delete a product type option by its FQN.
# Delete Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/delete-product-type-property
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Properties/{attributeFQN}
Delete a product type property by its FQN.
# Delete Variant Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/delete-variant-product-type-property
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/VariantProperties/{attributeFQN}
Delete a variant property by its FQN.
# Generate Product Variations
Source: https://docs.kibocommerce.com/api-reference/producttypes/generate-product-variations
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/variations
Generate product variations for a product type.
# Get Product Type
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}
Get product type by Id.
# Get Product Type Extra
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type-extra
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Extras/{attributeFQN}
Get a product type extra.
# Get Product Type Extras
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type-extras
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Extras
Get a list of product type extras.
# Get Product Type Option
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type-option
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Options/{attributeFQN}
Get an individual product type option by its FQN.
# Get Product Type Options
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type-options
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Options
Get options for the product type.
# Get Product Type Properties
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type-properties
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Properties
Get properties of a product type.
# Get Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-type-property
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Properties/{attributeFQN}
Get a product type property by its FQN.
# Get Product Types
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-product-types
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes
Retrieves a list of product types according to any specified filter criteria and sort options.
# Get Variant Product Type Properties
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-variant-product-type-properties
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/VariantProperties
Get variant properties for a product type.
# Get Variant Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/get-variant-product-type-property
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/VariantProperties/{attributeFQN}
Get a variant property by its FQN.
# Update Product Type
Source: https://docs.kibocommerce.com/api-reference/producttypes/update-product-type
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}
Update product type.
# Update Product Type Extra
Source: https://docs.kibocommerce.com/api-reference/producttypes/update-product-type-extra
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Extras/{attributeFQN}
Update a product type extra
# Update Product Type Option
Source: https://docs.kibocommerce.com/api-reference/producttypes/update-product-type-option
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Options/{attributeFQN}
Update a product option type by its FQN.
# Update Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/update-product-type-property
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/Properties/{attributeFQN}
Update a product type property by its FQN.
# Update Variant Product Type Property
Source: https://docs.kibocommerce.com/api-reference/producttypes/update-variant-product-type-property
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/attributedefinition/producttypes/{productTypeId}/VariantProperties/{attributeFQN}
Update a variant property by its FQN.
# Add Product Variation Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productvariations/add-product-variation-localized-delta-price
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedDeltaPrice
Add a product variation localized delta price.
# Add Product Variation Localized Price
Source: https://docs.kibocommerce.com/api-reference/productvariations/add-product-variation-localized-price
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedPrice
Add a product variation localized price.
# Delete Product Variation
Source: https://docs.kibocommerce.com/api-reference/productvariations/delete-product-variation
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/variations/{variationKey}
Deletes an existing product variation. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Product Variation Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productvariations/delete-product-variation-localized-delta-price
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedDeltaPrice/{currencyCode}
Delete the product variation localized delta prices for a specific currency.
# Delete Product Variation Localized Price by Currency
Source: https://docs.kibocommerce.com/api-reference/productvariations/delete-product-variation-localized-price-by-currency
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedPrice/{currencyCode}
Delete the product variation localized price for a specific currency code.
# Get Product Variation
Source: https://docs.kibocommerce.com/api-reference/productvariations/get-product-variation
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/variations/{variationKey}
Retrieves an existing product variation for a specific product and variation key. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Get Product Variation Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productvariations/get-product-variation-localized-delta-price
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedDeltaPrice/{currencyCode}
Retrieve the product variation localized delta prices for a specific currency.
# Get Product Variation Localized Delta Prices
Source: https://docs.kibocommerce.com/api-reference/productvariations/get-product-variation-localized-delta-prices
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedDeltaPrice
Get product variation localized delta prices.
# Get Product Variation Localized Price by Currency
Source: https://docs.kibocommerce.com/api-reference/productvariations/get-product-variation-localized-price-by-currency
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedPrice/{currencyCode}
Get the product variation localized price for a specific currency code.
# Get Product Variation Localized Prices
Source: https://docs.kibocommerce.com/api-reference/productvariations/get-product-variation-localized-prices
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedPrice
Get product variation localized prices.
# Get Product Variations
Source: https://docs.kibocommerce.com/api-reference/productvariations/get-product-variations
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/products/{productCode}/variations
Retrieves a paged list of product variations for a specific product according to any specified filter criteria and sort options. This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product Variation
Source: https://docs.kibocommerce.com/api-reference/productvariations/update-product-variation
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/variations/{variationKey}
Modifies an existing product variation specified by its variation key. Typically used to change the price or inventory count of an existing product variation. Read-only options are ignored.
This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Update Product Variation Localized Delta Price
Source: https://docs.kibocommerce.com/api-reference/productvariations/update-product-variation-localized-delta-price
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedDeltaPrice/{currencyCode}
Update the product variation localized delta prices for a specific currency.
# Update Product Variation Localized Delta Prices
Source: https://docs.kibocommerce.com/api-reference/productvariations/update-product-variation-localized-delta-prices
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedDeltaPrice
Update product variation localized delta prices.
# Update Product Variation Localized Price by Currency
Source: https://docs.kibocommerce.com/api-reference/productvariations/update-product-variation-localized-price-by-currency
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedPrice/{currencyCode}
Update the product variation localized price for a specific currency code.
# Update Product Variation Localized Prices
Source: https://docs.kibocommerce.com/api-reference/productvariations/update-product-variation-localized-prices
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/variations/{variationKey}/localizedPrice
Update product variation localized prices
# Update Product Variations
Source: https://docs.kibocommerce.com/api-reference/productvariations/update-product-variations
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/products/{productCode}/variations
Modifies multiple product variations for an existing product in one operation. Use to set IsActive to true for variations that represent configurable options for sale. Also use to change the price or inventory count of an existing product variation. Read-only options are ignored.
This current version of the Products API includes localizedContent to support multi-locale catalogs, which was not present in the previous API model. If you were a client prior to May 2024 and have upgraded your implementation to support this feature, you can still access product data that has not yet been rewritten to the new model by providing an x-api-version header set to "1".
# Delete Package File
Source: https://docs.kibocommerce.com/api-reference/publicapplication/delete-package-file
/openapi/openapi_appdevelopement.json delete /platform/developer/packages/{applicationKey}/files/{filepath}
Delete an existing package file.
# Get App Package Names
Source: https://docs.kibocommerce.com/api-reference/publicapplication/get-app-package-names
/openapi/openapi_appdevelopement.json get /platform/developer/applications/{applicationKey}/packagenames
Retrieve a list of application package names.
# Get App Versions
Source: https://docs.kibocommerce.com/api-reference/publicapplication/get-app-versions
/openapi/openapi_appdevelopement.json get /platform/developer/applications/versions/{nsAndAppId}
Retrieve a list of application versions.
# Get Package File Metadata
Source: https://docs.kibocommerce.com/api-reference/publicapplication/get-package-file-metadata
/openapi/openapi_appdevelopement.json get /platform/developer/packages/{applicationKey}/filemetadata/{filepath}
Retrieve all package file metadata.
# Get Package Metadata
Source: https://docs.kibocommerce.com/api-reference/publicapplication/get-package-metadata
/openapi/openapi_appdevelopement.json get /platform/developer/packages/{applicationKey}/metadata
Retrieve application package metadata.
# Rename Package File
Source: https://docs.kibocommerce.com/api-reference/publicapplication/rename-package-file
/openapi/openapi_appdevelopement.json post /platform/developer/packages/{applicationKey}/files_rename
Rename a package file.
# Upsert Package File
Source: https://docs.kibocommerce.com/api-reference/publicapplication/upsert-package-file
/openapi/openapi_appdevelopement.json post /platform/developer/packages/{applicationKey}/files/{filepath}
Update and replace a package file.
# Discard Drafts
Source: https://docs.kibocommerce.com/api-reference/publishing/discard-drafts
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/publishing/discarddrafts
Deletes the draft version of product changes (pending product changes) for each product code.
# Create Purchase Limit Rule
Source: https://docs.kibocommerce.com/api-reference/purchaselimitrules/create-purchase-limit-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/purchaselimit
Creates a new purchase limit rule.
# Delete Purchase Limit Rule
Source: https://docs.kibocommerce.com/api-reference/purchaselimitrules/delete-purchase-limit-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/purchaselimit/{code}
Deletes a purchase limit rule by code.
# Get Purchase Limit Rule by Code
Source: https://docs.kibocommerce.com/api-reference/purchaselimitrules/get-purchase-limit-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/purchaselimit/{code}
Gets purchase limit rule details by code.
# Get Purchase Limit Rules
Source: https://docs.kibocommerce.com/api-reference/purchaselimitrules/get-purchase-limit-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/purchaselimit
Gets a collection of purchase limit rules according to any specified filter criteria and sort options.
# Update Purchase Limit Rule
Source: https://docs.kibocommerce.com/api-reference/purchaselimitrules/update-purchase-limit-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/purchaselimit/{code}
Updates an existing purchase limit rule.
# Update Purchase Limit Rule Rank
Source: https://docs.kibocommerce.com/api-reference/purchaselimitrules/update-purchase-limit-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/purchaselimit/{code}/rank
Updates the rank for a purchase limit rule and rearranges the ranks of all other rules accordingly.
# Add Item To Quote
Source: https://docs.kibocommerce.com/api-reference/quote/add-item-to-quote
/openapi/openapi_commerce.json post /commerce/quotes/{quoteId}/items
Adds an item to the Quote of the current shopper.
# Apply Coupon
Source: https://docs.kibocommerce.com/api-reference/quote/apply-coupon
/openapi/openapi_commerce.json put /commerce/quotes/{quoteId}/coupons/{couponCode}
Apply a coupon to the quote.
# Copy quote
Source: https://docs.kibocommerce.com/api-reference/quote/copy-quote
/openapi/openapi_commerce.json post /commerce/quotes/{quoteId}/copy
Copies a source quote and creates a new quote.
# Create Comment
Source: https://docs.kibocommerce.com/api-reference/quote/create-comment
/openapi/openapi_commerce.json post /commerce/quotes/{quoteId}/comments
Create a comment on a specific quote.
# Create quote
Source: https://docs.kibocommerce.com/api-reference/quote/create-quote
/openapi/openapi_commerce.json post /commerce/quotes
Creates a new B2B quote. With quotes, buyers can request an estimate based on a list of products they are interested in. Sellers can evaluate these requests and make adjustments to pricing, discounts, or other criteria before the buyer chooses whether to place the order or not. Comments can be left on the quote to communicate during this negotiation process.
# Create Quote From Cart
Source: https://docs.kibocommerce.com/api-reference/quote/create-quote-from-cart
/openapi/openapi_commerce.json post /commerce/quotes/create/{cartId}
Creates a new quote from an existing cart, that is, when the customer chooses to initiate quote.
# Delete Quote
Source: https://docs.kibocommerce.com/api-reference/quote/delete-quote
/openapi/openapi_commerce.json delete /commerce/quotes/{quoteId}
Deletes the quote specified by quote Id.
# Delete Quote Item
Source: https://docs.kibocommerce.com/api-reference/quote/delete-quote-item
/openapi/openapi_commerce.json delete /commerce/quotes/{quoteId}/items/{quoteItemId}
Delete Quote Item
# Get All Quote Comments
Source: https://docs.kibocommerce.com/api-reference/quote/get-all-quote-comments
/openapi/openapi_commerce.json get /commerce/quotes/{quoteId}/comments
Retrieves all quote comments from an quote.
# Get Available Shipping Methods
Source: https://docs.kibocommerce.com/api-reference/quote/get-available-shipping-methods
/openapi/openapi_commerce.json get /commerce/quotes/{quoteId}/shippingMethods
Retrieves available shipping methods for quotes. Typically used to display available shipping method options on the quote page.
# Get Quote
Source: https://docs.kibocommerce.com/api-reference/quote/get-quote
/openapi/openapi_commerce.json get /commerce/quotes/{quoteId}
Retrieves the details of a quote specified by the quote ID.
# Get Quote By Name
Source: https://docs.kibocommerce.com/api-reference/quote/get-quote-by-name
/openapi/openapi_commerce.json get /commerce/quotes/customers/{customerAccountId}/{quoteName}
Retrieves quote by its name.
# Get Quote Comment
Source: https://docs.kibocommerce.com/api-reference/quote/get-quote-comment
/openapi/openapi_commerce.json get /commerce/quotes/{quoteId}/comments/{commentId}
Retrieves a specific quote comment from an quote.
# Get Quote Item
Source: https://docs.kibocommerce.com/api-reference/quote/get-quote-item
/openapi/openapi_commerce.json get /commerce/quotes/{quoteId}/items/{quoteItemId}
Retrieves an individual Quote item from a Quote specified by quote Id and quote item Id.
# Get Quote Items
Source: https://docs.kibocommerce.com/api-reference/quote/get-quote-items
/openapi/openapi_commerce.json get /commerce/quotes/{quoteId}/items
Returns a listing of Quotes
# Get Quote Items By Quote Name
Source: https://docs.kibocommerce.com/api-reference/quote/get-quote-items-by-quote-name
/openapi/openapi_commerce.json get /commerce/quotes/customers/{customerAccountId}/{quoteName}/items
Gets the quote specified by the quote name.
# Get Quotes
Source: https://docs.kibocommerce.com/api-reference/quote/get-quotes
/openapi/openapi_commerce.json get /commerce/quotes
Retrieves a list of B2B Quotes according to any specified filter criteria and sort options.
# Remove Coupon
Source: https://docs.kibocommerce.com/api-reference/quote/remove-coupon
/openapi/openapi_commerce.json delete /commerce/quotes/{quoteId}/coupons/{couponCode}
Removes a coupon that had been previously applied to the Quote.
# Remove Coupons
Source: https://docs.kibocommerce.com/api-reference/quote/remove-coupons
/openapi/openapi_commerce.json delete /commerce/quotes/{quoteId}/coupons
Removes all coupons that had been previously applied to the Quote.
# Send Quote Email
Source: https://docs.kibocommerce.com/api-reference/quote/send-quote-email
/openapi/openapi_commerce.json post /commerce/quotes/{quoteId}/email
Send Quote email to provided email addresses or email mentioned on the quote.
# Update Fulfillment Info
Source: https://docs.kibocommerce.com/api-reference/quote/update-fulfillment-info
/openapi/openapi_commerce.json post /commerce/quotes/{quoteId}/fulfillmentInfo
Updates the fulfillmentInfo of quote.
# Update Item Fulfillment
Source: https://docs.kibocommerce.com/api-reference/quote/update-item-fulfillment
/openapi/openapi_commerce.json put /commerce/quotes/{quoteId}/items/{quoteItemId}/fulfillment
Updates the fulfillment method and/or location of an individual quote item in the quote.
# Update Item Product Price
Source: https://docs.kibocommerce.com/api-reference/quote/update-item-product-price
/openapi/openapi_commerce.json put /commerce/quotes/{quoteId}/items/{quoteItemId}/price/{price}
Overrides the price of an individual quote item.
# Update Item Quantity
Source: https://docs.kibocommerce.com/api-reference/quote/update-item-quantity
/openapi/openapi_commerce.json put /commerce/quotes/{quoteId}/items/{quoteItemId}/quantity/{quantity}
Updates the quantity of an individual Quote item.
# Update Quote
Source: https://docs.kibocommerce.com/api-reference/quote/update-quote
/openapi/openapi_commerce.json put /commerce/quotes/{quoteId}
Updates a quote specified by quote Id.
# Update Quote Adjustments
Source: https://docs.kibocommerce.com/api-reference/quote/update-quote-adjustments
/openapi/openapi_commerce.json post /commerce/quotes/{quoteId}/adjustments
Set product, shipping, and handling adjustments on the specified quote.
# Get recommended shipping rates
Source: https://docs.kibocommerce.com/api-reference/rateshopping/get-recommended-shipping-rates
/openapi/openapi_fulfillment.json post /commerce/rate-shopping/recommend
Retrieves recommended shipping rates from configured carriers for the provided shipment details
# Trigger
Source: https://docs.kibocommerce.com/api-reference/rebalance/trigger
/openapi/openapi_fulfillment.json post /commerce/fulfillment/rebalancer/runs
Trigger
# Get Current Ranked Shipments
Source: https://docs.kibocommerce.com/api-reference/rebalanceread/get-current-ranked-shipments
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/runs/current/shipments
Get Current Ranked Shipments
# Get Current Run
Source: https://docs.kibocommerce.com/api-reference/rebalanceread/get-current-run
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/runs/current
Get Current Run
# Get Ranked Shipments
Source: https://docs.kibocommerce.com/api-reference/rebalanceread/get-ranked-shipments
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/runs/{jobId}/shipments
Get Ranked Shipments
# Get Reservation Detail
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/get-reservation-detail
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/reservations/{reservationId}
Get Reservation Detail
# Get Reservation Sourcing
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/get-reservation-sourcing
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/reservations/{reservationId}/sourcing
Get Reservation Sourcing
# Get Run Detail
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/get-run-detail
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}
Get Run Detail
# Get Shipment Detail
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/get-shipment-detail
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/shipments/{shipmentNumber}
Get Shipment Detail
# List All Rules
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-all-rules
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/rules
List All Rules
# List Backorder Rules
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-backorder-rules
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/backorder-rules
List Backorder Rules
# List Changes
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-changes
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/changes
List Changes
# List Current Backorder Shipments
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-current-backorder-shipments
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/backorder-shipments
List Current Backorder Shipments
# List Future Rules
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-future-rules
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/rules
List Future Rules
# List Reservation Lines
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-reservation-lines
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/reservations/{reservationId}/lines
List Reservation Lines
# List Reservations
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-reservations
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/reservations
List Reservations
# List Runs
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-runs
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs
List Runs
# List Runs For Shipment
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-runs-for-shipment
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/shipments/{shipmentNumber}/runs
List Runs For Shipment
# List Shipment Lines
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-shipment-lines
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/shipments/{shipmentNumber}/lines
List Shipment Lines
# List Shipments
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/list-shipments
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/{runId}/shipments
List Shipments
# Saved Filters
Source: https://docs.kibocommerce.com/api-reference/rebalancerrunaudit/saved-filters
/openapi/openapi_fulfillment.json get /commerce/fulfillment/rebalancer/audit/runs/saved-filters
Saved Filters
# Evaluate Backorder Rebalancing
Source: https://docs.kibocommerce.com/api-reference/rebalanceruleevaluation/evaluate-backorder-rebalancing
/openapi/openapi_fulfillment.json post /commerce/rebalance/evaluate/backorder
Evaluate Backorder Rebalancing
# Evaluate Future Rebalancing
Source: https://docs.kibocommerce.com/api-reference/rebalanceruleevaluation/evaluate-future-rebalancing
/openapi/openapi_fulfillment.json post /commerce/rebalance/evaluate/future
Evaluate Future Rebalancing
# Execute Redaction
Source: https://docs.kibocommerce.com/api-reference/redaction/execute-redaction
/openapi/openapi_gdpr.json post /platform/data/redaction/execute/{reportId}
Executes an approved draft redaction report. This action is irreversible — it permanently removes or overwrites all PII identified in the report. The report status changes from Draft to Executed and operationLog is populated. See the Redaction Services Developer Guide for the complete workflow and warnings.
# Generate Redaction Report
Source: https://docs.kibocommerce.com/api-reference/redaction/generate-redaction-report
/openapi/openapi_gdpr.json post /platform/data/redaction/report
Creates a draft redaction report by scanning tenant data for all PII associated with the specified data subject. No data is modified at this stage. Review the returned report before executing. See the Redaction Services Developer Guide for the complete two-phase workflow.
# Get Redaction Report
Source: https://docs.kibocommerce.com/api-reference/redaction/get-redaction-report
/openapi/openapi_gdpr.json get /platform/data/redaction/report/{reportId}
Retrieves a single redaction report by ID. Returns the full report including affectedEntities and, after execution, the operationLog. Use this to review a draft before executing or to audit a completed redaction. See the Redaction Services Developer Guide for field descriptions.
# List Redaction Reports
Source: https://docs.kibocommerce.com/api-reference/redaction/list-redaction-reports
/openapi/openapi_gdpr.json get /platform/data/redaction/report
Lists redaction reports for the tenant, with optional filtering by status (Draft or Executed) and date range. Returns summary objects without affectedEntities or operationLog; retrieve individual reports by ID for full details. See the Redaction Services Developer Guide for auditing guidance.
# GET /call-offs/{callOffOrderId}/runs — every audit record that touched
Source: https://docs.kibocommerce.com/api-reference/releaserules/get-call-offs-runs-—-every-audit-record-that-touched
/openapi/openapi_commerce.json get /commerce/jobs/release-rules/call-offs/{callOffOrderId}/runs
a given CallOffOrder, most recent first.
# GET /rules/{ruleId}/recent — records for one rule within an optional
Source: https://docs.kibocommerce.com/api-reference/releaserules/get-rules-recent-—-records-for-one-rule-within-an-optional
/openapi/openapi_commerce.json get /commerce/jobs/release-rules/rules/{ruleId}/recent
date range, most recent first.
# GET /runs/{runId} — every audit record produced by a single run, in
Source: https://docs.kibocommerce.com/api-reference/releaserules/get-runs-—-every-audit-record-produced-by-a-single-run-in
/openapi/openapi_commerce.json get /commerce/jobs/release-rules/runs/{runId}
chronological order. Drill-down from the runs list.
# GET /runs — per-run summaries (aggregated outcome counts) within an
Source: https://docs.kibocommerce.com/api-reference/releaserules/get-runs-—-per-run-summaries-aggregated-outcome-counts-within-an
/openapi/openapi_commerce.json get /commerce/jobs/release-rules/runs
optional date range; most-recent run first.
# Triggers an on-demand Release Rules Engine run for the caller's
Source: https://docs.kibocommerce.com/api-reference/releaserules/triggers-an-on-demand-release-rules-engine-run-for-the-callers
/openapi/openapi_commerce.json post /commerce/jobs/release-rules/run
{tenantId, siteId}.
Default behavior (`sync=false`): publishes the same
`ReleaseRuleEngineStart` event the cron scheduler does, returns
HTTP 202 + JobKey within ~200ms p95.
Debug bypass (`?sync=true`): SKIPS kibo.jobs + RabbitMQ +
MassTransit consumer entirely. Executes the orchestrator inline.
# Render Order Summary
Source: https://docs.kibocommerce.com/api-reference/rendition/render-order-summary
/openapi/openapi_fulfillment.json get /commerce/fulfillment/orders/{orderId}/summary/html
Render an order summary in HTML.
# Render Return Receipt
Source: https://docs.kibocommerce.com/api-reference/rendition/render-return-receipt
/openapi/openapi_fulfillment.json get /commerce/fulfillment/returns/{returnId}/receipt/html
Render a return receipt in HTML.
# Activate Reservation
Source: https://docs.kibocommerce.com/api-reference/reservation/activate-reservation
/openapi/openapi_reservation.json put /commerce/reservation/{reservationId}/activate
Activate a reservation. Kibo does not recommend using this API, as it is intended for internal use.
# Add Item
Source: https://docs.kibocommerce.com/api-reference/reservation/add-item
/openapi/openapi_reservation.json post /commerce/reservation/{reservationId}/items
Add an item to a reservation. Set runSynchronous to "true" to perform this call synchronously with better performance time.
# Close Reservation
Source: https://docs.kibocommerce.com/api-reference/reservation/close-reservation
/openapi/openapi_reservation.json put /commerce/reservation/{reservationId}/close
Close a reservation. Kibo does not recommend using this API, as it is intended for internal use.
# Convert To Order Reservation
Source: https://docs.kibocommerce.com/api-reference/reservation/convert-to-order-reservation
/openapi/openapi_reservation.json post /commerce/reservation/{reservationId}/converttoorderreservation
Converts a reservation associated with a cart to an order reservation.
# Create Reservation
Source: https://docs.kibocommerce.com/api-reference/reservation/create-reservation
/openapi/openapi_reservation.json post /commerce/reservation
Creates a new reservation. Set runSynchronous to "true" to perform this call synchronously with better performance time.
# Delete Reservation
Source: https://docs.kibocommerce.com/api-reference/reservation/delete-reservation
/openapi/openapi_reservation.json delete /commerce/reservation/{reservationId}
Delete a reservation. Set runSynchronous to "true" to perform this call synchronously with better performance time.
# Get Allocation Status
Source: https://docs.kibocommerce.com/api-reference/reservation/get-allocation-status
/openapi/openapi_reservation.json get /commerce/reservation/{reservationId}/getallocationstatus
Get Allocation Status
# Get Reservation By Id
Source: https://docs.kibocommerce.com/api-reference/reservation/get-reservation-by-id
/openapi/openapi_reservation.json get /commerce/reservation/{reservationId}
Get a specific reservation by its ID.
# Get Reservation Summary
Source: https://docs.kibocommerce.com/api-reference/reservation/get-reservation-summary
/openapi/openapi_reservation.json get /commerce/reservation/summary
Get Reservation Summary
# Get Reservations
Source: https://docs.kibocommerce.com/api-reference/reservation/get-reservations
/openapi/openapi_reservation.json get /commerce/reservation
Get all reservations.
# Get Reservations By Cart Id
Source: https://docs.kibocommerce.com/api-reference/reservation/get-reservations-by-cart-id
/openapi/openapi_reservation.json get /commerce/reservation/cart/{cartId}
Get reservations based on the Cart ID.
# Remove Item
Source: https://docs.kibocommerce.com/api-reference/reservation/remove-item
/openapi/openapi_reservation.json delete /commerce/reservation/{reservationId}/items/{reservationItemId}
Remove an item from a reservation.
# Update Item Quantity
Source: https://docs.kibocommerce.com/api-reference/reservation/update-item-quantity
/openapi/openapi_reservation.json put /commerce/reservation/{reservationId}/items/{reservationItemId}/quantity/{quantity}
Update a reservation item's quantity. Set runSynchronous to "true" to perform this call synchronously with better performance time.
# Update Reservation
Source: https://docs.kibocommerce.com/api-reference/reservation/update-reservation
/openapi/openapi_reservation.json put /commerce/reservation/{reservationId}
Update an existing reservation.
# Update Reservation Item
Source: https://docs.kibocommerce.com/api-reference/reservation/update-reservation-item
/openapi/openapi_reservation.json put /commerce/reservation/{reservationId}/items/{reservationItemId}
Updates a reservation item. Set runSynchronous to "true" to perform this call synchronously with better performance time.
# Update Timer
Source: https://docs.kibocommerce.com/api-reference/reservation/update-timer
/openapi/openapi_reservation.json put /commerce/reservation/{reservationId}/updatetimer
Restart the expiration timer of a reservation.
# Update Zip Code
Source: https://docs.kibocommerce.com/api-reference/reservation/update-zip-code
/openapi/openapi_reservation.json post /commerce/reservation/{reservationId}/zipcode/{zipCode}
Update the zip code of a reservation. Set runSynchronous to "true" to perform this call synchronously with better performance time.
# Create reservation rule
Source: https://docs.kibocommerce.com/api-reference/reservationrules/create-reservation-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/reservation
Creates a new reservation rule.
# Delete reservation rule
Source: https://docs.kibocommerce.com/api-reference/reservationrules/delete-reservation-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/reservation/{code}
Permanently deletes a reservation rule (FR-013 hard delete).
# GET /call-offs/{callOffOrderId}/runs — every audit record that touched
Source: https://docs.kibocommerce.com/api-reference/reservationrules/get-call-offs-runs-—-every-audit-record-that-touched
/openapi/openapi_commerce.json get /commerce/jobs/reservation-rules/call-offs/{callOffOrderId}/runs
a given CallOffOrder, most recent first. Drives the order-detail
"reservation history" panel.
# Get reservation rule by code
Source: https://docs.kibocommerce.com/api-reference/reservationrules/get-reservation-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/reservation/{code}
Gets a reservation rule by its unique code.
# Get reservation rules
Source: https://docs.kibocommerce.com/api-reference/reservationrules/get-reservation-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/reservation
Gets a collection of reservation rules according to any specified filter criteria and sort options.
# GET /rules/{ruleId}/recent — records for one rule within an optional
Source: https://docs.kibocommerce.com/api-reference/reservationrules/get-rules-recent-—-records-for-one-rule-within-an-optional
/openapi/openapi_commerce.json get /commerce/jobs/reservation-rules/rules/{ruleId}/recent
date range, most recent first. Powers the rule-detail "recent runs" panel.
# GET /runs/{runId} — every audit record produced by a single run, in
Source: https://docs.kibocommerce.com/api-reference/reservationrules/get-runs-—-every-audit-record-produced-by-a-single-run-in
/openapi/openapi_commerce.json get /commerce/jobs/reservation-rules/runs/{runId}
chronological order. Drill-down from the runs list.
# GET /runs — per-run summaries (aggregated counts by outcome) within an
Source: https://docs.kibocommerce.com/api-reference/reservationrules/get-runs-—-per-run-summaries-aggregated-counts-by-outcome-within-an
/openapi/openapi_commerce.json get /commerce/jobs/reservation-rules/runs
optional date range; most-recent run first.
# Triggers an on-demand Reservation Rules Engine run for the caller's
Source: https://docs.kibocommerce.com/api-reference/reservationrules/triggers-an-on-demand-reservation-rules-engine-run-for-the-callers
/openapi/openapi_commerce.json post /commerce/jobs/reservation-rules/run
{tenantId, siteId}.
Default behavior (`sync=false`): publishes the same
`ReservationRuleEngineStart` event the cron scheduler does, returns
HTTP 202 + JobKey within ~200ms p95 (publish-and-return; no batch work
in the request thread).
Debug bypass (`?sync=true`): SKIPS kibo.jobs + RabbitMQ +
MassTransit consumer entirely. Executes the orchestrator inline on the
request thread and returns HTTP 200 with the run's final state +
elapsed milliseconds. Intended for local repro and integration smoke
only — the request can hold the thread for the full duration of the
run. Still subject to the per-{tenantId, siteId} single-writer lease,
so a concurrent async run will SKIP this one.
# Update reservation rule
Source: https://docs.kibocommerce.com/api-reference/reservationrules/update-reservation-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/reservation/{code}
Updates an existing reservation rule with full replacement semantics (FR-009).
# Update reservation rule rank
Source: https://docs.kibocommerce.com/api-reference/reservationrules/update-reservation-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/reservation/{code}/rank
Updates the rank for a reservation rule and atomically reorders all other rules in the current master catalog.
# Create reservation steal-for rule
Source: https://docs.kibocommerce.com/api-reference/reservationstealforrules/create-reservation-steal-for-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/reservationstealfor
Creates a new reservation steal-for rule.
# Delete reservation steal-for rule
Source: https://docs.kibocommerce.com/api-reference/reservationstealforrules/delete-reservation-steal-for-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/reservationstealfor/{code}
Permanently deletes a reservation steal-for rule (FR-013 hard delete).
# Get reservation steal-for rule by code
Source: https://docs.kibocommerce.com/api-reference/reservationstealforrules/get-reservation-steal-for-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/reservationstealfor/{code}
Gets a reservation steal-for rule by its unique code.
# Get reservation steal-for rules
Source: https://docs.kibocommerce.com/api-reference/reservationstealforrules/get-reservation-steal-for-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/reservationstealfor
Gets a collection of reservation steal-for rules according to any specified filter criteria and sort options.
# Update reservation steal-for rule
Source: https://docs.kibocommerce.com/api-reference/reservationstealforrules/update-reservation-steal-for-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/reservationstealfor/{code}
Updates an existing reservation steal-for rule with full replacement semantics (FR-009).
# Update reservation steal-for rule rank
Source: https://docs.kibocommerce.com/api-reference/reservationstealforrules/update-reservation-steal-for-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/reservationstealfor/{code}/rank
Updates the rank for a reservation steal-for rule and atomically reorders all other rules of this type in the current master catalog.
# Create reservation steal-from rule
Source: https://docs.kibocommerce.com/api-reference/reservationstealfromrules/create-reservation-steal-from-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/reservationstealfrom
Creates a new reservation steal-from rule.
# Delete reservation steal-from rule
Source: https://docs.kibocommerce.com/api-reference/reservationstealfromrules/delete-reservation-steal-from-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/reservationstealfrom/{code}
Permanently deletes a reservation steal-from rule (FR-013 hard delete).
# Get reservation steal-from rule by code
Source: https://docs.kibocommerce.com/api-reference/reservationstealfromrules/get-reservation-steal-from-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/reservationstealfrom/{code}
Gets a reservation steal-from rule by its unique code.
# Get reservation steal-from rules
Source: https://docs.kibocommerce.com/api-reference/reservationstealfromrules/get-reservation-steal-from-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/reservationstealfrom
Gets a collection of reservation steal-from rules according to any specified filter criteria and sort options.
# Update reservation steal-from rule
Source: https://docs.kibocommerce.com/api-reference/reservationstealfromrules/update-reservation-steal-from-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/reservationstealfrom/{code}
Updates an existing reservation steal-from rule with full replacement semantics (FR-009).
# Update reservation steal-from rule rank
Source: https://docs.kibocommerce.com/api-reference/reservationstealfromrules/update-reservation-steal-from-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/reservationstealfrom/{code}/rank
Updates the rank for a reservation steal-from rule and atomically reorders all other rules of this type in the current master catalog.
# Add Package to Return
Source: https://docs.kibocommerce.com/api-reference/return/add-package-to-return
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/packages
package?
# Auto Refund Return
Source: https://docs.kibocommerce.com/api-reference/return/auto-refund-return
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/autorefund
Attempt to automatically refund the return
# Create Payment Action For Return
Source: https://docs.kibocommerce.com/api-reference/return/create-payment-action-for-return
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/payments/actions
Sets the action of the specified payment transaction interaction. Available actions depend on the current status of the payment transaction.If in doubt, get a list of available payment actions first.
# Create Return Attributes
Source: https://docs.kibocommerce.com/api-reference/return/create-return-attributes
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/attributes
Adds an attributeSet to the return. This is an internal attributeSet that the merchant might want to add to a return.
# Create Return Item
Source: https://docs.kibocommerce.com/api-reference/return/create-return-item
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/items
Adds a return item to the return.
# Create Return Item Attributes
Source: https://docs.kibocommerce.com/api-reference/return/create-return-item-attributes
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/items/{returnItemId}/attributes
Adds attributes to the return item. This is an internal attribute that the merchant might want to add to a return item.
# Create Return Note
Source: https://docs.kibocommerce.com/api-reference/return/create-return-note
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/notes
Adds a note to the return. This is an internal note that the merchant might want to add to a return. This note is visible in Admin for customer service representatives to see.
# Create Return Shipment
Source: https://docs.kibocommerce.com/api-reference/return/create-return-shipment
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/shipments
Creates a shipment by grouping together multiple packages into logical shipments.
# Create Return Shipping Order
Source: https://docs.kibocommerce.com/api-reference/return/create-return-shipping-order
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/ship
Creates a child order for the return for processing replacements. The request body (a collection of ReturnItemSpecifier) is optional. If the body is empty, the operation replaces all remaining items marked for replace. If you want to replace only a specific item(s) marked for return, you must specify the item(s) in the request body.
# Create Returns
Source: https://docs.kibocommerce.com/api-reference/return/create-returns
/openapi/openapi_commerce.json post /commerce/returns
Creates a new Return for an order or product list.
# Delete Order Item
Source: https://docs.kibocommerce.com/api-reference/return/delete-order-item
/openapi/openapi_commerce.json delete /commerce/returns/{orderId}/items/{orderItemId}
Removes a particular return item from the return of the current shopper.
# Delete Return
Source: https://docs.kibocommerce.com/api-reference/return/delete-return
/openapi/openapi_commerce.json delete /commerce/returns/{returnId}
Deletes a return specified by return Id.
# Delete Return Note
Source: https://docs.kibocommerce.com/api-reference/return/delete-return-note
/openapi/openapi_commerce.json delete /commerce/returns/{returnId}/notes/{noteId}
Deletes a specific note on a return.
# Delete Return Package
Source: https://docs.kibocommerce.com/api-reference/return/delete-return-package
/openapi/openapi_commerce.json delete /commerce/returns/{returnId}/packages/{packageId}
Delete a package from the return.
# Delete Return Shipment
Source: https://docs.kibocommerce.com/api-reference/return/delete-return-shipment
/openapi/openapi_commerce.json delete /commerce/returns/{returnId}/shipments/{shipmentId}
Deletes an existing return shipment
# Dispose Return Items
Source: https://docs.kibocommerce.com/api-reference/return/dispose-return-items
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/disposition
Restock return items at a disposition location.
# Get Available Return Actions
Source: https://docs.kibocommerce.com/api-reference/return/get-available-return-actions
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/actions
Gets all the available actions on the return specified by return Id.
# Get Item Conditions
Source: https://docs.kibocommerce.com/api-reference/return/get-item-conditions
/openapi/openapi_commerce.json get /commerce/returns/restock/conditions
Gets the item conditions for the returns
# Get Payment
Source: https://docs.kibocommerce.com/api-reference/return/get-payment
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/payments/{paymentId}
Gets specific payment on the return specified by return Id and payment Id.
# Get Payment Distribution
Source: https://docs.kibocommerce.com/api-reference/return/get-payment-distribution
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/paymentDistribution
Get Payment Distribution
# Get Payments
Source: https://docs.kibocommerce.com/api-reference/return/get-payments
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/payments
Gets payments on the return specified by return Id.
# Get Reasons
Source: https://docs.kibocommerce.com/api-reference/return/get-reasons
/openapi/openapi_commerce.json get /commerce/returns/reasons
Gets all the return reasons.
# Get Return
Source: https://docs.kibocommerce.com/api-reference/return/get-return
/openapi/openapi_commerce.json get /commerce/returns/{returnId}
Allows for retrieval for a return given only the return Id. Further manipulation of that returns must be done off of the order.
# Get Return Attributes
Source: https://docs.kibocommerce.com/api-reference/return/get-return-attributes
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/attributes
Retrieves a list of all attribute sets for a return.
# Get Return Item
Source: https://docs.kibocommerce.com/api-reference/return/get-return-item
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/items/{returnItemId}
Retrieves the details of a single return item.
# Get Return Item Attributes
Source: https://docs.kibocommerce.com/api-reference/return/get-return-item-attributes
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/items/{returnItemId}/attributes
Retrieves a list of all attributes for a return item.
# Get Return Items
Source: https://docs.kibocommerce.com/api-reference/return/get-return-items
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/items
Retrieves the details of all return items in an order.
# Get Return Label
Source: https://docs.kibocommerce.com/api-reference/return/get-return-label
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/shipping/label
Gets the return label specified by returnId.
# Get Return Note
Source: https://docs.kibocommerce.com/api-reference/return/get-return-note
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/notes/{noteId}
Retrieves a specific note from a return.
# Get Return Notes
Source: https://docs.kibocommerce.com/api-reference/return/get-return-notes
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/notes
Retrieves a list of all notes for a return.
# Get Return Package
Source: https://docs.kibocommerce.com/api-reference/return/get-return-package
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/packages/{packageId}
Get an return package.
# Get Return Package Label
Source: https://docs.kibocommerce.com/api-reference/return/get-return-package-label
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/packages/{packageId}/label
Get a return package label
# Get Return Shipment
Source: https://docs.kibocommerce.com/api-reference/return/get-return-shipment
/openapi/openapi_commerce.json get /commerce/returns/{returnId}/shipments/{shipmentId}
Retrieves a return shipment
# Get Returns
Source: https://docs.kibocommerce.com/api-reference/return/get-returns
/openapi/openapi_commerce.json get /commerce/returns
Provides a paged, collection of returns for a Site.
# Perform Payment Action For Return
Source: https://docs.kibocommerce.com/api-reference/return/perform-payment-action-for-return
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/payments/{paymentId}/actions
Sets the action of the specified payment transaction interaction. Available actions depend on the current status of the payment transaction.If in doubt, get a list of available payment actions first. To retrieve the list of available actions, use an operation like GetAvailableReturnActions to view the actions available for the resource you are updating.
# Perform Return Action
Source: https://docs.kibocommerce.com/api-reference/return/perform-return-action
/openapi/openapi_commerce.json post /commerce/returns/actions
Performs a specified action on one or more returns.
# Resend Return Email
Source: https://docs.kibocommerce.com/api-reference/return/resend-return-email
/openapi/openapi_commerce.json put /commerce/returns/email/resend
Resends return email.
# Restock Return Items
Source: https://docs.kibocommerce.com/api-reference/return/restock-return-items
/openapi/openapi_commerce.json post /commerce/returns/{returnId}/restock
API to restock return item.
# Update Return
Source: https://docs.kibocommerce.com/api-reference/return/update-return
/openapi/openapi_commerce.json put /commerce/returns/{returnId}
Updates an existing return.
# Update Return Attributes
Source: https://docs.kibocommerce.com/api-reference/return/update-return-attributes
/openapi/openapi_commerce.json put /commerce/returns/{returnId}/attributes
Updates a specific return attribute set of a return.
# Update Return Item Attributes
Source: https://docs.kibocommerce.com/api-reference/return/update-return-item-attributes
/openapi/openapi_commerce.json put /commerce/returns/{returnId}/items/{returnItemId}/attributes
Updates a specific return item attribute set of a return item.
# Update Return Note
Source: https://docs.kibocommerce.com/api-reference/return/update-return-note
/openapi/openapi_commerce.json put /commerce/returns/{returnId}/notes/{noteId}
Updates a specific note for a return.
# Update Return Package
Source: https://docs.kibocommerce.com/api-reference/return/update-return-package
/openapi/openapi_commerce.json put /commerce/returns/{returnId}/packages/{packageId}
Updates a return's package.
# Create Attribute
Source: https://docs.kibocommerce.com/api-reference/returnattributedefinitions/create-attribute
/openapi/openapi_commerce.json post /commerce/returns/attributedefinition/attributes
Create Attribute
# Get Attribute
Source: https://docs.kibocommerce.com/api-reference/returnattributedefinitions/get-attribute
/openapi/openapi_commerce.json get /commerce/returns/attributedefinition/attributes/{attributeFQN}
Get Attribute
# Get Attribute Vocabulary Values
Source: https://docs.kibocommerce.com/api-reference/returnattributedefinitions/get-attribute-vocabulary-values
/openapi/openapi_commerce.json get /commerce/returns/attributedefinition/attributes/{attributeFQN}/VocabularyValues
Get Attribute Vocabulary Values
# Get Attributes
Source: https://docs.kibocommerce.com/api-reference/returnattributedefinitions/get-attributes
/openapi/openapi_commerce.json get /commerce/returns/attributedefinition/attributes
Get Attributes
# Update Attribute
Source: https://docs.kibocommerce.com/api-reference/returnattributedefinitions/update-attribute
/openapi/openapi_commerce.json put /commerce/returns/attributedefinition/attributes/{attributeFQN}
Update Attribute
# Create Return Rule
Source: https://docs.kibocommerce.com/api-reference/returnrules/create-return-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/return
Creates a new return rule.
# Delete Return Rule
Source: https://docs.kibocommerce.com/api-reference/returnrules/delete-return-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/return/{code}
Deletes a return rule by code.
# Get Return Rule by Code
Source: https://docs.kibocommerce.com/api-reference/returnrules/get-return-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/return/{code}
Gets return rule details by code.
# Get Return Rules
Source: https://docs.kibocommerce.com/api-reference/returnrules/get-return-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/return
Gets a collection of return rules according to any specified filter criteria and sort options.
# Update Return Rule
Source: https://docs.kibocommerce.com/api-reference/returnrules/update-return-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/return/{code}
Updates an existing return rule.
# Update Return Rule Rank
Source: https://docs.kibocommerce.com/api-reference/returnrules/update-return-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/return/{code}/rank
Updates the rank for a return rule and rearranges the ranks of all other rules accordingly.
# Create Return Settings
Source: https://docs.kibocommerce.com/api-reference/returnsettings/create-return-settings
/openapi/openapi_settings.json post /commerce/settings/return/returnsettings
Creates return settings which includes return processing fee, return shipping location
and return label creation on fulfillment
# Get Return Settings
Source: https://docs.kibocommerce.com/api-reference/returnsettings/get-return-settings
/openapi/openapi_settings.json get /commerce/settings/return/returnsettings
Retrieves return settings which includes return processing fee, return shipping location
and return label creation on fulfillment
# Update Return Settings
Source: https://docs.kibocommerce.com/api-reference/returnsettings/update-return-settings
/openapi/openapi_settings.json put /commerce/settings/return/returnsettings
Modifies existing fulfillment settings which includes return processing fee, return shipping location
and return label creation on fulfillment
# Get Roles
Source: https://docs.kibocommerce.com/api-reference/role/get-roles
/openapi/openapi_user.json get /platform/adminuser/roles
Retrieves a list of all roles defined for this tenant.
# Get Edd Calculation Log
Source: https://docs.kibocommerce.com/api-reference/routing/get-edd-calculation-log
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/eddCalculationLog
Get Edd Calculation Log
# Get Sample Request
Source: https://docs.kibocommerce.com/api-reference/routing/get-sample-request
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/samplerequest
Retrieves a sample request.
# Get Suggestion Log
Source: https://docs.kibocommerce.com/api-reference/routing/get-suggestion-log
/openapi/openapi_orderrouting.json get /commerce/orders/orderrouting/api/v1/routing/suggestionLog
Retrieves a log of routing suggestions for an order. You can also view suggestion logs through the Order Routing user interface.
# Reverse Logistics Suggestions
Source: https://docs.kibocommerce.com/api-reference/routing/reverse-logistics-suggestions
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/routing/reverseLogisticsSuggestion
Reverse Logistics Suggestions
# Suggest Candidates
Source: https://docs.kibocommerce.com/api-reference/routing/suggest-candidates
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/routing/candidates
Suggests the routing candidates for an order.
# Suggest Routing
Source: https://docs.kibocommerce.com/api-reference/routing/suggest-routing
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/routing/suggestion
Suggests the routing assignment for an order.
# Suggest Routing Test
Source: https://docs.kibocommerce.com/api-reference/routing/suggest-routing-test
/openapi/openapi_orderrouting.json post /commerce/orders/orderrouting/api/v1/routing/suggestionTest
Tests the routing suggestion logic.
# Evaluate Purchase Limits
Source: https://docs.kibocommerce.com/api-reference/rules/evaluate-purchase-limits
/openapi/openapi_catalog_storefront.json post /commerce/rules/purchaselimit/evaluate
Evaluate the purchase limits for given products and customer.
# Evaluate Return Eligibility
Source: https://docs.kibocommerce.com/api-reference/rules/evaluate-return-eligibility
/openapi/openapi_catalog_storefront.json post /commerce/rules/return/evaluate
Evaluate the return eligibility for given products and customer
# Evaluate Safety Stock Rules
Source: https://docs.kibocommerce.com/api-reference/rules/evaluate-safety-stock-rules
/openapi/openapi_catalog_storefront.json post /commerce/rules/safetystock/evaluate
Evaluate the safety stock for given products and locations
# Create rules engine job
Source: https://docs.kibocommerce.com/api-reference/rulesenginejobs/create-rules-engine-job
/openapi/openapi_catalog_admin.json post /commerce/rules/jobs
Creates a new rules engine job, updates matching MZDB event statuses, and enqueues a RulesEngineJobCreatedEvent for publication. Publication is fire-and-forget via the internal message bus — a 201 response confirms the job was created and events were updated, but does not guarantee consumers have received the event. StampedCount reflects the number of events modified; SkippedCount reflects events that matched but were already in the target status.
# Delete Run History
Source: https://docs.kibocommerce.com/api-reference/runhistorylog/delete-run-history
/openapi/openapi_fulfillment.json delete /commerce/fulfillment/rebalancer/audit/runs/{runId}/log
Delete Run History
# Log
Source: https://docs.kibocommerce.com/api-reference/runhistorylog/log
/openapi/openapi_fulfillment.json post /commerce/fulfillment/rebalancer/audit/runs/{runId}/log
Log
# Create Safety Stock Rule
Source: https://docs.kibocommerce.com/api-reference/safetystockrules/create-safety-stock-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/safetystock
Creates a new safety stock rule.
# Delete Safety Stock Rule
Source: https://docs.kibocommerce.com/api-reference/safetystockrules/delete-safety-stock-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/safetystock/{code}
Deletes a safety stock rule by code.
# Get Safety Stock Rule by Code
Source: https://docs.kibocommerce.com/api-reference/safetystockrules/get-safety-stock-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/safetystock/{code}
Gets safety stock rule details by code.
# Get Safety Stock Rules
Source: https://docs.kibocommerce.com/api-reference/safetystockrules/get-safety-stock-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/safetystock
Gets a collection of safety stock rules according to any specified filter criteria and sort options.
# Update Safety Stock Rule
Source: https://docs.kibocommerce.com/api-reference/safetystockrules/update-safety-stock-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/safetystock/{code}
Updates an existing safety stock rule.
# Update Safety Stock Rule Rank
Source: https://docs.kibocommerce.com/api-reference/safetystockrules/update-safety-stock-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/safetystock/{code}/rank
Updates the rank for a safety stock rule and rearranges the ranks of all other rules accordingly.
# Get Schema Definition
Source: https://docs.kibocommerce.com/api-reference/schemadefinition/get-schema-definition
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/definition/{language}
Get Schema Definition
# List Schema Definitions
Source: https://docs.kibocommerce.com/api-reference/schemadefinition/list-schema-definitions
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/definition
List Schema Definitions
# Publish
Source: https://docs.kibocommerce.com/api-reference/schemadefinition/publish
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/searchSchema/definition/{language}/publish
Publish
# Revert
Source: https://docs.kibocommerce.com/api-reference/schemadefinition/revert
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/searchSchema/definition/{language}/revert
Revert
# Update Schema Definition
Source: https://docs.kibocommerce.com/api-reference/schemadefinition/update-schema-definition
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/searchSchema/definition/{language}
Update Schema Definition
# Delete Category Suggest Settings
Source: https://docs.kibocommerce.com/api-reference/searchcategorysuggestsettings/delete-category-suggest-settings
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/{name}/categorysuggestsettings
Deletes the CategorySuggestSettings for a specific SearchSetting by name.
# Get Category Suggest Settings
Source: https://docs.kibocommerce.com/api-reference/searchcategorysuggestsettings/get-category-suggest-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/{name}/categorysuggestsettings
Get CategorySuggestSettings for a specific SearchSettings.
# Update Category Suggest Settings
Source: https://docs.kibocommerce.com/api-reference/searchcategorysuggestsettings/update-category-suggest-settings
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/{name}/categorysuggestsettings
Adds or updates the CategorySuggestSettings for a specific SearchSetting.
# Delete Search Listing Settings
Source: https://docs.kibocommerce.com/api-reference/searchlistingsettings/delete-search-listing-settings
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/{name}/listingsettings
Deletes the ListingSettings for a specific SearchSetting by name.
# Get Search Listing Settings
Source: https://docs.kibocommerce.com/api-reference/searchlistingsettings/get-search-listing-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/{name}/listingsettings
Get ListingSettings for a specific SearchSettings by name.
# Update Search Listing Settings
Source: https://docs.kibocommerce.com/api-reference/searchlistingsettings/update-search-listing-settings
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/{name}/listingsettings
Adds or updates the ListingSettings for a specific SearchSetting by name.
# Clone Search Merchandizing Rule
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrule/clone-search-merchandizing-rule
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchmerchandizingrules/{code}/clone
Clones a search merchandizing rule.
# Create Search Merchandizing Rule
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrule/create-search-merchandizing-rule
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/searchmerchandizingrules
Create a new search merchandizing rule.
# Delete Search Merchandizing Rule
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrule/delete-search-merchandizing-rule
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/searchmerchandizingrules/{code}
Deletes a search merchandizing rule.
# Get Search Merchandizing Rule
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrule/get-search-merchandizing-rule
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchmerchandizingrules/{code}
Retrieves a search merchandizing rule based on its code.
# Get Search Merchandizing Rules
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrule/get-search-merchandizing-rules
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchmerchandizingrules
Retrieve a list of all search merchandizing rules. You can filter this query by CategoryCode, which supports an EQ (equals) filter with the syntax /catalog/admin/searchmerchandizingrules/?filter=categorycode eq AAA
# Update Search Merchandizing Rule
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrule/update-search-merchandizing-rule
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/searchmerchandizingrules/{code}
Updates an existing search merchandizing rule.
# Preview Search Merchandizing Rule
Source: https://docs.kibocommerce.com/api-reference/searchmerchandizingrules/preview-search-merchandizing-rule
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/searchmerchandizingrules/previewsearchmerchandizingrule
Preview search results with given SearchMerchandizingRule object
# Search Preview
Source: https://docs.kibocommerce.com/api-reference/searchpreview/search-preview
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/productsearch/preview
Though this endpoint only returns data, the decision has been made to make it a POST because the request body will be larger than what a url length can contain.
# Site Search Preview
Source: https://docs.kibocommerce.com/api-reference/searchpreview/site-search-preview
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/productsearch/sitesearchpreview
Though this endpoint only returns data, the decision has been made to make it a POST because the request body will be larger than what a url length can contain.
# Delete Product Suggest Settings
Source: https://docs.kibocommerce.com/api-reference/searchproductsuggestsettings/delete-product-suggest-settings
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/{name}/productsuggestsettings
Deletes the ProductSuggestSettings for a specific SearchSetting by name.
# Get Product Suggest Settings
Source: https://docs.kibocommerce.com/api-reference/searchproductsuggestsettings/get-product-suggest-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/{name}/productsuggestsettings
Get ProductSuggestSettings for a specific SearchSettings by name.
# Update Product Suggest Settings
Source: https://docs.kibocommerce.com/api-reference/searchproductsuggestsettings/update-product-suggest-settings
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/{name}/productsuggestsettings
Adds or updates the ProductSuggestSettings for a specific SearchSetting by name.
# Add Search Redirect
Source: https://docs.kibocommerce.com/api-reference/searchredirect/add-search-redirect
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/search/redirect
Adds a search redirect for a specific site.
# Delete Search Redirect
Source: https://docs.kibocommerce.com/api-reference/searchredirect/delete-search-redirect
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/redirect/{redirectId}
Deletes a specific redirect for a site.
# Get Search Redirect
Source: https://docs.kibocommerce.com/api-reference/searchredirect/get-search-redirect
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/redirect/{redirectId}
Get search redirect by redirect id.
# Get Search Redirects
Source: https://docs.kibocommerce.com/api-reference/searchredirect/get-search-redirects
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/redirect
Get search redirect list.
# Update Search Redirect
Source: https://docs.kibocommerce.com/api-reference/searchredirect/update-search-redirect
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/redirect/{redirectId}
Update a search redirect for a specific site.
# Add Search Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/add-search-settings
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/search/settings
Adds the Search Settings for a specific site.
# Delete Search Settings by Name
Source: https://docs.kibocommerce.com/api-reference/searchsettings/delete-search-settings-by-name
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/settings/{name}
Delete the Search Settings for a specific site by name.
# Delete Site Search Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/delete-site-search-settings
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/{name}/sitesearchsettings
Deletes the SiteSearchSettings for a specific SearchSetting by name.
# Get Search Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/get-search-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/settings
Get site search settings list.
# Get Search Settings by Name
Source: https://docs.kibocommerce.com/api-reference/searchsettings/get-search-settings-by-name
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/settings/{name}
Get specific site search settings by name.
# Get Site Search Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/get-site-search-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/{name}/sitesearchsettings
Get SiteSearchSettings for a specific SearchSettings by name.
# Get System Default Search Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/get-system-default-search-settings
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/settings/systemdefault
Get the system default search settings.
# Update Search Settings by Name
Source: https://docs.kibocommerce.com/api-reference/searchsettings/update-search-settings-by-name
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/settings/{name}
Update site search settings for a specific site by name.
# Update Site Search Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/update-site-search-settings
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/{name}/sitesearchsettings
Updates the SiteSearchSettings for a specific SearchSetting by name.
# Update Spellcheck Settings
Source: https://docs.kibocommerce.com/api-reference/searchsettings/update-spellcheck-settings
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/spellcheck
Update Spellcheck for SiteSearchSettings.
# Add Synonym Definition
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/add-synonym-definition
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/search/synonyms
Add synonym definition
# Add Synonym Definition Collection
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/add-synonym-definition-collection
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/search/synonym-definitions/{localeCode}
Add or update a synonym definition collection.
# Delete Synonym Definition
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/delete-synonym-definition
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/search/synonyms/{synonymId}
Delete a specific synonym definition by ID.
# Get Synonym Definition
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/get-synonym-definition
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/synonyms/{synonymId}
Get a specific synonym definition by ID.
# Get Synonym Definition Collection
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/get-synonym-definition-collection
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/synonym-definitions/{localeCode}
Get synonym definition collection.
# Get Synonym Definition Collections
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/get-synonym-definition-collections
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/master-catalog-synonym-definitions/{languageCode}
Get synonym definition collections.
# Get Synonym Definitions
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/get-synonym-definitions
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/search/synonyms
Get synonym definitions.
# Update Synonym Definition
Source: https://docs.kibocommerce.com/api-reference/searchsynonyms/update-synonym-definition
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/search/synonyms/{synonymId}
Update a specific synonym definition by ID.
# Backorder Items
Source: https://docs.kibocommerce.com/api-reference/shipment/backorder-items
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/backorderedItems
Backorder items from a shipment.
# Backorder Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/backorder-shipment
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/backordered
Backorder a shipment.
# Cancel Items
Source: https://docs.kibocommerce.com/api-reference/shipment/cancel-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/canceledItems
Cancel items from a shipment.
# Cancel Order Shipments
Source: https://docs.kibocommerce.com/api-reference/shipment/cancel-order-shipments
/openapi/openapi_fulfillment.json put /commerce/shipments/order/{orderId}/canceled
Cancel an order's shipments.
# Cancel Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/cancel-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/canceled
Cancel a specific shipment.
# Create Shipments
Source: https://docs.kibocommerce.com/api-reference/shipment/create-shipments
/openapi/openapi_fulfillment.json post /commerce/shipments/bulk
Create new shipments in bulk.
# Customer At Curbside
Source: https://docs.kibocommerce.com/api-reference/shipment/customer-at-curbside
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/customerAtCurbside
Indicates that the customer is ready for curbside pickup.
# Customer At Store
Source: https://docs.kibocommerce.com/api-reference/shipment/customer-at-store
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/customerAtStore
Indicates that a customer is ready for in-store pickup.
# Customer Care Items
Source: https://docs.kibocommerce.com/api-reference/shipment/customer-care-items
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/customerCaredItems
Places shipment items into Customer Care.
# Customer Care Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/customer-care-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/customerCared
Places a shipment into Customer Care.
# Customer in Transit
Source: https://docs.kibocommerce.com/api-reference/shipment/customer-in-transit
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/customerInTransit
Indicates that the customer is in transit for pickup.
# Delete Order Shipments
Source: https://docs.kibocommerce.com/api-reference/shipment/delete-order-shipments
/openapi/openapi_fulfillment.json delete /commerce/shipments/order/{orderId}
Delete the shipments of an order.
# Delete Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/delete-shipment
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}
Delete a shipment.
# Destination Update
Source: https://docs.kibocommerce.com/api-reference/shipment/destination-update
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/destination
Update a shipment's destination.
# Estimated Delivery Date Clear
Source: https://docs.kibocommerce.com/api-reference/shipment/estimated-delivery-date-clear
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/estimatedDeliveryDate
Estimated Delivery Date Clear
# Estimated Delivery Date Update
Source: https://docs.kibocommerce.com/api-reference/shipment/estimated-delivery-date-update
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/estimatedDeliveryDateUpdate
Estimated Delivery Date Update
# Execute Task
Source: https://docs.kibocommerce.com/api-reference/shipment/execute-task
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/tasks/{taskName}/completed
Complete a shipment task.
# Fulfill Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/fulfill-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/fulfilled
Mark a shipment as fulfilled.
# Get Location Shipment Count
Source: https://docs.kibocommerce.com/api-reference/shipment/get-location-shipment-count
/openapi/openapi_fulfillment.json get /commerce/shipments/locationShipmentCount
Get Location Shipment Count
# Get Location Summary Report
Source: https://docs.kibocommerce.com/api-reference/shipment/get-location-summary-report
/openapi/openapi_fulfillment.json get /commerce/shipments/locationSummaryReport
Get a location summary report.
# Get Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/get-shipment
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}
Get a specific shipment by its number.
# Get Shipment Step Count by Shipment Type
Source: https://docs.kibocommerce.com/api-reference/shipment/get-shipment-step-count-by-shipment-type
/openapi/openapi_fulfillment.json get /commerce/shipments/countsByStep
Get the step counts of shipment types.
# Get Shipments
Source: https://docs.kibocommerce.com/api-reference/shipment/get-shipments
/openapi/openapi_fulfillment.json get /commerce/shipments
A paged list of shipments is returned according to any specified filter criteria and sort options. These Fulfillment APIs use a different paging and filtering scheme than most other APIs in the system. For more information, see the Sorting & Filtering APIs guide in the knowledge base.
# Get Tasks
Source: https://docs.kibocommerce.com/api-reference/shipment/get-tasks
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/tasks
Get all shipment tasks.
# Get Workflow Variable
Source: https://docs.kibocommerce.com/api-reference/shipment/get-workflow-variable
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/workflow/variables/{variableName}
Get Workflow Variable
# Get Workflow Variables
Source: https://docs.kibocommerce.com/api-reference/shipment/get-workflow-variables
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/workflow/variables
Get Workflow Variables
# Items Ready For Pack
Source: https://docs.kibocommerce.com/api-reference/shipment/items-ready-for-pack
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/itemsReadyForPack
Items Ready For Pack
# Items Ready For Prep
Source: https://docs.kibocommerce.com/api-reference/shipment/items-ready-for-prep
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/itemsReadyForPrep
Items Ready For Prep
# New Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/new-shipment
/openapi/openapi_fulfillment.json post /commerce/shipments
Create a new shipment.
# New Shipment Via Proxy
Source: https://docs.kibocommerce.com/api-reference/shipment/new-shipment-via-proxy
/openapi/openapi_fulfillment.json post /commerce/shipments/newShipmentViaProxy
New Shipment Via Proxy
# Picked Up Items
Source: https://docs.kibocommerce.com/api-reference/shipment/picked-up-items
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/pickedUpItems
Mark shipment items as picked up.
# Reassign Items
Source: https://docs.kibocommerce.com/api-reference/shipment/reassign-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/reassignedItems
Reassign shipment items.
# Reassign Shipments
Source: https://docs.kibocommerce.com/api-reference/shipment/reassign-shipments
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/reassigned
Reassign a shipment.
# Receive Transfer
Source: https://docs.kibocommerce.com/api-reference/shipment/receive-transfer
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/received
Mark a transfer shipment as received.
# Refresh Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/refresh-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/refresh
Refresh a shipment.
# Reject Items
Source: https://docs.kibocommerce.com/api-reference/shipment/reject-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/rejectedItems
Reject shipment items.
# Reject Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/reject-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/rejected
Reject a shipment.
# Render Order Summary
Source: https://docs.kibocommerce.com/api-reference/shipment/render-order-summary
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/order-summary/html
Render an order summary in HTML.
# Render Packing Slip
Source: https://docs.kibocommerce.com/api-reference/shipment/render-packing-slip
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/rendition/html
Render a packing slip in HTML.
# Replace Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/replace-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}
Update and replace an existing shipment.
# Resend Item Email
Source: https://docs.kibocommerce.com/api-reference/shipment/resend-item-email
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/items/{lineId}/email/resend
Resend an item email notification.
# Resend Shipment Email
Source: https://docs.kibocommerce.com/api-reference/shipment/resend-shipment-email
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/email/resend
Resend a shipment confirmation email.
# Reset Stock Validation
Source: https://docs.kibocommerce.com/api-reference/shipment/reset-stock-validation
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/items/{lineId}/validateStock
Reset Stock Validation
# Retry Fulfilling Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/retry-fulfilling-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/retried
Attempt to fulfill a shipment again.
# Revert Task
Source: https://docs.kibocommerce.com/api-reference/shipment/revert-task
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/tasks/{taskName}/reverted
Revert a shipment task.
# Search and Receive Transfer
Source: https://docs.kibocommerce.com/api-reference/shipment/search-and-receive-transfer
/openapi/openapi_fulfillment.json put /commerce/shipments/received/{search}
Search for and receive a transfer shipment.
# Search Receivable Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/search-receivable-shipment
/openapi/openapi_fulfillment.json get /commerce/shipments/receivable/{search}
Search Receivable Shipment
# Search Shipments
Source: https://docs.kibocommerce.com/api-reference/shipment/search-shipments
/openapi/openapi_fulfillment.json post /commerce/shipments/search
Search Shipments
# Set Workflow Variable
Source: https://docs.kibocommerce.com/api-reference/shipment/set-workflow-variable
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/workflow/variables
Set Workflow Variable
# Skip Task
Source: https://docs.kibocommerce.com/api-reference/shipment/skip-task
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/tasks/{taskName}/skipped
Skip a shipment task.
# Transfer Items
Source: https://docs.kibocommerce.com/api-reference/shipment/transfer-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/transferredItems
Transfer items from a shipment.
# Transfer Shipment
Source: https://docs.kibocommerce.com/api-reference/shipment/transfer-shipment
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/transferred
Transfer a shipment.
# Update Backorder Items
Source: https://docs.kibocommerce.com/api-reference/shipment/update-backorder-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/backorderedItems
Update a shipment's backordered items.
# Update Fulfillment Fields
Source: https://docs.kibocommerce.com/api-reference/shipment/update-fulfillment-fields
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/fulfillmentFields
Update a shipment's fulfillment fields.
# Update Gift Card Info
Source: https://docs.kibocommerce.com/api-reference/shipment/update-gift-card-info
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/giftCardInfo
Update the gift card information of a shipment.
# Update Last Cancellation Date
Source: https://docs.kibocommerce.com/api-reference/shipment/update-last-cancellation-date
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/lastCancellationDate
Update Last Cancellation Date
# Validate Stock Item
Source: https://docs.kibocommerce.com/api-reference/shipment/validate-stock-item
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/items/{lineId}/validateStock
Validate Stock Item
# Workflow Definition Image
Source: https://docs.kibocommerce.com/api-reference/shipment/workflow-definition-image
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/workflow-definition-image
Get the workflow definition image of a shipment.
# Workflow Instance Image
Source: https://docs.kibocommerce.com/api-reference/shipment/workflow-instance-image
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/workflow-instance-image
Get a workflow instance image for a shipment.
# Get attribute vocabulary values
Source: https://docs.kibocommerce.com/api-reference/shipmentattributedefinition/get-attribute-vocabulary-values
/openapi/openapi_fulfillment.json get /commerce/shipments/attributedefinition/attributes/{attributeFQN}/vocabularyValues
Retrieves vocabulary values for a specific attribute (if it has predefined values). Requires Order Read or Order Ship permissions.
# Get shipment attribute definitions
Source: https://docs.kibocommerce.com/api-reference/shipmentattributedefinition/get-shipment-attribute-definitions
/openapi/openapi_fulfillment.json get /commerce/shipments/attributedefinition/attributes
Retrieves shipment attribute definitions with optional filtering and pagination. Requires Order Read or Order Ship permissions.
# Get shipment line item attribute definitions
Source: https://docs.kibocommerce.com/api-reference/shipmentattributedefinition/get-shipment-line-item-attribute-definitions
/openapi/openapi_fulfillment.json get /commerce/shipments/attributedefinition/items/attributes
Retrieves shipment line item attribute definitions with optional filtering and pagination. Requires Order Read or Order Ship permissions.
# Get single shipment attribute definition
Source: https://docs.kibocommerce.com/api-reference/shipmentattributedefinition/get-single-shipment-attribute-definition
/openapi/openapi_fulfillment.json get /commerce/shipments/attributedefinition/attributes/{attributeFQN}
Retrieves a specific shipment attribute definition by its fully qualified name. Requires Order Read or Order Ship permissions.
# Create Shipment Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentattributes/create-shipment-attributes
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/attributes
Create Shipment Attributes
# Delete Shipment Map Attribute
Source: https://docs.kibocommerce.com/api-reference/shipmentattributes/delete-shipment-map-attribute
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/attributes/{key}
Delete a shipment attribute.
# Get Shipment Map Attribute
Source: https://docs.kibocommerce.com/api-reference/shipmentattributes/get-shipment-map-attribute
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/attributes/{key}
Get a shipment attribute by its key.
# Get Shipment Map Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentattributes/get-shipment-map-attributes
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/attributes
Get a shipment's attributes.
# Set Shipment Map Attribute
Source: https://docs.kibocommerce.com/api-reference/shipmentattributes/set-shipment-map-attribute
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/attributes/{key}
Set a shipment's attribute value.
# Set Shipment Map Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentattributes/set-shipment-map-attributes
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/attributes
Set a shipment's attributes.
# Add Shipment To Consolidation Group
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/add-shipment-to-consolidation-group
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/shipments/add/{shipmentNumberToAdd}
Add Shipment To Consolidation Group
# Add Shipment to Existing Consolidation Group
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/add-shipment-to-existing-consolidation-group
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/shipments/{shipmentConsolidationId}/add/{shipmentNumberToAdd}
Add Shipment To Consolidation Group
# Add Shipments to Existing Consolidation Group
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/add-shipments-to-existing-consolidation-group
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/consolidated/shipments/{shipmentConsolidationId}
Consolidate Shipments
# Consolidate Shipments
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/consolidate-shipments
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/consolidated/shipments
Consolidate Shipments
# Get Consolidated Shipments
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/get-consolidated-shipments
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/consolidated/shipments
Get Consolidated Shipments
# Get Consolidation Candidate Shipments
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/get-consolidation-candidate-shipments
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/consolidated/shipments/candidates
Get Consolidation Candidate Shipments
# Get Consolidation Group by ID
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/get-consolidation-group-by-id
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/consolidated/shipments/{shipmentConsolidationId}
Get Consolidated Shipments
# Remove Current Shipment From Consolidation
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/remove-current-shipment-from-consolidation
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/consolidated/shipments
Remove Current Shipment From Consolidation
# Remove Shipment from Consolidation Group by ID
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/remove-shipment-from-consolidation-group-by-id
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/consolidated/shipments/{shipmentConsolidationId}
Remove Current Shipment From Consolidation
# Remove Specific Shipment From Consolidation Group
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/remove-specific-shipment-from-consolidation-group
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/shipments/remove/{shipmentNumberToRemove}
Remove Specific Shipment From Consolidation Group
# Remove Specific Shipment from Existing Consolidation Group
Source: https://docs.kibocommerce.com/api-reference/shipmentconsolidation/remove-specific-shipment-from-existing-consolidation-group
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/consolidated/shipments/{shipmentConsolidationId}/remove/{shipmentNumberToRemove}
Remove Specific Shipment From Consolidation Group
# Delete Alternate Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/delete-alternate-contact
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/alternateContact
Delete a shipment's alternate contact details.
# Get Alternate Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/get-alternate-contact
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/alternateContact
Get the designated alternate contact for a shipment.
# Get Customer Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/get-customer-contact
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/customerContact
Get the customer contact information of a shipment.
# Get Destination Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/get-destination-contact
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/destinationContact
Get the destination contact for a shipment.
# Update Alternate Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/update-alternate-contact
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/alternateContact
Update the designated alternate contact of a shipment.
# Update Customer Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/update-customer-contact
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/customerContact
Update the customer contact information of a shipment.
# Update Destination Contact
Source: https://docs.kibocommerce.com/api-reference/shipmentcontact/update-destination-contact
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/destinationContact
Update the destination contact of a shipment.
# Delete Shipment Data
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/delete-shipment-data
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/data
Delete a shipment's data.
# Delete Shipment Data By Key
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/delete-shipment-data-by-key
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/data/{key}
Delete a shipment data entry by its key.
# Delete Shipment Item Data
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/delete-shipment-item-data
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/items/{lineId}/data
Delete shipment item data.
# Delete Shipment Item Data By Key
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/delete-shipment-item-data-by-key
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/items/{lineId}/data/{key}
Delete a shipment item data record by its key.
# Get Shipment Data
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/get-shipment-data
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/data
Get the data of a shipment.
# Get Shipment Item Data
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/get-shipment-item-data
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/items/{lineId}/data
Get the data of a shipment line item.
# Replace Shipment Data
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/replace-shipment-data
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/data
Update and replace a shipment's data.
# Replace Shipment Item Data
Source: https://docs.kibocommerce.com/api-reference/shipmentdata/replace-shipment-item-data
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/items/{lineId}/data
Replace shipment item data.
# Place Shipment on Hold
Source: https://docs.kibocommerce.com/api-reference/shipmenthold/place-shipment-on-hold
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/hold
Transitions a shipment to HOLD status, suspending normal fulfillment processing.
# Release Shipment from Hold
Source: https://docs.kibocommerce.com/api-reference/shipmenthold/release-shipment-from-hold
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/holdRelease
Transitions a shipment from HOLD status back to its previous status, such as READY, allowing normal fulfillment processing to continue.
# Update Hold Release Date
Source: https://docs.kibocommerce.com/api-reference/shipmenthold/update-hold-release-date
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/holdReleaseDate
Updates the scheduled release date for a shipment currently on hold. The shipment will be automatically released when the specified date/time is reached.
# Get Shipment Inventory Allocations
Source: https://docs.kibocommerce.com/api-reference/shipmentinventoryallocation/get-shipment-inventory-allocations
/openapi/openapi_inventory.json post /commerce/inventory/v5/inventory/shipmentInventoryAllocations
Get future Inventory Allocations by shipment Ids
# Create Shipment Item Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentitemattributes/create-shipment-item-attributes
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/items/attributes
Create Shipment Item Attributes
# Get Shipment Item Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentitemattributes/get-shipment-item-attributes
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/items/attributes
Get Shipment Item Attributes
# Update Shipment Item Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentitemattributes/update-shipment-item-attributes
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/items/attributes/bulk
Update Shipment Item Attributes
# Update Single Item Attributes
Source: https://docs.kibocommerce.com/api-reference/shipmentitemattributes/update-single-item-attributes
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/items/attributes/{lineId}
Update Single Item Attributes
# Get Query Descriptor
Source: https://docs.kibocommerce.com/api-reference/shipmentmetadata/get-query-descriptor
/openapi/openapi_fulfillment.json get /commerce/shipments/metadata/query-descriptor
Get Query Descriptor
# Get Rule Fields
Source: https://docs.kibocommerce.com/api-reference/shipmentmetadata/get-rule-fields
/openapi/openapi_fulfillment.json get /commerce/shipments/metadata/rule-fields
Get Rule Fields
# Make Shipment Immutable
Source: https://docs.kibocommerce.com/api-reference/shipmentmutability/make-shipment-immutable
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/immutable
Make Shipment Immutable
# Make Shipment Mutable
Source: https://docs.kibocommerce.com/api-reference/shipmentmutability/make-shipment-mutable
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/mutable
Make Shipment Mutable
# Delete Shipment Note
Source: https://docs.kibocommerce.com/api-reference/shipmentnotes/delete-shipment-note
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/notes/{noteId}
Delete an existing shipment note.
# New Shipment Note
Source: https://docs.kibocommerce.com/api-reference/shipmentnotes/new-shipment-note
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/notes
Add a new note to a shipment.
# Update Shipment Note
Source: https://docs.kibocommerce.com/api-reference/shipmentnotes/update-shipment-note
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/notes/{noteId}
Update an existing shipment note.
# Create New Packages
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/create-new-packages
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/packages/bulk
Create new shipment packages in bulk.
# Delete Shipment Package
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/delete-shipment-package
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/packages/{packageId}
Delete an existing shipment package.
# Delete Shipment Packages
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/delete-shipment-packages
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/packages/bulk
Delete shipment packages in bulk.
# New Package
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/new-package
/openapi/openapi_fulfillment.json post /commerce/shipments/{shipmentNumber}/packages
Create a new shipment package.
# Receive Package By Id
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/receive-package-by-id
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/packages/{packageId}/received
Receive Package By Id
# Receive Package By Tracking Number
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/receive-package-by-tracking-number
/openapi/openapi_fulfillment.json put /commerce/shipments/packages/received/{search}
Receive Package By Tracking Number
# Remove Shipping Information
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/remove-shipping-information
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/packages/bulk/shipping
Remove Shipping Information
# Save Multi Piece Shipment Packages
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/save-multi-piece-shipment-packages
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/packages/mps
Save Multi Piece Shipment Packages
# Update Package
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/update-package
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/packages/{packageId}
Update an existing shipment package.
# Validate Package Items And Receive
Source: https://docs.kibocommerce.com/api-reference/shipmentpackages/validate-package-items-and-receive
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/packages/{packageId}/validateReceipt
Validate Package Items And Receive
# Get Prioritization History
Source: https://docs.kibocommerce.com/api-reference/shipmentpriority/get-prioritization-history
/openapi/openapi_fulfillment.json get /commerce/shipments/priorities/{shipmentNumber}/history
Get Prioritization History
# Get Priority Info
Source: https://docs.kibocommerce.com/api-reference/shipmentpriority/get-priority-info
/openapi/openapi_fulfillment.json get /commerce/shipments/priorities/{shipmentNumber}
Get Priority Info
# Update Priorities
Source: https://docs.kibocommerce.com/api-reference/shipmentpriority/update-priorities
/openapi/openapi_fulfillment.json put /commerce/shipments/priorities
Update Priorities
# Clear Release Info
Source: https://docs.kibocommerce.com/api-reference/shipmentrelease/clear-release-info
/openapi/openapi_fulfillment.json delete /commerce/shipments/{shipmentNumber}/release
Clear Release Info
# Get Release Info
Source: https://docs.kibocommerce.com/api-reference/shipmentrelease/get-release-info
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/release
Get Release Info
# Patch Release Info
Source: https://docs.kibocommerce.com/api-reference/shipmentrelease/patch-release-info
/openapi/openapi_fulfillment.json patch /commerce/shipments/{shipmentNumber}/release
Patch Release Info
# Update Release Info
Source: https://docs.kibocommerce.com/api-reference/shipmentrelease/update-release-info
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/release
Update Release Info
# Create shipment release rule
Source: https://docs.kibocommerce.com/api-reference/shipmentreleaserules/create-shipment-release-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/shipmentrelease
Creates a new shipment release rule.
# Delete shipment release rule
Source: https://docs.kibocommerce.com/api-reference/shipmentreleaserules/delete-shipment-release-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/shipmentrelease/{code}
Deletes a shipment release rule by code.
# Get shipment release rule by code
Source: https://docs.kibocommerce.com/api-reference/shipmentreleaserules/get-shipment-release-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/shipmentrelease/{code}
Gets a shipment release rule details by code.
# Get shipment release rules
Source: https://docs.kibocommerce.com/api-reference/shipmentreleaserules/get-shipment-release-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/shipmentrelease
Gets a collection of shipment release rules according to any specified filter criteria and sort options.
# Update shipment release rule
Source: https://docs.kibocommerce.com/api-reference/shipmentreleaserules/update-shipment-release-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/shipmentrelease/{code}
Updates an existing shipment release rule.
# Update shipment release rule rank
Source: https://docs.kibocommerce.com/api-reference/shipmentreleaserules/update-shipment-release-rule-rank
/openapi/openapi_catalog_admin.json put /commerce/rules/shipmentrelease/{code}/rank
Updates the rank for a shipment release rule and rearranges the ranks of all other rules accordingly.
# Resend Shipment Cancel Email
Source: https://docs.kibocommerce.com/api-reference/shipmentresendemail/resend-shipment-cancel-email
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/resendCanceledEmail
Resend Shipment Cancel Email
# Resend Shipment Fulfill Email
Source: https://docs.kibocommerce.com/api-reference/shipmentresendemail/resend-shipment-fulfill-email
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/resendFulfilledEmail
Resend Shipment Fulfill Email
# Create shipment rule
Source: https://docs.kibocommerce.com/api-reference/shipmentrules/create-shipment-rule
/openapi/openapi_catalog_admin.json post /commerce/rules/shipment
Creates a new shipment rule.
# Delete shipment rule
Source: https://docs.kibocommerce.com/api-reference/shipmentrules/delete-shipment-rule
/openapi/openapi_catalog_admin.json delete /commerce/rules/shipment/{code}
Delete a shipment rule.
# Get shipment rule by code
Source: https://docs.kibocommerce.com/api-reference/shipmentrules/get-shipment-rule-by-code
/openapi/openapi_catalog_admin.json get /commerce/rules/shipment/{code}
Retrieves the details of a single shipment rule.
# Get shipment rules
Source: https://docs.kibocommerce.com/api-reference/shipmentrules/get-shipment-rules
/openapi/openapi_catalog_admin.json get /commerce/rules/shipment
Retrieves a list of shipment rules.
# Parse Shipment Expression
Source: https://docs.kibocommerce.com/api-reference/shipmentrules/parse-shipment-expression
/openapi/openapi_catalog_admin.json post /commerce/rules/shipment/expression/parse
Parses a shipment expression and returns the query string for retrieving shipments that match the criteria.
# Update shipment rule
Source: https://docs.kibocommerce.com/api-reference/shipmentrules/update-shipment-rule
/openapi/openapi_catalog_admin.json put /commerce/rules/shipment/{code}
Update an existing shipment rule.
# Get Shipments Aggregation
Source: https://docs.kibocommerce.com/api-reference/shipmentsaggregation/get-shipments-aggregation
/openapi/openapi_fulfillment.json get /commerce/shipments/aggregation
Get Shipments Aggregation
# Get Carriers
Source: https://docs.kibocommerce.com/api-reference/shipping/get-carriers
/openapi/openapi_shipping_storefront.json get /commerce/catalog/storefront/shipping/carriers
Get a list of supported carriers.
# Get Labels
Source: https://docs.kibocommerce.com/api-reference/shipping/get-labels
/openapi/openapi_shipping_storefront.json post /commerce/catalog/storefront/shipping/request-labels
Get Shipping Label for the Service Type Requested
# Get Labels By Tracking Number
Source: https://docs.kibocommerce.com/api-reference/shipping/get-labels-by-tracking-number
/openapi/openapi_shipping_storefront.json post /commerce/catalog/storefront/shipping/get-labels
Get shipping labels by tracking number.
# Get Multi Rates
Source: https://docs.kibocommerce.com/api-reference/shipping/get-multi-rates
/openapi/openapi_shipping_storefront.json post /commerce/catalog/storefront/shipping/request-multi-rates
Get List of Rate Responses for a List of Rate Requests
# Get Rates
Source: https://docs.kibocommerce.com/api-reference/shipping/get-rates
/openapi/openapi_shipping_storefront.json post /commerce/catalog/storefront/shipping/request-rates
Get Rate Responses for a Rate Request
# Get Transit Times
Source: https://docs.kibocommerce.com/api-reference/shipping/get-transit-times
/openapi/openapi_shipping_storefront.json post /commerce/catalog/storefront/shipping/transit-times
Get Transit Times
# Handle Carrier Notifications
Source: https://docs.kibocommerce.com/api-reference/shippingnotification/handle-carrier-notifications
/openapi/openapi_fulfillment.json post /commerce/fulfillment/shipping/notifications/{carrier}
Handle carrier notifications.
# Create Order Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/create-order-handling-fee-rule
/openapi/openapi_shipping_admin.json post /commerce/shipping/admin/profiles/{profilecode}/rules/orderhandlingfees
Creates a new order handling fee rule
# Create Product Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/create-product-handling-fee-rule
/openapi/openapi_shipping_admin.json post /commerce/shipping/admin/profiles/{profilecode}/rules/producthandlingfees
Creates a new product handling fee rule
# Create Shipping Inclusion Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/create-shipping-inclusion-rule
/openapi/openapi_shipping_admin.json post /commerce/shipping/admin/profiles/{profilecode}/rules/shippinginclusions
Creates a new shipping inclusion rule
# Delete Order Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/delete-order-handling-fee-rule
/openapi/openapi_shipping_admin.json delete /commerce/shipping/admin/profiles/{profilecode}/rules/orderhandlingfees/{id}
Deletes an existing order handling fee rule
# Delete Product Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/delete-product-handling-fee-rule
/openapi/openapi_shipping_admin.json delete /commerce/shipping/admin/profiles/{profilecode}/rules/producthandlingfees/{id}
Deletes an existing product handling fee rule
# Delete Shipping Inclusion Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/delete-shipping-inclusion-rule
/openapi/openapi_shipping_admin.json delete /commerce/shipping/admin/profiles/{profilecode}/rules/shippinginclusions/{id}
Deletes an existing shipping inclusion rule
# Get Configured Shipping States
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-configured-shipping-states
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/shippingstates
Retrieves all configured shipping states
# Get Order Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-order-handling-fee-rule
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/rules/orderhandlingfees/{id}
Retrieves an order handling fee rule by ID
# Get Order Handling Fee Rules
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-order-handling-fee-rules
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/rules/orderhandlingfees
Retrieve all order handling fee rules
# Get Product Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-product-handling-fee-rule
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/rules/producthandlingfees/{id}
Retrieves a product handling fee rule by ID
# Get Product Handling Fee Rules
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-product-handling-fee-rules
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/rules/producthandlingfees
Retrieves all product handling fee rules
# Get Shipping Inclusion Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-shipping-inclusion-rule
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/rules/shippinginclusions/{id}
Retrieves a shipping inclusion rule by ID
# Get Shipping Inclusion Rules
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-shipping-inclusion-rules
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles/{profilecode}/rules/shippinginclusions
Retrieves all shipping inclusion rules
# Get Shipping Profiles
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/get-shipping-profiles
/openapi/openapi_shipping_admin.json get /commerce/shipping/admin/profiles
Get shipping profiles for the tenant/master catalog
# Update Order Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/update-order-handling-fee-rule
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/profiles/{profilecode}/rules/orderhandlingfees/{id}
Updates an existing order handling fee rule
# Update Product Handling Fee Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/update-product-handling-fee-rule
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/profiles/{profilecode}/rules/producthandlingfees/{id}
Updates an existing product handling fee rule
# Update Shipping Inclusion Rule
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/update-shipping-inclusion-rule
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/profiles/{profilecode}/rules/shippinginclusions/{id}
Updates an existing shipping inclusion rule
# Update States
Source: https://docs.kibocommerce.com/api-reference/shippingprofile/update-states
/openapi/openapi_shipping_admin.json put /commerce/shipping/admin/profiles/{profilecode}/shippingstates
Updates the configured shipping states
# Create Shipping Settings
Source: https://docs.kibocommerce.com/api-reference/shippingsettings/create-shipping-settings
/openapi/openapi_settings.json post /commerce/settings/shipping/orderhandlingfee
OBSOLETE: Handling fees are now defined via shipping admin
Creates site's shipping handling fee.
# Get Order Handling Fee
Source: https://docs.kibocommerce.com/api-reference/shippingsettings/get-order-handling-fee
/openapi/openapi_settings.json get /commerce/settings/shipping/orderhandlingfee
OBSOLETE: Handling fees are now defined via shipping admin
Retrieves the site's shipping handling fee.
# Get Site Shipping Settings
Source: https://docs.kibocommerce.com/api-reference/shippingsettings/get-site-shipping-settings
/openapi/openapi_settings.json get /commerce/settings/shipping
Retrieves site's current shipping settings including information about the active shipping rate provider,
return address, shipping methods, and which countries that you can ship to.
# Update Shipping Settings
Source: https://docs.kibocommerce.com/api-reference/shippingsettings/update-shipping-settings
/openapi/openapi_settings.json put /commerce/settings/shipping/orderhandlingfee
OBSOLETE: Handling fees are now defined via shipping admin
Updates the site's shipping handling fee.
# Add Stopwords
Source: https://docs.kibocommerce.com/api-reference/stopwords/add-stopwords
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/searchSchema/stopwords/{language}
Upload a stopwords file for a language as a list of strings. This should be a .txt file, not JSON.
# Get Stopwords
Source: https://docs.kibocommerce.com/api-reference/stopwords/get-stopwords
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/stopwords/{language}
Downloads the stopwords file for the language. This is a .txt file, not a JSON response.
# Get Storefront Shipment
Source: https://docs.kibocommerce.com/api-reference/storefront/get-storefront-shipment
/openapi/openapi_fulfillment.json get /commerce/fulfillment/storefront/shipments/{shipmentNumber}
Retrieve a storefront shipment by number.
# Get Storefront Shipments
Source: https://docs.kibocommerce.com/api-reference/storefront/get-storefront-shipments
/openapi/openapi_fulfillment.json get /commerce/fulfillment/storefront/shipments
Retrieve all storefront shipments.
# Create Anonymous Shopper Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/create-anonymous-shopper-auth-ticket
/openapi/openapi_customer.json get /commerce/customer/authtickets/anonymousshopper
Authenticates anonymous shopper for the site.
# Create Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/create-auth-ticket
/openapi/openapi_customer.json post /commerce/customer/authtickets/2fa/auth
Validates the 2FA details provided by the user and creates an authentication ticket
# Create User Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/create-user-auth-ticket
/openapi/openapi_customer.json post /commerce/customer/authtickets
Authenticates a user for a particular site given a set of user credentials.
# Generate 2FA Code
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/generate-2fa-code
/openapi/openapi_customer.json post /commerce/customer/authtickets/2fa/request
Generates a 6-digit 2FA code and sends it to the user's email
# Generate OTP Code
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/generate-otp-code
/openapi/openapi_customer.json post /commerce/customer/authtickets/otp/request
Generates a 6-digit OTP code and sends it to the user's email
# Impersonate Cart
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/impersonate-cart
/openapi/openapi_customer.json post /commerce/customer/authtickets/impersonatecart
Impersonates a cart.
# Refresh User Auth Ticket
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/refresh-user-auth-ticket
/openapi/openapi_customer.json put /commerce/customer/authtickets/refresh
Refreshes a user's authentication.
# Validate OTP
Source: https://docs.kibocommerce.com/api-reference/storefrontauthticket/validate-otp
/openapi/openapi_customer.json post /commerce/customer/authtickets/otp/auth
Validates the OTP details provided by the Admin and creates an authentication ticket
# Get Price List
Source: https://docs.kibocommerce.com/api-reference/storefrontpricelists/get-price-list
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/pricelists/{priceListCode}
Retrieves the price list for the given priceListCode
# Get Resolved Price List (GET)
Source: https://docs.kibocommerce.com/api-reference/storefrontpricelists/get-resolved-price-list-get
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/pricelists/resolved
This is primarily used when creating an offline order for a shopper. You can use this operation alongside custom Arc.js actions to alter the price list to which a shopper resolves.
# Get Resolved Price List (POST)
Source: https://docs.kibocommerce.com/api-reference/storefrontpricelists/get-resolved-price-list-post
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/pricelists/resolved
This is primarily used when creating an offline order for a shopper. You can use this operation alongside custom Arc.js actions to alter the price list to which a shopper resolves.
# Configure Variation Product
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/configure-variation-product
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/products/{productCode}/configure
Configure a new product selection. This occurs each time a shopper selects a product option as they configure a product. Once all the required product options are configured, the product can be added to a cart.
# Get location inventories for a list of products
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-location-inventories-for-a-list-of-products
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/products/locationinventory
Get location inventories for a list of products
# Get Location Inventory
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-location-inventory
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/products/{productCode}/locationinventory
Get product inventory. You can provide up to a maximum of 200 product codes and 200 location codes in the endpoint by default.
# Get Product
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-product
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/products/{productCode}
Retrieves information about a single product given its product code.
# Get Product Costs
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-product-costs
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/products/costs
Get costs for products. This cost is the amount the merchant pays for the product—it is not the price that the shopper sees on the storefront (which is usually higher).
# Get Product for Indexing
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-product-for-indexing
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/products/indexing/{productCode}
Retrieves information about a single product given its product code for Mozu to index in the search engine
# Get Product Substitutions
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-product-substitutions
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/products/{productCode}/substitutions
Returns a list of up to 10 products that can be substituted for the provided product code.
# Get Products
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/get-products
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/products
Retrieves a list of products that appear on the storefront according to any specified filter criteria and sort options.
# Validate Discounts
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/validate-discounts
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/products/{productCode}/validateDiscounts
Validate if a collection of discounts is valid for a product. This includes discounts that would normally be considered order level discounts.
# Validate Variant Product
Source: https://docs.kibocommerce.com/api-reference/storefrontproducts/validate-variant-product
/openapi/openapi_catalog_storefront.json post /commerce/catalog/storefront/products/{productCode}/validate
Validate the final state of shopper-selected options.
# Get Search Redirect
Source: https://docs.kibocommerce.com/api-reference/storefrontsearchredirect/get-search-redirect
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/searchredirect/{redirectId}
Get search redirect item by redirect Id.
# Get Search Redirects
Source: https://docs.kibocommerce.com/api-reference/storefrontsearchredirect/get-search-redirects
/openapi/openapi_catalog_storefront.json get /commerce/catalog/storefront/searchredirect/redirects
Get list of search redirect items.
# Add Subscription Item
Source: https://docs.kibocommerce.com/api-reference/subscription/add-subscription-item
/openapi/openapi_subscription.json post /commerce/subscriptions/{subscriptionId}/items
Add a subscription item in existing subscription.
# Apply Coupon
Source: https://docs.kibocommerce.com/api-reference/subscription/apply-coupon
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/coupons/{couponCode}
Apply coupon to the Subscription.
# Change Pricelist On Subscription
Source: https://docs.kibocommerce.com/api-reference/subscription/change-pricelist-on-subscription
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/priceList
Updates the price list on the subscription.
# Convert To Order
Source: https://docs.kibocommerce.com/api-reference/subscription/convert-to-order
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/converttoorder
Convert the subscription to order.
# Create line-level attributes on a subscription item; skips FQNs that already exist
Source: https://docs.kibocommerce.com/api-reference/subscription/create-line-level-attributes-on-a-subscription-item;-skips-fqns-that-already-exist
/openapi/openapi_subscription.json post /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/attributes
Create line-level attributes on a subscription item; skips FQNs that already exist.
# Create Subscription Attributes
Source: https://docs.kibocommerce.com/api-reference/subscription/create-subscription-attributes
/openapi/openapi_subscription.json post /commerce/subscriptions/{subscriptionId}/attributes
Creates list of subscription attributes specified by subscription Id.
# Creates Subscription
Source: https://docs.kibocommerce.com/api-reference/subscription/creates-subscription
/openapi/openapi_subscription.json post /commerce/subscriptions
Creates and validates a new subscription.
# Delete a single line-level attribute from a subscription item by FQN
Source: https://docs.kibocommerce.com/api-reference/subscription/delete-a-single-line-level-attribute-from-a-subscription-item-by-fqn
/openapi/openapi_subscription.json delete /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/attributes/{attributeFqn}
Delete a single line-level attribute from a subscription item by FQN.
# Delete Subscription Data
Source: https://docs.kibocommerce.com/api-reference/subscription/delete-subscription-data
/openapi/openapi_subscription.json delete /commerce/subscriptions/{subscriptionId}/data/{subscriptionDataId}
Delete Value of the given Key in the SubscriptionData bag.
# Delete Subscription Draft
Source: https://docs.kibocommerce.com/api-reference/subscription/delete-subscription-draft
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/cleardraft
Delete subscription draft
# Delete Subscription Item
Source: https://docs.kibocommerce.com/api-reference/subscription/delete-subscription-item
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/remove
Removes a particular subscription item from the subscription
# Delete Subscription Item Data
Source: https://docs.kibocommerce.com/api-reference/subscription/delete-subscription-item-data
/openapi/openapi_subscription.json delete /commerce/subscriptions/{subscriptionId}/item/{subscriptionItemId}/data/{subscriptionItemDataId}
Deletes the Value of the given Key in the SubscriptionItem Data bag.
# Get all line-level attributes for a subscription item
Source: https://docs.kibocommerce.com/api-reference/subscription/get-all-line-level-attributes-for-a-subscription-item
/openapi/openapi_subscription.json get /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/attributes
Get all line-level attributes for a subscription item.
# Get Available Shipment Methods
Source: https://docs.kibocommerce.com/api-reference/subscription/get-available-shipment-methods
/openapi/openapi_subscription.json get /commerce/subscriptions/{subscriptionId}/shipments/methods
Gets valid shipping methods for subscription
# Get Reasons
Source: https://docs.kibocommerce.com/api-reference/subscription/get-reasons
/openapi/openapi_subscription.json get /commerce/subscriptions/reasons
Gets available subscription action reasons for the given category. If no category is supplied will give available Cancel action reasons.
# Get Subscription Attributes
Source: https://docs.kibocommerce.com/api-reference/subscription/get-subscription-attributes
/openapi/openapi_subscription.json get /commerce/subscriptions/{subscriptionId}/attributes
Gets the list of attributes specified by subscription Id.
# Get Subscription Data
Source: https://docs.kibocommerce.com/api-reference/subscription/get-subscription-data
/openapi/openapi_subscription.json get /commerce/subscriptions/{subscriptionId}/data
Retrieves all the values in the Subscription Data bag
# Get Subscription Item Data
Source: https://docs.kibocommerce.com/api-reference/subscription/get-subscription-item-data
/openapi/openapi_subscription.json get /commerce/subscriptions/{subscriptionId}/item/{subscriptionItemId}/data
Retrieves a specific value in the SubscriptionItem Data bag.
# Get Subscriptions
Source: https://docs.kibocommerce.com/api-reference/subscription/get-subscriptions
/openapi/openapi_subscription.json get /commerce/subscriptions
Retrieves a list of subscriptions according to any specified filter criteria and sort options.
# Gets Subscription
Source: https://docs.kibocommerce.com/api-reference/subscription/gets-subscription
/openapi/openapi_subscription.json get /commerce/subscriptions/{subscriptionId}
Retrieves the details of a subscription specified by the subscription ID.
# Order Now
Source: https://docs.kibocommerce.com/api-reference/subscription/order-now
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/ordernow
Lets the user place an instant order from the subscription.
# Order Partial Subscription
Source: https://docs.kibocommerce.com/api-reference/subscription/order-partial-subscription
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/orderpartialdraft
Lets the user place an order from Partial Draft.
# Perform Subscription Action
Source: https://docs.kibocommerce.com/api-reference/subscription/perform-subscription-action
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/actions
Perform the specified action on subscription. Available actions are Activate, Pause, Cancel, and RetryFailedContinuityOrder.
# Remove Coupons
Source: https://docs.kibocommerce.com/api-reference/subscription/remove-coupons
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/removecoupon
Removes existing coupons from a subscription.
# Skip Subscription
Source: https://docs.kibocommerce.com/api-reference/subscription/skip-subscription
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/skip
Skips the next continuity order for the subscription.
# Update Adjustments
Source: https://docs.kibocommerce.com/api-reference/subscription/update-adjustments
/openapi/openapi_subscription.json post /commerce/subscriptions/{subscriptionId}/adjustments
Update item, shipping and handling adjustments on the subscription.
# Update Fulfillment Info
Source: https://docs.kibocommerce.com/api-reference/subscription/update-fulfillment-info
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/fulfillmentinfo
Modifies the Fulfillment Info for a subscription.
# Update Installment plan
Source: https://docs.kibocommerce.com/api-reference/subscription/update-installment-plan
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/installmentPlan
Updates the installment plan on the subscription.
# Update Item Fulfillment
Source: https://docs.kibocommerce.com/api-reference/subscription/update-item-fulfillment
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/fulfillment
Update an item's fulfillment type on an existing subscription.
# Update Item Quantity
Source: https://docs.kibocommerce.com/api-reference/subscription/update-item-quantity
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/quantity/{quantity}
Updates an item's quantity on a existing subscription.
# Update Next Order Date
Source: https://docs.kibocommerce.com/api-reference/subscription/update-next-order-date
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/nextorderdate
Updates the next order date on an existing subscription
# Update Payment
Source: https://docs.kibocommerce.com/api-reference/subscription/update-payment
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/payment
Updates the payment on the subscription.
# Update Subscription
Source: https://docs.kibocommerce.com/api-reference/subscription/update-subscription
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}
Update the info for an existing subscription
# Update Subscription Attribute
Source: https://docs.kibocommerce.com/api-reference/subscription/update-subscription-attribute
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/attributes
Updates the list of subscription attributes specified by subscription id and removes the missing attributes if not passed when removeMissing flag is set.
# Update Subscription Data
Source: https://docs.kibocommerce.com/api-reference/subscription/update-subscription-data
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/data/{subscriptionDataId}
Insert / Updates the Value of the given Key in the Subscription Data bag.
# Update Subscription Frequency
Source: https://docs.kibocommerce.com/api-reference/subscription/update-subscription-frequency
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/frequency
Update the frequency on an existing subscription
# Update Subscription Item Data
Source: https://docs.kibocommerce.com/api-reference/subscription/update-subscription-item-data
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/item/{subscriptionItemId}/data/{subscriptionItemDataId}
Updates the value of the given key on a subscription item bag.
# Upsert Inventory Tags
Source: https://docs.kibocommerce.com/api-reference/subscription/upsert-inventory-tags
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/upsertinventorytags
Updates and replaces inventory tags.
# Upsert line-level attributes on a subscription item
Source: https://docs.kibocommerce.com/api-reference/subscription/upsert-line-level-attributes-on-a-subscription-item
/openapi/openapi_subscription.json put /commerce/subscriptions/{subscriptionId}/items/{subscriptionItemId}/attributes
Upsert line-level attributes on a subscription item.
# Create Subscription Settings
Source: https://docs.kibocommerce.com/api-reference/subscriptionsettings/create-subscription-settings
/openapi/openapi_settings.json post /commerce/settings/subscription/subscriptionsettings
Creates new subscription settings for a site
# Get Subscription Settings
Source: https://docs.kibocommerce.com/api-reference/subscriptionsettings/get-subscription-settings
/openapi/openapi_settings.json get /commerce/settings/subscription/subscriptionsettings
Retrieves existing subscription settings for a site
# Update Subscription Settings
Source: https://docs.kibocommerce.com/api-reference/subscriptionsettings/update-subscription-settings
/openapi/openapi_settings.json put /commerce/settings/subscription/subscriptionsettings
Modifies existing subscription settings for a site
# Add Substitute Items
Source: https://docs.kibocommerce.com/api-reference/substitutions/add-substitute-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/substituteItems
Add Substitute Items
# Get Substitute Items
Source: https://docs.kibocommerce.com/api-reference/substitutions/get-substitute-items
/openapi/openapi_fulfillment.json get /commerce/shipments/{shipmentNumber}/substituteItems
Get Substitute Items
# Remove Substitute Items
Source: https://docs.kibocommerce.com/api-reference/substitutions/remove-substitute-items
/openapi/openapi_fulfillment.json put /commerce/shipments/{shipmentNumber}/substituteItems/remove
Remove Substitute Items
# Downloads the suggest file for the site
Source: https://docs.kibocommerce.com/api-reference/suggestdefinition/downloads-the-suggest-file-for-the-site
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/suggest/{language}
Downloads the suggest file for the site
# Gets the suggester settings for the site
Source: https://docs.kibocommerce.com/api-reference/suggestdefinition/gets-the-suggester-settings-for-the-site
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/suggest/settings/{language}
Gets the suggester settings for the site
# Updates the suggester settings for the site
Source: https://docs.kibocommerce.com/api-reference/suggestdefinition/updates-the-suggester-settings-for-the-site
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/searchSchema/suggest/settings/{language}
Updates the suggester settings for the site
# Uploads a suggest file for the site in tab separated format)
Source: https://docs.kibocommerce.com/api-reference/suggestdefinition/uploads-a-suggest-file-for-the-site-in-tab-separated-format
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/searchSchema/suggest/{language}
Uploads a suggest file for the site in tab separated format)
# List Synonyms
Source: https://docs.kibocommerce.com/api-reference/synonym/list-synonyms
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/searchSchema/synonyms
List Synonyms
# Update Synonyms
Source: https://docs.kibocommerce.com/api-reference/synonym/update-synonyms
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/searchSchema/synonyms/reload
Update Synonyms
# Create Tag
Source: https://docs.kibocommerce.com/api-reference/tag/create-tag
/openapi/openapi_catalog_admin.json post /commerce/catalog/admin/tags
Creates a tag.
# Delete Tag
Source: https://docs.kibocommerce.com/api-reference/tag/delete-tag
/openapi/openapi_catalog_admin.json delete /commerce/catalog/admin/tags/{tagCode}
Deletes a Tag specified by its tagCode.
# Get Tag
Source: https://docs.kibocommerce.com/api-reference/tag/get-tag
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/tags/{tagCode}
Retrieves the details of a single tag.
# Get Tag Collection as Tag Tree
Source: https://docs.kibocommerce.com/api-reference/tag/get-tag-collection-as-tag-tree
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/tags/node/tree
Retrieves the tag collection as tag tree for specified tagCode.
# Get Tags
Source: https://docs.kibocommerce.com/api-reference/tag/get-tags
/openapi/openapi_catalog_admin.json get /commerce/catalog/admin/tags
Retrieves a list of tags.
# Update Tag
Source: https://docs.kibocommerce.com/api-reference/tag/update-tag
/openapi/openapi_catalog_admin.json put /commerce/catalog/admin/tags/{tagCode}
Modifies a tag.
# Create Target Rule
Source: https://docs.kibocommerce.com/api-reference/targetrules/create-target-rule
/openapi/openapi_shipping_admin.json post /commerce/targetrules
Create Target Rule
# Delete Target Rule
Source: https://docs.kibocommerce.com/api-reference/targetrules/delete-target-rule
/openapi/openapi_shipping_admin.json delete /commerce/targetrules/{code}
Delete Target Rule
# Get Target Rule
Source: https://docs.kibocommerce.com/api-reference/targetrules/get-target-rule
/openapi/openapi_shipping_admin.json get /commerce/targetrules/{code}
Get Target Rule
# Get Target Rules
Source: https://docs.kibocommerce.com/api-reference/targetrules/get-target-rules
/openapi/openapi_shipping_admin.json get /commerce/targetrules
Retrieves a list of TargetRules according to any specified filter criteria and sort options
# Update Target Rule
Source: https://docs.kibocommerce.com/api-reference/targetrules/update-target-rule
/openapi/openapi_shipping_admin.json put /commerce/targetrules/{code}
Update Target Rule
# Validate Target Rule
Source: https://docs.kibocommerce.com/api-reference/targetrules/validate-target-rule
/openapi/openapi_shipping_admin.json post /commerce/targetrules/validate
Validate Target Rule
# Estimate Order Tax
Source: https://docs.kibocommerce.com/api-reference/taxes/estimate-order-tax
/openapi/openapi_pricing.json post /commerce/catalog/storefront/tax/estimate-order
Retrieves a tax context for the given order.
# Get Tenant by ID
Source: https://docs.kibocommerce.com/api-reference/tenants/get-tenant-by-id
/openapi/openapi_tenant.json get /platform/tenants/{tenantId}
Retrieve information about a tenant. The attributes object will contain flags indicating whether or not certain features are enabled on the tenant. Kibo employees can reference this internal-only documentation for a list of all attributes.
# Create Transfer Time
Source: https://docs.kibocommerce.com/api-reference/transfertimes/create-transfer-time
/openapi/openapi_location_admin.json post /commerce/admin/locations/transfertimes
Create transfertime between locations or location types
# Delete Transfer Time
Source: https://docs.kibocommerce.com/api-reference/transfertimes/delete-transfer-time
/openapi/openapi_location_admin.json delete /commerce/admin/locations/transfertimes/{id}
Deletes a specific transfer time
# Get Transfer Times
Source: https://docs.kibocommerce.com/api-reference/transfertimes/get-transfer-times
/openapi/openapi_location_admin.json get /commerce/admin/locations/transfertimes
Gets list of transfertimes by filter (FromId and ToId), sort and paging.
# Get Transfer Times by Locations
Source: https://docs.kibocommerce.com/api-reference/transfertimes/get-transfer-times-by-locations
/openapi/openapi_location_admin.json post /commerce/admin/locations/transfertimes/{tolocationcode}
Gets transfertimes between a specific ToLocation and a list of FromLocations
# Gets a specif transfertime by Id
Source: https://docs.kibocommerce.com/api-reference/transfertimes/gets-a-specif-transfertime-by-id
/openapi/openapi_location_admin.json get /commerce/admin/locations/transfertimes/{id}
Gets a specific transfertime by Id
# Update Transfer Time
Source: https://docs.kibocommerce.com/api-reference/transfertimes/update-transfer-time
/openapi/openapi_location_admin.json put /commerce/admin/locations/transfertimes/{id}
Update a specific transfer time
# Activate a vendor by setting its status to Active
Source: https://docs.kibocommerce.com/api-reference/vendor/activate-a-vendor-by-setting-its-status-to-active
/openapi/openapi_location_admin.json put /commerce/vendors/{vendorCode}/activate
Activate a vendor by setting its status to Active
# Add locations to a vendor (bulk operation)
Source: https://docs.kibocommerce.com/api-reference/vendor/add-locations-to-a-vendor-bulk-operation
/openapi/openapi_location_admin.json post /commerce/vendors/{vendorCode}/locations
Add locations to a vendor (bulk operation)
# Create a new vendor
Source: https://docs.kibocommerce.com/api-reference/vendor/create-a-new-vendor
/openapi/openapi_location_admin.json post /commerce/vendors
Create a new vendor
# Create a new vendor SKU mapping
Source: https://docs.kibocommerce.com/api-reference/vendor/create-a-new-vendor-sku-mapping
/openapi/openapi_location_admin.json post /commerce/vendors/{vendorCode}/skumappings
Create a new vendor SKU mapping
# Deactivate a vendor by setting its status to InActive
Source: https://docs.kibocommerce.com/api-reference/vendor/deactivate-a-vendor-by-setting-its-status-to-inactive
/openapi/openapi_location_admin.json put /commerce/vendors/{vendorCode}/deactivate
Deactivate a vendor by setting its status to InActive
# Deletes a specific vendor
Source: https://docs.kibocommerce.com/api-reference/vendor/deletes-a-specific-vendor
/openapi/openapi_location_admin.json delete /commerce/vendors/{vendorCode}
Deletes a specific vendor
# Deletes a specific vendor SKU mapping
Source: https://docs.kibocommerce.com/api-reference/vendor/deletes-a-specific-vendor-sku-mapping
/openapi/openapi_location_admin.json delete /commerce/vendors/{vendorCode}/skumappings/{upc}
Deletes a specific vendor SKU mapping
# Get all locations associated with a vendor
Source: https://docs.kibocommerce.com/api-reference/vendor/get-all-locations-associated-with-a-vendor
/openapi/openapi_location_admin.json get /commerce/vendors/{vendorCode}/locations
Get all locations associated with a vendor
# Gets a specific vendor by vendor code
Source: https://docs.kibocommerce.com/api-reference/vendor/gets-a-specific-vendor-by-vendor-code
/openapi/openapi_location_admin.json get /commerce/vendors/{vendorCode}
Gets a specific vendor by vendor code
# Gets a specific vendor SKU mapping by UPC
Source: https://docs.kibocommerce.com/api-reference/vendor/gets-a-specific-vendor-sku-mapping-by-upc
/openapi/openapi_location_admin.json get /commerce/vendors/{vendorCode}/skumappings/{upc}
Gets a specific vendor SKU mapping by UPC
# Gets list of vendor SKU mappings by filter, sort and paging
Source: https://docs.kibocommerce.com/api-reference/vendor/gets-list-of-vendor-sku-mappings-by-filter-sort-and-paging
/openapi/openapi_location_admin.json get /commerce/vendors/{vendorCode}/skumappings
Gets list of vendor SKU mappings by filter, sort and paging
# Gets list of vendors by filter, sort and paging
Source: https://docs.kibocommerce.com/api-reference/vendor/gets-list-of-vendors-by-filter-sort-and-paging
/openapi/openapi_location_admin.json get /commerce/vendors
Filter by VendorCode, Name, Status, Email, or LocationCode
# Gets vendor SKU mappings for the vendor associated with a location
Source: https://docs.kibocommerce.com/api-reference/vendor/gets-vendor-sku-mappings-for-the-vendor-associated-with-a-location
/openapi/openapi_location_admin.json get /commerce/vendors/location/{locationCode}/skumappings
Gets vendor SKU mappings for the vendor associated with a location
# Remove multiple locations from a vendor (bulk operation, idempotent)
Source: https://docs.kibocommerce.com/api-reference/vendor/remove-multiple-locations-from-a-vendor-bulk-operation-idempotent
/openapi/openapi_location_admin.json post /commerce/vendors/{vendorCode}/locations/delete
Remove multiple locations from a vendor (bulk operation, idempotent)
# Update a specific vendor
Source: https://docs.kibocommerce.com/api-reference/vendor/update-a-specific-vendor
/openapi/openapi_location_admin.json put /commerce/vendors/{vendorCode}
Update a specific vendor
# Update a specific vendor SKU mapping
Source: https://docs.kibocommerce.com/api-reference/vendor/update-a-specific-vendor-sku-mapping
/openapi/openapi_location_admin.json put /commerce/vendors/{vendorCode}/skumappings/{upc}
Update a specific vendor SKU mapping
# Update vendor locations (bulk operation with upsert or full replace)
Source: https://docs.kibocommerce.com/api-reference/vendor/update-vendor-locations-bulk-operation-with-upsert-or-full-replace
/openapi/openapi_location_admin.json put /commerce/vendors/{vendorCode}/locations
Update vendor locations (bulk operation with upsert or full replace)
# Get View Documents
Source: https://docs.kibocommerce.com/api-reference/views/get-view-documents
/openapi/openapi_content.json get /content/documentlists/{documentListName}/views/{viewName}/documents
When fullSearch is `true`, performs an exhaustive search to ensure all matching
documents are returned. May be slower on very large lists. Returns HTTP 400 if the document list exceeds
the configured maximum size (default 100,000). Defaults to `false`, which performs a faster search
optimized for recently updated documents.
# Add Item To Wishlist
Source: https://docs.kibocommerce.com/api-reference/wishlist/add-item-to-wishlist
/openapi/openapi_commerce.json post /commerce/wishlists/{wishlistId}/items
Adds an item to the wishlist of the current shopper.
# Create Wishlist
Source: https://docs.kibocommerce.com/api-reference/wishlist/create-wishlist
/openapi/openapi_commerce.json post /commerce/wishlists
Create wishlist.
# Delete Wishlist Item
Source: https://docs.kibocommerce.com/api-reference/wishlist/delete-wishlist-item
/openapi/openapi_commerce.json delete /commerce/wishlists/{wishlistId}/items/{wishlistItemId}
Delete/remove wishlist item.
# Deletes Wishlist
Source: https://docs.kibocommerce.com/api-reference/wishlist/deletes-wishlist
/openapi/openapi_commerce.json delete /commerce/wishlists/{wishlistId}
Deletes a wishlist specified by wishlist Id.
# Get Wishlist
Source: https://docs.kibocommerce.com/api-reference/wishlist/get-wishlist
/openapi/openapi_commerce.json get /commerce/wishlists/{wishlistId}
Retrieves the details of a wishlist specified by the wishlist ID.
# Get Wishlist By Name
Source: https://docs.kibocommerce.com/api-reference/wishlist/get-wishlist-by-name
/openapi/openapi_commerce.json get /commerce/wishlists/customers/{customerAccountId}/{wishlistName}
Retrieves wishlist by name.
# Get Wishlist Item
Source: https://docs.kibocommerce.com/api-reference/wishlist/get-wishlist-item
/openapi/openapi_commerce.json get /commerce/wishlists/{wishlistId}/items/{wishlistItemId}
Retrieves an individual wishlist item from a wishlist.
# Get Wishlist Items
Source: https://docs.kibocommerce.com/api-reference/wishlist/get-wishlist-items
/openapi/openapi_commerce.json get /commerce/wishlists/{wishlistId}/items
Returns a listing of wishlists.
# Get Wishlist Items By WishlistName
Source: https://docs.kibocommerce.com/api-reference/wishlist/get-wishlist-items-by-wishlistname
/openapi/openapi_commerce.json get /commerce/wishlists/customers/{customerAccountId}/{wishlistName}/items
Returns a listing of wishlists.
# Get Wishlists
Source: https://docs.kibocommerce.com/api-reference/wishlist/get-wishlists
/openapi/openapi_commerce.json get /commerce/wishlists
Retrieves a list of wishlists according to any specified filter criteria and sort options.
# Remove All Wishlist Items
Source: https://docs.kibocommerce.com/api-reference/wishlist/remove-all-wishlist-items
/openapi/openapi_commerce.json delete /commerce/wishlists/{wishlistId}/items
Clears all items in the wishlist.
# Update Wishlist
Source: https://docs.kibocommerce.com/api-reference/wishlist/update-wishlist
/openapi/openapi_commerce.json put /commerce/wishlists/{wishlistId}
Updates a wishlist specified by wishlist Id.
# Update Wishlist Item
Source: https://docs.kibocommerce.com/api-reference/wishlist/update-wishlist-item
/openapi/openapi_commerce.json put /commerce/wishlists/{wishlistId}/items/{wishlistItemId}
Updates a wishlist item.
# Update Wishlist Item Quantity
Source: https://docs.kibocommerce.com/api-reference/wishlist/update-wishlist-item-quantity
/openapi/openapi_commerce.json put /commerce/wishlists/{wishlistId}/items/{wishlistItemId}/{quantity}
Updates the quantity of an item in the wishlist.
# Get Process Definition
Source: https://docs.kibocommerce.com/api-reference/workflowprocess/get-process-definition
/openapi/openapi_fulfillment.json get /commerce/processes/definitions/{containerIdOrAlias}/{processId}
Get a specific process definition by ID.
# Get Process Definition Image
Source: https://docs.kibocommerce.com/api-reference/workflowprocess/get-process-definition-image
/openapi/openapi_fulfillment.json get /commerce/processes/definitionImage/{containerIdOrAlias}/{processId}
Get a process definition image.
# Get Process Definitions
Source: https://docs.kibocommerce.com/api-reference/workflowprocess/get-process-definitions
/openapi/openapi_fulfillment.json get /commerce/processes/definitions
Get a list of process definitions.
# Get Workflow Process By Shipment Type
Source: https://docs.kibocommerce.com/api-reference/workflowprocess/get-workflow-process-by-shipment-type
/openapi/openapi_fulfillment.json get /commerce/processes/shipmentType/{shipmentType}
Get workflow process details by shipment type.
# Get Workflow Process By Shipment Type Location Code
Source: https://docs.kibocommerce.com/api-reference/workflowprocess/get-workflow-process-by-shipment-type-location-code
/openapi/openapi_fulfillment.json get /commerce/processes/shipmentType/{shipmentType}/location/{locationCode}
Get workflow process details by shipment type and location code.
# Get Workflow Process By Shipment Type Location Group Code
Source: https://docs.kibocommerce.com/api-reference/workflowprocess/get-workflow-process-by-shipment-type-location-group-code
/openapi/openapi_fulfillment.json get /commerce/processes/shipmentType/{shipmentType}/locationGroup/{locationGroupCode}
Get workflow process details by shipment type and location group code.
# Buy Online Pickup In Store (BOPIS)
Source: https://docs.kibocommerce.com/concept-guides/bopis
Learn how BOPIS enables customers to purchase products online and collect them at physical retail locations
# **Buy Online Pickup In Store (BOPIS) Conceptual Guide**
**Buy Online Pickup In Store (BOPIS)** is a fulfillment type that enables customers to purchase products through a digital channel and collect their order at a physical retail location.
***
## **1. Strategic Overview**
**Concept Definition:** Buy Online Pickup In Store (BOPIS) is a unified commerce fulfillment method where inventory from a physical retail location is reserved for an online order and prepared for customer collection.
**Business Context:** Kibo Commerce positions BOPIS as a key **omnichannel fulfillment strategy** managed through the platform's Order Management System (OMS) and integrated storefront capabilities. It leverages real-time inventory visibility across all locations to optimize the use of existing retail store assets for digital order fulfillment.
**Value Drivers:**
1. **Optimized Inventory Utilization:** BOPIS allows retailers to treat store inventory as fulfillable stock for online sales, maximizing the return on investment in physical store inventory and reducing the need for markdowns due to slow-moving in-store products.
2. **Enhanced Customer Convenience:** It provides customers with immediate access to products by eliminating shipping wait times and costs, which significantly improves the perceived value and flexibility of the shopping experience.
3. **Increased Sales Opportunities:** Bringing customers into a physical store location for pickup creates an opportunity for store associates to engage in additional product sales, service up-sells, or cross-sells at the point of collection.
**Scope Statement:** This guide covers the functional process, configuration settings, integration points, and customer experience capabilities of the BOPIS fulfillment type, including the default workflow, inventory transfers, and customer communication. It explicitly **excludes** implementation details, API specifications, storefront code, and specific financial reporting metrics.
***
## **2. Core Concepts Explained**
### **What is BOPIS?**
BOPIS, or Pickup, is a distinct **fulfillment type** within the Kibo Commerce platform that routes a customer's order to a physical store location for processing. It is defined by its shipment process, which is designed for internal store operations rather than external shipping carriers.
Its role in the broader platform ecosystem is as a **bridge between the digital and physical channels**. The Order Management System (OMS) creates a specific BOPIS shipment, which then enters a store-centric fulfillment workflow managed typically through a dedicated Fulfiller User Interface. The process is tightly integrated with the platform's **Location** and **Inventory** services to ensure that the designated pickup location possesses the stock required to fulfill the order.
### **Why does BOPIS matter?**
BOPIS is a core strategy for blending the efficiency of digital commerce with the immediate gratification of in-person retail.
* **Operational Benefits:** By utilizing store inventory, a retailer can reduce costs associated with 'last-mile' shipping and the logistical complexity of maintaining stock exclusively in a Distribution Center (DC). It provides a mechanism to move products through the supply chain more efficiently by minimizing transit and packaging overhead for a significant segment of digital sales.
* **Financial Benefits:** The elimination of shipping costs for the customer is a powerful incentive that can mitigate cart abandonment attributed to high freight charges. For the retailer, the lower cost-to-serve for a BOPIS shipment, compared to a direct-to-consumer shipment, contributes to improved margins on those specific transactions.
* **Customer Experience Benefits:** It caters to the immediate needs of the customer by making products available in a matter of hours, often the same day, which is a key differentiator from standard home delivery. It also introduces flexibility, allowing customers to dictate the time and place of the final transaction touchpoint, resulting in higher overall customer satisfaction and loyalty.
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
The BOPIS workflow involves a collaboration between several core platform components:
* **Storefront:** The customer-facing interface where the pickup location is selected and the order is placed.
* **Inventory Service:** Provides real-time, location-specific stock availability that informs the customer during the shopping and checkout process.
* **Order Management System (OMS):** Manages the order lifecycle, creates the specific BOPIS shipment, and monitors its state transitions.
* **Location Service:** Defines and manages the physical store locations, including which locations are enabled for BOPIS fulfillment.
* **Fulfiller UI:** The application used by store associates to manage the in-store fulfillment process (e.g., picking, staging, customer handoff).
* **Email/Notification Service:** Responsible for automated customer communications based on shipment status changes.
### **Configuration-Level Deep Dive**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Location: Fulfillment Type: In Store Pickup Enabled** | Individual location setting to enable it for BOPIS. | **Impact:** Granular control over which stores can participate in complex omnichannel logic.. | A **drugstore retailer** enables BOPIS for all store locations that have a population density within a 5 mile radius of the store. |
| **BOPIS Transfer Enabled (Site)** | Controls whether fulfillment locations can request a transfer of missing inventory from another location to complete a BOPIS order. | **Impact:** Increases the probability of fulfilling an order, reducing cancellations. **Trade-off:** Adds complexity and time to the fulfillment cycle for the customer. | A **Fashion & Apparel Retailer** enables this to prevent a lost sale when a single item in a multi-item order is out of stock in the pickup store. |
| **Action on BOPIS Reject (Site)** | Determines the system's action when a store associate rejects a BOPIS shipment (e.g., due to stock discrepancy or damage). | **Options: Cancel** (terminates the shipment) or **Customer Care** (routes the shipment to a manual resolution queue). **Impact:** Controls the outcome of fulfillment failure. **Trade-off:** Cancellation is faster but a lost sale; Customer Care is slower but may allow for saving the sale. | An **Enterprise Electronics Retailer** selects **Customer Care** so an agent can offer the customer a substitution or home delivery instead of an immediate cancellation. |
| **Ready for Pickup & Pickup Reminder Email Templates** | Enablement of customer-facing emails to inform that the order is ready for pickup. Reminder emails can be sent if order is not picked up. | **Impact:** Improves transparency and manages customer expectations during the extended fulfillment cycle. | A **Direct-to-Consumer (DTC) Brand** enables *Ready for Pickup Email* to proactively inform a customer that their highly anticipated product is ready for Pickup |
***
## **4. Key Capabilities and Business Applications**
### **Capability: Store Locator and Inventory Availability**
**Functional Explanation:** The platform enables the dynamic display of physical store locations and their respective inventory levels during the shopping journey. A customer can select a store and view if a product is available for BOPIS fulfillment at that specific location. The capability includes pre-built storefront components to manage location selection and to validate stock-to-location linkages during the cart and checkout processes.
**Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** A customer is purchasing a high-value television and wants to pick it up immediately. On the Product Detail Page, the system instantly shows the television is "In Stock" at the selected store, confirming availability for pickup. The BOPIS option is enabled in their cart.
* **Outcome:** The seamless confirmation of immediate availability encourages the customer to complete the purchase instantly, **resulting in a higher conversion rate for high-value items** where immediacy is a strong purchase driver.
### **Capability: Default BOPIS Fulfillment Workflow**
**Functional Explanation:** A standard, linear process for store associates to manage the BOPIS shipment. This process transitions the shipment through key states: **Accept Shipment** (store acknowledges the order), **Print Pick Sheet** (generates a document to locate items), **Validate Stock** (physical confirmation of item availability) and finally **Provide to Customer** (hand-off to the customer). This workflow is the foundation for simple, on-hand pickups.
**Business Application Example:**
* **Industry:** Fashion & Apparel Retailer
* **Scenario:** A customer orders a new winter coat online for pickup at their nearest mall store. A store associate receives the new BOPIS shipment in their Fulfiller UI, **Accepts** it, prints the **Pick Sheet**, and quickly locates all items in the store's back stock. After a final **Stock Validation**, the associate stages the bag and "Ready for Pickup" notification is automatically sent to the customer.
* **Outcome:** The streamlined process ensures a rapid in-store fulfillment time, which **results in a faster customer notification and an elevated perception of the retailer's operational efficiency**.
### **Capability: BOPIS Shipment with Service Items**
**Functional Explanation:** For BOPIS shipments that include a service product (e.g., assembly, engraving), the standard flow is modified to include an **Order Preparation** step situated between **Validate Stock** and **Customer Pickup**. This distinct step ensures that any required in-store value-added service is completed before the customer is notified that the entire order is ready for collection.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A contractor orders a complex industrial pump and includes a professional "Pre-Assembly Inspection and Calibration" service item with the BOPIS order. The store associate completes the **Validate Stock** step, and the shipment automatically moves to **Order Preparation**. A technician then performs the calibration. Once the service is complete, the shipment can proceed to **Customer Pickup**.
* **Outcome:** The mandatory preparation step prevents the customer from arriving before the service is finished, **resulting in fewer service complaints and a reduction in lost labor time due to rushed or incomplete preparation**.
### **Capability: Transfer Shipments for Out-of-Stock Items**
**Functional Explanation:** When the **Validate Stock** step confirms that some items are missing for a BOPIS shipment, the system can initiate a **Transfer Shipment**. A child shipment is created, routed to a designated transfer location (another store or DC), and the original BOPIS shipment is placed into a **Waiting for Transfer** state. This capability requires location-level and system-level configuration enablement.
**Business Application Example:**
* **Industry:** Direct-to-Consumer (DTC) Brand
* **Scenario:** A customer orders three unique scented candles from a DTC brand's website for pickup at a boutique location. The store only has two in stock. During **Validate Stock**, the associate identifies the missing candle and initiates a **Transfer Shipment** request from a nearby inventory hub.
* **Outcome:** The ability to source the missing item from another location prevents an immediate loss of sale, **resulting in the capture of the full order value and a positive outcome for the customer** who receives all their desired items.
### **Capability: Partial Pickup for Waiting Shipments**
**Functional Explanation:** If a BOPIS shipment is in the **Waiting for Transfer** state, a store associate has the option to offer a **Partial Pickup**. This splits the immediately available items into a new, separate shipment that can be fulfilled on the spot. The customer can take the available items, and the original shipment remains in the waiting state for the transferred inventory. The customer is notified with a *Partial Pickup Ready* email.
**Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** A customer's order for a laptop (in stock) and a special-order keyboard (waiting for transfer) is being processed. The customer arrives, wanting the laptop immediately. The associate executes a **Partial Pickup**, hands over the laptop, and the new shipment is marked **Fulfilled**. The original shipment for the keyboard continues to wait for the transfer.
* **Outcome:** Providing the customer with the option to take available items right away delivers a highly flexible experience, **resulting in immediate customer gratification and the maintenance of the remaining sale** without forced cancellation.
### **Capability: Automated Pickup Reminders and Auto Cancellation**
**Functional Explanation:** The platform's fulfillment messaging service manages a series of automated emails to the customer. These include **Order Pickup Ready** and, after a configurable delay, **Order Pickup Reminder** emails.
**Business Application Example:**
* **Industry:** Marketplace Operator
* **Scenario:** A customer receives the **Order Pickup Ready** email for their item from a third-party seller's boutique location. After three days, the system automatically triggers an **Order Pickup Reminder** email to the customer's primary email address, reminding them the item is still reserved and waiting. If the item is still not picked up after a longer, business-defined window, the system will put the order in Customer Care/Cancellation.
* **Outcome:** The use of automated reminders prompts customers to collect their orders promptly, **resulting in the reduction of inventory holding time within the store and a quicker restock of uncollected items**.
***
## **5. Platform Integration Map**
### **Upstream Dependencies**
| Dependency | Description |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Locations and Inventory** | Requires that physical store locations are configured, enabled for fulfillment, and have their accurate stock levels reported to the Inventory Service. |
| **Site Settings** | General system settings, particularly those related to **Transfers** and the **Action on BOPIS Reject**, must be configured to define the default business rules for the BOPIS workflow. |
| **Email Templates** | Requires the relevant customer communication email templates (*Order Pickup Ready*, *Order Pickup Reminder*, *Partial Pickup Ready,Transfer Shipment Created/Shipped*) to be enabled and configured within the general site settings. |
### **Downstream Impacts**
| Impacted System/Process | Description |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order History** | The BOPIS fulfillment process updates the order and shipment statuses, providing customers and Customer Service Representatives (CSRs) with real-time tracking visibility. |
| **Payment Gateway** | Upon fulfillment, the system triggers the final capture of any authorized payment amount, completing the financial transaction. |
### **Synergistic Features**
| Feature | Combined Value Proposition |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Returns Management** | A BOPIS order, once fulfilled, is often eligible for an in-store return. This synergy provides a seamless post-purchase experience by allowing the customer to return the item to the same channel they used for pickup, further driving store traffic. |
| **Product Service Items** | The integration of service items into the BOPIS flow allows retailers to sell value-added services (e.g., assembly, preparation) that are completed in the store prior to pickup, capturing additional revenue per order. |
***
## **6. Related Documents**
For foundational knowledge, refer to:
* **[Location Admin](/developer-guides/location-admin):** Set up for Locations to support Fulfillment Type BOPIS. Accurate location configuration is important for BOPIS location assignment.
* **[Inventory](/concept-guides/inventory):** This guide is a prerequisite to understanding BOPIS, as real-time inventory visibility across the retail network is important for BOPIS order placement.
* **[Order Routing](/concept-guides/order-routing):** This covers details of supporting BOPIS with Transfers.
* **[Catalog](/concept-guides/catalog):** Set up for Products for fulfillment types supported.
To understand downstream impacts, refer to:
* **[Fulfillment](/concept-guides/fulfillment):** This guide details the workflows for fulfilling BOPIS Orders
# Cart & Checkout
Source: https://docs.kibocommerce.com/concept-guides/cart-and-checkout
Explore cart and checkout capabilities for aggregating shopper selections and finalizing transactions
# **Kibo Commerce Platform Conceptual Guide: Cart & Checkout**
See the Cart API documentation for programmatic access
See how a CSR can take over and edit a shopper's active cart
## **1. Strategic Overview**
**Concept Definition:** Cart & Checkout is the set of platform capabilities responsible for aggregating shopper selections, determining final order costs, collecting necessary shopper and fulfillment details, and finalizing the transaction through payment and order placement.
**Business Context:** The Kibo Commerce Cart & Checkout capabilities are positioned as the core conversion engine, ensuring a flexible, consistent, and reliable path to purchase. It is designed to handle the complexities of enterprise e-commerce, including varied fulfillment models and intricate pricing logic.
**Value Drivers:**
* **Conversion Optimization:** The system streamlines the path-to-purchase, reducing friction points by offering flexible shopper identity options (registered or anonymous) and utilizing express checkout features to minimize cart abandonment.
* **Omnichannel Fulfillment Enablement:** It supports a wide array of fulfillment options, allowing retailers to integrate physical store inventory and services into the digital checkout flow, enhancing inventory utilization and offering superior customer choice.
* **Financial Accuracy and Compliance:** With internal promotion, tax, and shipping engines, the platform ensures precise calculation of all financial components, providing transparent pricing.
**Scope Statement:** This guide explains the core functional components, configurable attributes, fulfillment capabilities, and financial structures of the Cart & Checkout features, enabling non-technical stakeholders to make informed deployment decisions. It explicitly excludes implementation details, API specifications, and database schemas.
***
## **2. Core Concepts Explained**
### **What is Cart & Checkout?**
The **Cart** object is a dynamic, persistent container that aggregates the items a shopper intends to purchase. It is the initial stage of the transaction process, storing selected products, quantities and applied promotions. The **Checkout** is the subsequent, stateful process where the system validates all order details—including shopper identity, fulfillment method, shipping address(es), final costs, and payment information—before creating a formal order. The key functional role is to bridge product selection with order finalization, managing the inherent complexity of financial calculations and fulfillment logistics.
### **Why does Cart & Checkout matter?**
Cart & Checkout capabilities significantly impact **operational efficiency** by centralizing complex logic for shipping, taxation, and promotions, reducing manual intervention and error rates. **Financial benefits** are realized through dynamic, accurate cost determination and the ability to deploy sophisticated promotional strategies via the platform's promotion engine. From a **customer experience** standpoint, a flexible checkout that supports multi-shipment options, diverse payment methods, and express features translates directly into a seamless, trusted, and low-friction shopping journey.
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
The Cart & Checkout functionality is built on a service-oriented architecture:
* **Cart Service:** Manages item aggregation, quantity updates, and initial promotional application.
* **Checkout Service:** Manages shipping/fulfillment selection, payment information capture, tax calculation, and order placement.
* **Catalog Service:** Provides definitive product information, including current pricing, product details, and inventory assignments, which are referenced when an item is added to the cart.
* **Promotion Engine:** Applies discounts based on configured rules, affecting item, order, and shipping costs.
* **Inventory Service:** Provides inventory availability for items in the order
* **Payment Service:** Manages tokenization and payment authorization via the payment gateways.
### **Configurations Deep Dive**
| Configuration Needed | Business Purpose | Impact and Trade-offs | Concrete Example |
| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment Gateway Credentials** | Controls the connection to the external service responsible for processing and authorizing payments. | Proper configuration is mandatory for transaction finalization; incorrect settings will result in failed checkouts and conversion loss. | An Enterprise Electronics Retailer sets up Cybersource as their payment gateway in the Kibo Admin. |
| **Shipping Carrier Accounts** | Defines and connects the platform to preferred external carriers to retrieve real-time shipping methods and rates. | Using live carrier rates ensures shipping cost accuracy but introduces external service latency into the checkout time. | A Fashion & Apparel Retailer configures their FedEx and USPS accounts to offer calculated rates for Next-Day, Ground, and other services. |
| **Tax Service Integration Setup** | Establishes the connection and parameters for the service that calculates real-time, geo-specific sales and use taxes. | Integration with a third-party service ensures tax compliance across various jurisdictions but requires ongoing maintenance of product tax classifications. | A DTC Brand sets up their Avalara tax integration,for accurate tax collection at checkout. |
| **Reservation Timeout (Cart)** | Specifies how long inventory is reserved for items in an active cart. | Shorter times free up inventory faster for other shoppers; longer times increase the chance a shopper completes their purchase. | An Enterprise Electronics Retailer sets a 15-minute reservation on high-demand, limited-stock gaming consoles. |
***
## **4. Key Capabilities and Business Applications**
### **Capability: Multi-Shipment/Multi-Ship-To (MST)**
**Functional Explanation:** This capability allows a shopper to assign different line items within a single cart to distinct shipping addresses and fulfillment methods. The system handles the resulting complexity by breaking the cart into multiple logical shipments, each calculated independently for shipping rates, while consolidating them under a single, unified order and checkout process.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A procurement manager for a large manufacturing firm places an order for 100 specialized tools. They need 50 of the tools sent to their primary warehouse and the remaining 50 sent directly to a sub-contractor's workshop across the country. They leverage the **Multi-Ship-To** capability in the checkout to define two distinct destinations within the same transaction.
* **Qualitative Business Outcome:** This single-transaction capability simplifies the purchasing manager's workflow, consolidates invoicing, and results in improved client satisfaction and higher average order value (AOV) for the distributor.
### **Capability: Support for Diverse Fulfillment Types**
**Functional Explanation:** The platform is engineered to support various fulfillment models within a single cart and checkout. The shopper can select different fulfillment types for different line items or entire shipments, including standard **Ship-to-Home**, **Buy Online, Pick Up In Store (BOPIS)**, **Curbside Pickup**, or local **Delivery** via third-party services. The platform dynamically validates inventory availability and eligibility for each method based on the shopper's location and product attributes.
**Business Application Example:**
* **Industry:** Fashion & Apparel Retailer (Omnichannel)
* **Scenario:** A shopper adds a pair of jeans (available only at the central warehouse) and a newly released seasonal jacket (available at a nearby physical store) to their cart. During checkout, they assign the jeans to **Ship-to-Home** and select **BOPIS** for the jacket, picking it up in two hours.
* **Qualitative Business Outcome:** This flexibility maximizes the use of both warehouse and store inventory, avoids lost sales due to item unavailability, and offers a superior, convenient customer experience, resulting in fewer customer support calls about delayed or split orders.
### **Capability: Cart Inventory Reservation**
**Functional Explanation:** When a product is added to a cart, the platform is able to initiate a temporary inventory reservation for that item, holding the stock aside so that other simultaneous shoppers cannot claim the inventory. This is an important function for managing limited or high-demand stock. The reservation is held for a configurable timeout duration and automatically released if the shopper abandons the cart or the timeout is exceeded, ensuring efficient inventory turnover.
Business Application Example:
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** A high-demand, limited-edition video game console is released. To prevent shoppers from reaching the final payment step only to find the item is out of stock, the retailer configures the system to reserve the console's inventory for 15 minutes once it is placed in a cart.
* **Qualitative Business Outcome:** This capability provides the shopper with confidence that the item is secured while they complete the checkout process, significantly reducing last-minute fulfillment failures and improving the overall fairness of high-demand sales events.
### **Capability: Express Checkout for Registered Users**
**Functional Explanation:** The platform allows registered shoppers to significantly accelerate the checkout process by automatically populating required billing, shipping, and payment information from their stored customer account data. The system utilizes tokenized payment information for security and allows the shopper to complete the transaction with minimal clicks or data entry. This feature is reliant on the shopper having a verified, persistent account with saved details.
Business Application Example:
* **Industry:** Direct-to-Consumer (DTC) Brand
* **Scenario:** A repeat customer of a DTC coffee subscription service logs into their account to make a one-time purchase of a new grinder. Because their default shipping address and tokenized credit card information are already stored, the system presents an Express Checkout option, allowing them to bypass several steps of the standard flow.
* **Qualitative Business Outcome:** By minimizing data entry for repeat customers, the system drastically reduces checkout friction and minimizes the likelihood of cart abandonment, leading directly to higher customer retention and faster transaction times.
### **Capability: Integration with External Promotion Engines**
**Functional Explanation:** While Kibo Commerce features a robust **internal promotion engine** capable of complex rules (e.g., BOGO, percentage off, fixed price), the platform also provides documented integration points to connect with **third-party promotion engines** or Customer Relationship Management (CRM) systems. This allows a retailer to use external loyalty programs or pricing logic as the source of truth for applying discounts in the cart, offering maximum flexibility in promotional strategy. The external service is called during the pricing calculation phase in the cart/checkout process.
**Business Application Example:**
* **Industry:** Marketplace Operator (Multi-vendor management)
* **Scenario:** A Marketplace Operator runs a complex, tiered loyalty program managed by a specialized external platform. When a shopper adds items to the cart, the system calls the third-party engine to determine if the shopper qualifies for a "Tier 3 Loyalty Member 20% off all vendors" promotion.
* **Qualitative Business Outcome:** This architecture allows the retailer to leverage advanced, personalized promotional logic without rebuilding complex loyalty systems, thereby achieving greater strategic flexibility and improved customer retention.
### **Capability: Persistence and API Accessibility**
**Functional Explanation:** The Kibo Commerce cart is a persistent object, meaning that once a shopper (registered or anonymous) adds items, that cart state is maintained across sessions and devices. Additionally, the platform provides robust, decoupled **Cart APIs** that allow the use of the platform's core pricing, fulfillment, and promotion logic **without dependence on the visual theme or storefront technology**. This headless capability supports building custom front-ends or integrating with novel sales channels like kiosks or mobile applications.
**Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** The retailer decides to launch a new, highly customized Progressive Web App (PWA) on a framework outside of the standard Kibo theme. They use the **Kibo Cart APIs** to manage all product adding, tax calculation, and payment authorization through the PWA's custom user interface.
* **Qualitative Business Outcome:** This approach ensures that the new, innovative front-end benefits from the enterprise-grade stability and accuracy of the Kibo pricing and payment services, accelerating time-to-market for new channels while minimizing integration risk.
### **Capability: Support for Diverse Payment Types (Including Third-Party)**
**Functional Explanation:** The Cart & Checkout is designed to accept standard payment methods (Credit Card, Debit Card) and supports multiple non-traditional and **third-party payment types**. This includes popular methods like **PayPal, Apple Pay,** and specialized options such as **gift cards & store credits**. The system handles the complex logic of payment authorization & partial payments.
**Business Application Example:**
* **Industry:** DTC Brand (Subscription models, customer acquisition focus)
* **Scenario:** A shopper is buying a high-value item and wishes to spread the cost. The checkout displays the option to pay with their standard credit card or Amazon pay. The shopper selects the amazon pay option, and the system securely communicates the order total for immediate financing authorization.
* **Qualitative Business Outcome:** Offering a broader range of payment methods, particularly third-party financing options, lowers the barrier to purchase, resulting in reduced cart abandonment and the potential for a higher overall AOV.
***
## **5. Platform Integration Map**
**Upstream Dependencies:**
* **Product Data Model:** Required for product existence, pricing, and tax classification codes.
* **Inventory Management:** Required for real-time stock levels, BOPIS validation, and inventory reservations.
* **Customer Accounts:** Required for enabling Express Checkout and retrieving saved addresses/payment tokens.
**Downstream Impacts:**
* **Order Management System (OMS):** The completed checkout creates the formal Order object, triggering fulfillment and payment capture processes.
* **Reporting & Analytics:** Transactional data feeds into business intelligence for sales analysis and abandonment tracking.
* **Payment Gateway:** Receives authorization and capture requests.
**Synergistic Features:**
* **Promotion Engine:** The promotion rules and logic are directly consumed by the Cart for real-time discount application, creating a unified pricing strategy and value communication to the shopper.
* **Shipping & Tax Services:** Integration with these services (internal or external) ensures that the cart calculates final, accurate landed costs, reducing post-purchase adjustments.
***
## **6. Related Documents**
**For foundational knowledge, refer to:**
* **[Catalog](/concept-guides/catalog):** Explains how products are defined, classified, and priced, which is a prerequisite for adding any item to the Cart.
* **[Customer API](/developer-guides/customer):** Explains the creation and persistence of shopper records, which is essential for Express Checkout and leveraging saved information.
**To understand downstream impacts, refer to:**
* **[Fulfillment](/concept-guides/fulfillment):** Explains how the completed Checkout is transformed into a manageable order, governing subsequent lifecycle steps like fulfillment and return authorization.
**For complementary strategies, refer to:**
* **[Promotions](/concept-guides/promotions):** Explains the full range of configurable rules and tiers that are applied and calculated by the Cart & Checkout features to achieve strategic sales goals.
***
# Catalog and Product Architecture
Source: https://docs.kibocommerce.com/concept-guides/catalog
Learn how catalogs, sites, categories, and products work together to power your commerce experience
# **Kibo Commerce Conceptual Guide: Catalog, Product, and Site Architecture**
Learn about product catalog architecture and management
See the Admin Catalog API documentation for programmatic access
See the Storefront Catalog API documentation
See how to create a new catalog in Kibo
Learn how to configure and manage sites
### **1. Strategic Overview**
This guide provides a comprehensive conceptual overview of the entire Kibo Commerce catalog architecture, from the foundational structure of **Catalogs** and **Sites** to the detailed organization of **Categories** and **Products**. A complete understanding of how these interconnected layers function is the most important step in managing a successful, scalable e-commerce operation on the platform. This architecture governs how your product universe is stored, how sales channels are defined, how products are organized for discovery, and how each item is defined with precision.
* **Concept Definition:** The Kibo Commerce catalog is a hierarchical system where Catalogs act as containers for product information, Sites serve as the transactional endpoints where products are sold, Categories organize those products for navigation, and Products are the detailed records of the items themselves.
* **Business Context:** This integrated structure allows a business to manage a diverse, multi-channel retail operation from a single platform. It enables the creation of user-friendly shopping experiences, automates merchandizing with rules-based logic, and manages complex product variations with accuracy, directly impacting everything from international expansion and operational efficiency to customer conversion rates.
* **Scope Statement:** This document covers the complete catalog architecture: Master Catalogs, Child Catalogs, Sites, the three types of Categories (Static, Dynamic Precomputed, Dynamic Realtime), Product Types, Product Attributes (Options, Properties, Extras), and all associated configurable settings. It explicitly excludes pricing and [price list](/pages/price-lists) configurations, which are covered in a separate guide.
***
### **2. Core Concepts Explained: From Global Structure to Granular Detail**
The Kibo Commerce platform organizes your business in a clear, top-down hierarchy. It begins with the foundational layer of Catalogs and Sites, which defines the overall structure. Within that structure, the merchandizing layer of Categories and Products is used to organize and define the specific items you sell.
#### **2.1 The Foundational Layer: Catalogs and Sites**
##### **The Master Catalog: Your Central Product Database**
A [Master Catalog](/pages/master-catalogs) is the definitive, centralized repository for every product you intend to sell across any channel. Think of it as your primary Product Information Management (PIM) system built directly into the platform. Its core purpose is to ensure that there is one—and only one—master record for each product, preventing data inconsistencies across your business. Every product, with its universal attributes like SKU, weight, and default description, must be created in a Master Catalog first.
* **Business Application Example:**
* **Industry:** Global Electronics Manufacturer
* **Scenario:** A company sells hundreds of electronic components globally. By creating a single "Global Master Catalog," they ensure that the core technical specifications for a specific microchip are identical whether it's being viewed by a distributor in North America or an engineer in Europe. This prevents costly errors stemming from inconsistent product data.
##### **The Child Catalog: Your Curated Storefront Assortment**
A [Child Catalog](/pages/catalog-and-site-structure-settings-2) (referred to simply as a "Catalog" in the admin interface) is a subset of products inherited from a Master Catalog, curated for a specific purpose. Its primary function is to allow you to **override** the master product data without altering the original record. This inheritance model is the key to efficiently managing different brands, regions, or stores.
* **Business Application Example:**
* **Industry:** Fashion & Apparel Retailer
* **Scenario:** A retailer has a Master Catalog with their entire clothing line. They create a "Canadian Retail" Child Catalog. Within this catalog, they override product descriptions to include both English and French and adjust prices to Canadian dollars. For the winter season, they create a "Holiday Sale" discount that applies *only* to this Canadian catalog, leaving their US and European operations unaffected.
##### **The Site: Your Transactional Channel**
If a Catalog defines *what* products are for sale, a Site defines *where* and *how* they are sold. A Site is any transactional endpoint in your business. The architectural rule is simple but powerful: a Site must be linked to one and only one Catalog, but a single Catalog can power many Sites. Notably, a "Site" is an abstract concept that extends beyond a website and can represent a B2B portal, a physical store, or even a marketplace like Amazon.
* **Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A distributor has a "North American Products" Child Catalog. They link this single catalog to three different Sites: their public e-commerce website, a physical warehouse for pickups, and a dedicated portal for their largest client. All three Sites sell from the same product assortment, but the transactional rules (like payment gateways) are configured independently for each.
#### **2.2 The Merchandizing Layer: Categories and Products**
##### **Categories: Structuring the Shopper Journey**
Categories are the primary tool for organizing products into logical groups, which in turn powers your site's navigation and helps shoppers find what they're looking for. Kibo Commerce offers three distinct types of categories:
* **Type 1: [Static Categories](/pages/static-categories):** A merchandiser manually and individually assigns products to the category. This provides maximum control and is ideal for building the permanent navigational hierarchy of your site (e.g., "Apparel" > "Tops" > "T-Shirts") or creating carefully curated collections like a "Holiday Gift Guide."
* **Type 2: [Dynamic Precomputed Categories](/pages/dynamic-categories):** This category type uses a logical expression (e.g., properties.brand eq 'Sony') to automatically populate itself with products. The system evaluates this rule when the catalog is indexed (an offline process), meaning the category loads very quickly for shoppers. It's perfect for brand pages or feature-based collections.
* **Type 3: Dynamic Realtime Categories:** This is the most flexible type, evaluating its rule "on-the-fly" when a shopper visits the page. See [Dynamic Categories](/pages/dynamic-categories) for more details. Its unique capability is that the expression can evaluate a product's final, discounted **sale price**, making it ideal for time-sensitive pages like "Clearance Under \$50."
##### **Product Types: Creating Consistent Product Blueprints**
A **[Product Type](/pages/product-types-overview)** is a template that defines the structure, attributes, and available settings for a specific group of products. Every product in your catalog must be assigned to a single Product Type. This ensures consistency and makes catalog-wide updates simple and error-free. While a default "Base Product Type" exists, it is a best practice to create custom Product Types (e.g., "Apparel," "Electronics") for different kinds of products.
* **Business Application Example:**
* **Industry:** Footwear Retailer
* **Scenario:** The retailer creates a "Shoe" Product Type. They add attributes like Size, Color, Width, and Material to this template. Now, every time a new shoe is added to the catalog, it automatically inherits these fields, ensuring no essential information is missed.
##### **Product Attributes: The Building Blocks of Product Data**
[Product Attributes](/pages/product-attributes-overview) are the individual data points that describe a product. Kibo Commerce makes a key distinction between three types:
* **Type 1: [Options](/pages/option-attributes):** These are attributes a shopper can select to configure a product, like Size or Color. The most important characteristic is that **each unique combination of selected values generates a new [product variation](/pages/product-variations) with a unique SKU**. This is essential for accurate, variant-level inventory tracking.
* **Type 2: [Properties](/pages/property-attributes):** These are inherent, non-configurable details about a product, like Brand or Material. Shoppers can see them and use them for filtering, but they cannot change them. Properties **do not** generate new SKUs.
* **Type 3: [Extras](/pages/extra-attributes):** These are optional add-on products or services a shopper can add during purchase, typically for an additional cost. They are a key tool for upselling and can include services like Gift Wrapping or other products like an Extended Warranty.
***
### **3. Functional Components & Configuration Deep Dive**
This section details every configurable attribute for the entire catalog architecture, from the highest-level structures down to individual products.
#### **3.1 Master Catalog Configuration**
| Name | Business Purpose | Available Options/Data Type | Concrete Example |
| :---------------------- | :------------------------------------------------------------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------- |
| **Catalog Type** | Defines the object as a Master Catalog. | Dropdown: Master Catalog | This must be selected to create the top-level product container. |
| **Master Catalog Name** | A human-readable identifier for the global product set. | Text | "Global Footwear Master Catalog" |
| **Default Locale Code** | Sets the primary language and region for product data. | Dropdown list of locale codes (e.g., en-US, en-GB). | Setting this to en-US means all product descriptions will default to US English. |
| **Supported Locales** | Defines all additional languages into which child catalogs can translate product data. | Multi-select list of locale codes. | Selecting fr-FR and de-DE allows you to create French and German child catalogs. |
| **Currency Code** | Sets the primary currency for the master set of products. | Dropdown list of ISO currency codes (e.g., USD, EUR). | Setting this to USD establishes the baseline currency for all products. |
#### **3.2 Child Catalog (Catalog) Configuration**
| Attribute Name | Business Purpose | Available Options/Data Type | Concrete Example |
| :---------------------- | :-------------------------------------------------------------------------------------------------- | :----------------------------------------- | :------------------------------------------------------------------------------------- |
| **Catalog Type** | Defines the object as a Child Catalog. | Dropdown: Catalog | This must be selected to create a catalog that inherits from a master. |
| **Master Catalog** | Establishes the inheritance relationship, determining which products are available to this catalog. | Dropdown list of existing Master Catalogs. | Selecting "Global Footwear Master Catalog" makes all footwear products available here. |
| **Catalog Name** | A human-readable identifier for this specific catalog. | Text | "Canadian Winter Season Catalog" |
| **Default Locale Code** | Sets the primary language for this specific catalog. | Dropdown list of locales. | Selecting fr-CA means this catalog's product data will be in Canadian French. |
| **Currency Code** | Sets the primary currency for this specific catalog, which can differ from the master. | Dropdown list of ISO currency codes. | Setting this to CAD ensures all prices in this catalog are in Canadian Dollars. |
When the child catalog's currency differs from the master catalog's, product prices are not converted automatically. Product variations in particular have no fallback to the master catalog price: every variation must be given a localized price in the child catalog's currency, or its configurable product will be excluded from that catalog's storefront. Refer to [Multi-Currency Catalogs](/pages/multi-currency-catalogs "Multi-Currency Catalogs").
#### **3.3 Site Configuration**
| Attribute Name | Business Purpose | Available Options/Data Type | Concrete Example |
| :--------------- | :----------------------------------------------------------------------------------------- | :---------------------------------------- | :---------------------------------------------------------------------------------- |
| **Site Name** | The identifier used within the Kibo Commerce admin to select the site's context. | Text | "US Retail Website" or "Chicago Flagship Store" |
| **Storefront** | A toggle to indicate if the site is an online storefront that shoppers can visit directly. | Yes/No Toggle | Set to "Yes" for your e-commerce website, but "No" for a physical store location. |
| **Catalog** | The mandatory link to the one catalog that will supply products to this site. | Dropdown list of existing Child Catalogs. | Linking this site to the "US Retail Catalog" ensures it sells the correct products. |
| **Country Code** | The primary country of operation for the site, used for address and tax logic. | Dropdown list of country codes. | Selecting US configures the site for operation within the United States. |
| **Locale Code** | The site's language, which must be one of the locales supported by its associated catalog. | Dropdown list of locale codes. | Selecting en-US ensures the site displays content in US English. |
#### **3.4 Category Attribute Configuration**
| Attribute Name | Business Purpose | Available Options/Data Type | Concrete Example |
| :---------------------- | :---------------------------------------------------------------------------------- | :----------------------------------------- | :----------------------------------------------------------------------------------------- |
| **Attribute Label** | The user-facing name of the attribute. | Text | "Is Featured" |
| **Administration Name** | An internal name for administrative purposes. | Text | "is\_featured\_category" |
| **Display Group** | Determines if the attribute is visible only in the admin or also on the storefront. | Dropdown: Admin Only, Admin and Storefront | Set to Admin and Storefront if you want to display a special badge on featured categories. |
| **Input Type** | The type of data the attribute will hold. | List, Text box, Text area, Date, Yes/No | For "Is Featured," the input type would be Yes/No. |
#### **3.5 Product Configuration**
##### **General Settings**
| Attribute Name | Business Purpose | Concrete Example |
| :------------------------- | :------------------------------------------------------- | :-------------------------------------------------------------------------- |
| **Product Title** | The customer-facing name of the product. | "Men's Classic Crewneck T-Shirt" |
| **Product Code** | A unique internal identifier (SKU or style number). | "M-TSHIRT-CREW-CLASSIC" |
| **Product Type** | The template the product is based on. | Assigning the "Apparel" product type. |
| **Product Usage** | Defines the product's behavior (Standard, Bundle, etc.). | Selecting "Product with Variations" because it comes in sizes and colors. |
| **Short/Long Description** | Customer-facing text describing the product. | A short marketing blurb and a longer detailed description with fabric care. |
| **Product Image** | The primary images for the product. | Uploading high-resolution studio shots of the t-shirt. |
##### **Status & Scheduling (Child Catalog Level)**
| Attribute Name | Business Purpose | Concrete Example |
| :------------------------ | :----------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **Status** | Controls the product's visibility in a specific catalog. | Setting a new product to Disabled until it is ready to go live. |
| **Active Start/End Date** | Automatically activates/deactivates a product on a schedule. | Scheduling a seasonal holiday product to be Active only from Nov 1 to Dec 31. |
##### **Inventory**
| Attribute Name | Business Purpose | Concrete Example |
| :------------------------ | :------------------------------------------------ | :--------------------------------------------------------------------------- |
| **Out of Stock Behavior** | Defines what happens when inventory reaches zero. | Setting the behavior to "Allow Backorder" for a popular, replenishable item. |
##### **Shipping**
| Attribute Name | Business Purpose | Concrete Example |
| :---------------------- | :------------------------------------------------- | :--------------------------------------------------------- |
| **Fulfillment Methods** | Specifies how the product can be delivered. | Enabling both Direct Ship and In-Store Pickup for an item. |
| **Must Ship Alone** | Flags items that cannot be boxed with other items. | Toggling this on for a large, fragile mirror. |
| **Weight/Dimensions** | Provides data for calculating shipping rates. | Entering 5 lbs and dimensions of 12x8x4 inches. |
##### **Categories (Child Catalog Level)**
| Attribute Name | Business Purpose | Concrete Example |
| :-------------------- | :-------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- |
| **Static Categories** | Assigns the product to one or more static categories for navigation. | Adding the t-shirt to the "Men's > Tops > T-Shirts" category. |
| **Primary Category** | If in multiple categories, this defines the breadcrumb trail on the product page. | Setting "T-Shirts" as the primary category so the breadcrumb is always consistent. |
##### **SEO (Search Engine Optimization)**
| Attribute Name | Business Purpose | Concrete Example |
| :------------------- | :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| **Meta Title** | The text shown in the browser tab and as the main link in Google search results. | "Men's Classic Cotton Crewneck T-Shirt |
| **Slug** | The user-friendly keyword-rich part of the URL. | The URL becomes .../mens-classic-cotton-tshirt/p/M-TSHIRT-CREW\... |
| **Meta Description** | The short summary that appears under the title in search results. | "Shop the perfect everyday tee. Our men's classic crewneck is made from 100% soft, breathable cotton..." |
***
### **4. Key Capabilities and Business Applications**
This section details the practical value of the complete catalog architecture by exploring its core capabilities.
**Capability: Centralized Product Information Management (PIM)**
* **Functional Explanation:** The Master Catalog acts as a single, authoritative source for all core product data. Any update made to a product in the Master Catalog can be automatically inherited by all its Child Catalogs, ensuring consistency and dramatically reducing manual effort.
* **Business Application Example:**
* **Industry:** Consumer Packaged Goods (CPG) Brand
* **Scenario:** A CPG brand updates the nutritional information for a food product in the Master Catalog once. This change is instantly reflected on their B2C website, B2B portal, and mobile app feed, ensuring regulatory compliance everywhere.
**Capability: Multi-Storefront and Regional Expansion**
* **Functional Explanation:** The Child Catalog and Site structure is purpose-built to enable rapid expansion. A new Child Catalog can be created to inherit the base product set, with specific overrides for local language, currency, and assortment. A new Site is then created and pointed to this catalog to launch a fully localized experience.
* **Business Application Example:**
* **Industry:** DTC Apparel Brand
* **Scenario:** A US brand expands to the UK by creating a "UK Market" Child Catalog, overriding prices to GBP and descriptions to UK English. They launch a new "UK Storefront" Site linked to this catalog, accelerating their time-to-market.
**Capability: True Omnichannel Operations**
* **Functional Explanation:** By abstracting the concept of a "Site" to be any transactional endpoint (web, physical store, call center), Kibo Commerce enables centralized order processing, inventory visibility, and customer management across all channels.
* **Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** A customer buys a laptop online (Site 1) and chooses to pick it up in-store (Site 2). The order is seamlessly routed to the store for fulfillment, inventory is updated in real-time, and the customer has a smooth, unified experience.
**Capability: Precise, Variant-Level Inventory Management**
* **Functional Explanation:** By correctly using the "Option" attribute type, businesses generate unique SKUs for every sellable [variation](/pages/product-variations) of a product. This allows the [inventory](/concept-guides/inventory) system to track stock levels for each specific variant, preventing overselling.
* **Business Application Example:**
* **Industry:** Footwear Retailer
* **Scenario:** A retailer defines "Size" and "Color" as Options for a sneaker. They can accurately display "Out of Stock" for a "Size 9 / Red" sneaker while still selling the "Size 10 / Blue" version, resulting in reliable fulfillment.
**Capability: Automated, Rules-Based Merchandizing**
* **Functional Explanation:** [Dynamic Categories](/pages/dynamic-categories) allow merchandisers to create product collections that manage themselves based on logical rules. This automates the creation of pages for brands, new arrivals, and sales, freeing up merchandisers for more strategic tasks.
* **Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A distributor's "What's New" page is a Dynamic Category that automatically includes any product added in the last 30 days. The page is always current with zero manual effort.
**Capability: Increased Average Order Value via Upselling**
* **Functional Explanation:** The "Extra" attribute type provides a native mechanism for offering add-on products and services directly on the product detail page, helping to increase the total value of the customer's cart.
* **Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** On a digital camera's product page, the retailer configures two "Extras": a 2-Year Extended Warranty and a discounted Camera Bag. The customer adds both, increasing the transaction value by 20%.
***
### **5. Platform Integration Map**
The complete catalog system is the heart of the commerce experience, with deep integrations across the platform.
* **Upstream Dependencies:**
* **Catalogs:** A Master Catalog must exist before any products can be created. Categories are managed within a specific Child Catalog.
* **Downstream Impacts:**
* **[Inventory](/concept-guides/inventory):** Product variations (generated by Options) are the fundamental basis for all inventory tracking.
* **Pricing & Discounts:** [Price Lists](/pages/price-lists) and Promotions are configured to target specific products or entire categories.
* **Search:** Product properties are a primary driver for the faceted search and filtering experience on the storefront.
* **[Order Management](/pages/orders-overview):** Every order is associated with a Site and contains specific product SKUs that are passed to the order system for fulfillment.
* **Content Management:** Website content, such as landing pages, is managed within a storefront Site and can feature specific products or categories.
* **Synergistic Features:**
* **SEO:** Product-level SEO fields work directly with the storefront rendering engine to create search-engine-optimized pages.
* **[Customer Segments](/pages/customer-segments):** Segments can be used to control which Price Lists apply to a user, and this logic is executed within the context of the Site they are visiting.
***
### **6. Real-World Example: International Launch of a New Product Line**
Let's walk through a complete end-to-end scenario of a company launching a new, configurable product line in a new international market.
* **The Business:** "Urban Office," a successful US-based DTC furniture brand, decides to launch its new, highly configurable "Flex" office chair in the German market.
* Step 1: Define the Product Blueprint (Master Catalog)
First, in their existing "Global Master Catalog," the catalog manager creates a new Product Type called "Office Seating." They define its attributes:
* **Options:** Frame Color (Black, White), Fabric Color (Gray, Navy). These will create unique SKUs.
* **Properties:** Weight Capacity (Text), Material (Text). These are for information and filtering.
* **Extras:** Extended 5-Year Warranty (a service).
* Step 2: Create the Master Product
Still in the Master Catalog, the manager creates the "Flex" product, assigns it the "Office Seating" Product Type, and fills in the universal, non-localized data: product code, weight, dimensions, and default English descriptions. The system generates the 4 unique SKUs based on the Options (e.g., FLEX-BLK-GRY, FLEX-WHT-NAVY). See [Product Variations](/pages/product-variations) for more on how variants are created.
* Step 3: Create the Localized Child Catalog
To manage the German launch, the team creates a new Child Catalog named "German Store Catalog." It inherits from the "Global Master Catalog." Inside this new catalog, they:
1. **Localize Content:** Select the "Flex" chair and override the Product Title and Long Description with professionally translated German text.
2. **Set Local Price:** Override the product's price, setting it in Euros.
* Step 4: Merchandise the Product in the New Catalog
Within the "German Store Catalog," the merchandizing team creates categories to help customers find the new chair:
1. **Static Category:** They manually assign the "Flex" chair to their existing Buromobel > Sitzmobel > Ergonomische Stuhle (Office Furniture > Seating > Ergonomic Chairs) category.
2. **Dynamic Category:** They create a new **Dynamic Precomputed Category** called "Neuheiten" (New Arrivals) with a rule to include all products added in the last 60 days. The "Flex" chair is automatically added.
* Step 5: Launch the German Site
Finally, the team creates a new Site called "Urban Office DE Storefront." During setup, they:
1. Link it to the "German Store Catalog."
2. Set the Country Code to DE and the Locale Code to de-DE.
3. Configure Site-specific settings like German payment gateways (e.g., Giropay) and local tax rules.
* The Outcome:
The new German website (urbanoffice.de) is launched. When customers visit, they see a fully localized experience. They find the "Flex" chair via the German navigation or the "New Arrivals" page. The product page displays German descriptions and prices in Euros. Customers can use dropdowns to select frame and fabric colors, and the correct variant SKU is added to their cart for accurate inventory and fulfillment, all managed from the same central Kibo Commerce instance as the original US store.
### **7. Related Conceptual Guides**
For foundational knowledge and upstream & downstream impact, refer to:
* [Pricing](/concept-guides/pricing)
* Foundational Knowledge: This Catalog guide is a prerequisite for Pricing. All products must first be defined in the Master Catalog before a Price List can be created to override their base price. Price Lists are created within the context of a Master Catalog.
* Downstream Impacts: The catalog structure directly controls pricing. Child Catalogs can have their own base prices, and Price Lists are layered on top of that structure to target specific customer segments or sites.
* Complementary Strategies: The Catalog defines what is for sale, while the Price List defines at what price and to whom it is sold. An "Exclusive" Price List can be used with a Child Catalog to create a highly curated and price-controlled portal for B2B customers.
* [Search and Merchandizing](/concept-guides/search-and-merchandizing)
* Foundational Knowledge: This Catalog guide is foundational for Search. The "Properties" you define on your products (e.g., Brand, Color, Material) are the raw data that the search engine indexes to create the faceted navigation (filters) shoppers use.
* Downstream Impacts: The quality and completeness of your product properties directly determine the effectiveness of your site's search and filtering capabilities. Well-structured categories also form the basis for shopper navigation.
* Complementary Strategies: The Catalog provides the raw materials (products and attributes), while Search and Merchandizing provide the tools to display them intelligently. A well-defined catalog enables a powerful merchandizing strategy, leading to better product discovery and higher conversion rates.
* [Promotions](/concept-guides/promotions)
* Foundational Knowledge: This Catalog guide is a prerequisite for Promotions. All products and categories must be defined in the catalog before a discount can be created to target them.
* Downstream Impacts: The way you organize products into Static and Dynamic Precomputed Categories directly impacts your ability to create efficient, targeted promotions. Discounts can be applied to an entire category at once.
* Complementary Strategies: The Child Catalog structure allows for localized promotions (e.g., a "Canadian-only" sale). Furthermore, Dynamic Realtime Categories (which can read discounted prices) work with promotions to automatically create a "Live Sale" page showing all items currently on promotion, with no manual effort.
# Kibo CMS Overview
Source: https://docs.kibocommerce.com/concept-guides/cms-overview
A headless content management system built into the Kibo Composable Commerce Platform, enabling content editors, merchandisers, and developers to manage pages, structured content, and digital assets across storefronts.
Kibo CMS is the content management layer of the Kibo Composable Commerce Platform. It provides a unified environment for creating and publishing structured content, building storefront pages, managing digital assets, and controlling user access — all within the same platform used to manage your catalog, orders, and fulfillment operations.
Content teams work in a visual interface with drag-and-drop page building, rich content modeling, and built-in publishing workflows. Developers access content programmatically through a GraphQL API. Both work within the same tenant-isolated, role-controlled environment that governs the rest of the Kibo platform.
## Key Capabilities
Define structured content types with custom fields, validations, and relationships. Content models describe the shape of your data — from editorial articles to product spotlights to promotional banners — and expose each model through a generated GraphQL API. Supported field types include text, rich text, numbers, booleans, date/time, file references, and references to other content entries.
A drag-and-drop visual editor for building and publishing storefront pages without writing code. Content editors compose pages from layout grids and reusable page elements, preview changes before publishing, and manage revisions across Draft, Published, and Unpublished states. Each publish event creates a new revision, preserving the previously published version until the new one is explicitly promoted.
Upload, search, organize, and tag digital assets including images and documents. The File Manager supports image width resizing via URL parameter and tagging for structured asset organization. Assets managed here are available for reference throughout the Website Builder and Headless CMS.
Access to Kibo CMS is managed through Kibo account roles. Users log in with their existing Kibo credentials, and their Kibo role determines their CMS access level — Full Access, Editor, or Viewer. No separate user provisioning is required within Kibo CMS.
Each company or brand on the Kibo platform operates within its own isolated CMS tenant. Tenant provisioning is managed through the platform, and each tenant maintains its own content models, pages, assets, users, and locale settings. This allows multiple brands or business units to operate independently on shared infrastructure.
Multi-language support is an upcoming capability. Locales will be configurable at the tenant level, and content entries will support locale-specific field values to enable teams to maintain separate content for each market.
Content entries and pages maintain a full revision history. Revisions are created on each publish event, making it safe to iterate on content while a stable published version remains live. Unpublishing reverts a page or entry to a non-public state without deleting it.
Every content model automatically generates a GraphQL API for headless content delivery. Storefronts and integrations query content entries directly via the Read API, the Manage API, or the Preview API, each scoped to the appropriate access level.
## Kibo Commerce Integration
Kibo CMS is designed to work alongside the rest of the Kibo Composable Commerce Platform. The integration connects CMS page-building workflows directly to live commerce data, and shares identity management with the broader platform.
### Product and Category Pages
The Kibo CMS Website Builder includes a Kibo Commerce integration that connects page creation to the live product catalog and category tree. When building storefront pages, editors can search for and associate pages with specific products or product categories from the Kibo Commerce catalog.
Two page types are available in the Website Builder's ecommerce integration:
* **Kibo Product Page** — Associates a page with a specific product, referenced by product code. The page preview renders at `/product/{productCode}`.
* **Kibo Category Page** — Associates a page with a product category, referenced by category code. The page preview renders at `/category/{categoryCode}`.
This allows content teams to build product detail page templates and category browsing pages that are linked to real catalog data, and to preview how those pages will render against specific products or categories before publishing.
### GraphQL API for Headless Content Delivery
All content modeled and published in Kibo CMS is accessible to storefronts and downstream systems through a GraphQL API. The API is automatically generated from your content models and supports three access modes:
* **Read API** — For fetching published content entries. Used by storefronts to render live content.
* **Manage API** — For reading and writing content entries programmatically. Requires elevated permissions.
* **Preview API** — For accessing unpublished draft content, enabling preview environments to render content before it goes live.
## Who Uses Kibo CMS
Kibo CMS serves several distinct audiences within a commerce organization:
**Content Editors** create and maintain content entries and build storefront pages using the Website Builder. They work within the permissions defined by their assigned role, typically scoped to specific content model groups or page categories.
**Merchandisers** use the Website Builder to build and publish category pages and promotional landing pages. The Kibo Commerce integration lets them associate pages directly with products and categories from the live catalog, making it possible to manage both the commerce data and the editorial experience from a single platform.
**Tenant Administrators** configure tenant-level settings within Kibo CMS. User access is managed through the Kibo platform — users log in with their existing Kibo credentials, and their CMS access level is determined by their Kibo role.
**Developers** define content models, build storefront integrations, and configure the GraphQL API. Developers typically create the initial content model structure that content editors then populate. They also implement the storefront rendering layer that queries the CMS Read API at build time or runtime to deliver content to end users.
## Getting Started
Key terms: content models, content entries, fields, and field types
Website Builder concepts: grid elements, page elements, revisions, and statuses
Define a content type with custom fields and validations
Add a record to an existing content model
Add images and documents to the File Manager
Folder structure and tagging for asset management
Understand how Kibo account roles control CMS access
# Delivery Fulfillment
Source: https://docs.kibocommerce.com/concept-guides/delivery-fulfillment
Enable routing and dispatch of shipments from retail locations or distribution centers to customers
# **Kibo Commerce Conceptual Guide: Delivery Fulfillment**
See how delivery fulfillment routes and dispatches shipments to customers
***
## **1. Strategic Overview**
**Concept Definition:** Delivery is an out-of-the-box fulfillment method in the Kibo Commerce platform that enables the routing, preparation, and dispatch of shipments directly from designated retail locations or distribution centers to the customer's specified shipping address.
**Business Context:** Delivery serves as a key component of a unified commerce strategy.1 Positioning alongside Buy Online Pickup In Store (BOPIS) and standard Ship to Home (STH), Delivery allows retailers to fully leverage their distributed inventory network, including physical stores, to execute customer delivery, optimizing fulfillment for factors such as speed, cost, and stock clearance across the entire commerce ecosystem.
**Value Drivers:**
1. **Enhanced Customer Choice and Reach:** Delivery expands fulfillment options beyond standard warehouse shipping, allowing physical retail locations to serve as micro-distribution centers. This capability utilizes existing infrastructure to increase the speed and convenience of order fulfillment for the end customer.
2. **Optimal Inventory Utilization and Markdown Reduction:** Through advanced Order Routing logic, Delivery assignments can strategically prioritize locations based on inventory attributes, such as age or low velocity. The goal is to maximize stock turnover, ensuring the retailer minimizes the capital required to hold aging stock and reduces the need for subsequent markdowns.
3. **Preservation of Customer Experience via Consolidation:** The Delivery process supports transfer-based consolidation, which proactively gathers fragmented inventory into a single shipment at a centralized location.3 This mechanism prevents the customer inconvenience associated with multiple packages from a single order, guaranteeing a unified delivery experience.
**Scope Statement:** This conceptual guide details the core configuration prerequisites for Delivery at the product and location levels, explains the operational steps of the Default and Consolidation fulfillment flows, outlines the system’s support for current, backordered, and future-dated shipments, and specifies the operational controls available via Order Routing Scenarios and package management capabilities. This guide maintains a strict focus on functional description, explicitly excluding deep technical API documentation, specific Business Process Manager (BPM) implementation steps, and quantitative performance assertions.
***
## **2. Core Concepts Explained**
### **What is Delivery Fulfillment?**
Delivery Fulfillment is a distinct fulfillment method within Kibo Commerce’s Order Management System (OMS). While it closely aligns with the traditional Ship-to-Home (STH) process during early stages such as picking and stock validation, it differentiates itself through enhanced preparation, dispatch, and delivery confirmation steps designed for distributed fulfillment networks. This model enables brick-and-mortar stores to serve as last-mile fulfillment hubs, supporting faster and more localized delivery operations.
Functional Definition and Role in the Platform Ecosystem:\
Delivery Fulfillment serves as the operational link between physical inventory locations and the customer’s delivery destination. It leverages Kibo’s advanced Order Routing framework to assign the optimal fulfillment location based on configurable business rules—such as proximity, inventory availability, or fulfillment efficiency. Throughout the shipment lifecycle—from order acceptance and picking to packing, dispatch, and final delivery confirmation—the process is centrally managed and tracked through the Fulfiller User Interface (UI), ensuring complete visibility and control across all delivery operations.
### **Why Delivery Matters**
The strategic adoption of Delivery fulfillment drives benefits across three key dimensions: operations, finance, and customer experience.
**Operational Efficiency:** Delivery requires explicit, granular control, mandating configuration at both the location level and the product level.1 This dual requirement ensures that only fulfillment locations operationally equipped with the necessary delivery infrastructure and trained staff are included in the routing pool, and that only products suitable for this fulfillment method are offered.1 This mechanism enforces strong operational discipline, minimizing the risk of fulfillment failures often associated with decentralized logistics and thereby streamlining internal processes and reducing exceptions.
**Financial Impact through Optimized Location Assignment:** The Delivery fulfillment method is a key enabler for dynamic financial strategies, leveraging the platform's distributed inventory visibility. Delivery specifically supports the execution of orders assigned to locations based on strategic goals, such as maximizing inventory turnover. By allowing Delivery orders to be routed to locations holding lower Life to Date (LTD) inventory values for the order items (a process supported by the Velocity sort strategy), the fulfillment process accelerates the movement of aging stock. This direct action through Delivery minimizes the capital tied up in slow-moving inventory and consequently reduces the need for markdowns, transforming the Delivery method from a logistical necessity into a direct financial optimization tool.
**Customer Experience through Speed and Consistency**:Delivery is specifically designed to optimize delivery speed by leveraging dynamic location assignment, where the fulfillment node geographically closest to the customer is prioritized via order routing logic. Important for delivery consistency is the optional feature of Delivery Consolidation. This mechanism addresses inventory fragmentation by using internal transfers to gather all required items into a single, centralized location before dispatching the complete order. This preemptive action ensures the customer receives a unified delivery, which significantly enhances reliability and reduces potential support inquiries related to split or partial shipments. While the location assignment must adhere to strategic trade-offs defined in the Order Routing configuration (e.g., balancing speed vs. inventory velocity), the Delivery process's primary goal remains customer-centric: enabling rapid fulfillment from a decentralized network
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
The Delivery fulfillment model is built upon the interaction of key architectural components that define eligibility, routing decisions, and operational execution:
1. **Catalog/Product Configuration:** This component dictates which products are eligible for purchase using the Delivery fulfillment method.
2. **Location Configuration:** This component governs which physical fulfillment nodes (e.g., stores, regional distribution centers) are operationally capable and authorized to perform Delivery fulfillment.
3. **Order Routing Logic:** This key layer determines the optimal assignment of the order to a location and manages the associated process flow logic, including Consolidation and Transfer management.
4. **Shipment workflow States:** This component tracks the specific progression of the order within the Fulfiller UI, providing staff with clear guidance through the necessary operational steps, including preparation, dispatch, and final confirmation.
### **Configuration-Level Deep Dive**
Configuration settings provide the granular control necessary to define the operational behavior, eligibility, and strategic prioritization of Delivery fulfillment. The following attributes and settings are vital for controlling the Delivery process:
Delivery Configuration Attributes and Business Impact
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| **Location Fulfillment Type: Delivery** | Authorizes a specific physical location to handle the unique logistics of delivery fulfillment.1 | **Impact:** Enables the location to be considered in the routing candidate pool. | A flagship retail store is checked for Delivery, allowing it to fulfill local online orders during peak season. |
| **Product>Shipping Section: Delivery** | Controls the storefront visibility and availability of the Delivery fulfillment option for individual products.1 | **Impact:** Makes the Delivery option selectable by the shopper for that item. | A standard t-shirt is *checked* for Delivery, while a large, fragile artwork piece is *unchecked* and restricted to freight. |
| **Order Routing: Sort Strategy (Distance)** | Defines the location selection priority based on geographical proximity to the customer's shipping address.1 | **Impact:** Optimizes customer delivery speed and often minimizes shipping costs. | The system assigns the order to the closest store location (25 miles away) |
| **Order Routing: Sort Strategy (Velocity)** | Prioritizes locations that hold lower Life to Date (LTD) inventory values for the order items.2 | **Impact:** Accelerates inventory turnover and directly reduces the likelihood of future markdowns. | A retailer uses this to ensure that all inventory acquired 12 months ago is shipped out before newer inventory is touched. |
| **Delivery Consolidation (Enabled/Disabled)** | Determines whether the system should utilize inventory **Transfers** when a Delivery location is partially out of stock.1 | **Impact:** Guarantees a single, complete shipment to the customer, minimizing complexity. | The setting is enabled globally to ensure high-value electronics orders are never split. |
| **Backorder Settings: Allow backordering** | Permits a product to be sold on the storefront even when the inventory count is zero or negative.6 | **Impact:** Captures sales revenue that would otherwise be lost during out-of-stock periods. | A luxury goods brand allows backorders for limited edition items expected to restock in 90 days. |
## **4. Key Capabilities and Business Applications**
### **Capability 1: The Delivery Default Fulfillment Flow (Current Inventory)**
**Functional Explanation:** The Delivery Default Flow provides the standard process for orders fulfilled using current, available inventory. After assignment and acceptance, the process follows standardized steps: **Print Pick Sheet** 1, **Validate Items in Stock**, and **Print Packing Slip**.1 The unique Delivery steps begin with **Prepare for Delivery**, where mandatory actions occur, including completing any required **Assembly** (Fulfillment Service Items) 1, entering final package details (dimensions and weight), and printing delivery labels. The fulfillment associate then initiates **Dispatch** by clicking **Handover to Delivery Provider**. The final step is **Delivery Confirmation**, where the fulfiller manually clicks **Order Was Delivered** (or confirmation is received automatically), marking the shipment Complete.
Business Application Example:\
Industry: Enterprise Electronics Retailer\
Scenario: An electronics retailer receives an order for a smart home device requiring initial software setup and battery installation (a fulfillment service item) before shipping. The order is routed to a specialized fulfillment lab location.\
The lab team proceeds through the default flow. During the Prepare for Delivery step, the fulfillment technician executes the required assembly and setup service. They confirm the final package specifications, generate the delivery label, and click Ready for Dispatch. After carrier collection, upon notification of delivery, the system (or staff) confirms the completion. This process ensures specialized services are integrated into the standard timeline, resulting in fewer customer support calls regarding complex initial setup and a verified final delivery status.
### **Capability 2: Delivery Consolidation Flow (Utilizing Transfers)**
**Functional Explanation:** When Delivery Consolidation is enabled and the selected fulfillment location does not have the complete inventory, the system initiates an internal transfer to source the missing items from another location. During this process, the Shipment is temporarily placed on hold until all required items arrive at the destination. Once the transfer is completed, the order is released for packing and shipped to the customer as a single, consolidated delivery.
Business Application Example:\
Industry: B2B Industrial Distributor\
Scenario: A manufacturing client places an urgent order for five high-pressure valves and ten specialized gaskets, routed to a regional distribution center. The center only has the valves.\
Because Delivery Consolidation is configured for B2B orders, Kibo initiates a transfer request for the ten missing gaskets from the central depot. The client's order immediately moves to the Waiting for Transfer status. This action ensures that the customer receives the full order in a single package. This guarantees compliance with the B2B client’s strict, single-delivery receiving protocols and simplifies their inbound receiving process, resulting in streamlined receiving and fewer delivery discrepancies for the client.
### **Capability 3: Management of Future Delivery Shipments**
**Functional Explanation:**\
Delivery shipments can be planned and scheduled for fulfillment based on future inventory availability and confirmed delivery timelines. This capability leverages *Future Inventory allocation logic* to allocate items against projected incoming stock, ensuring that shipments can be prepared and delivered once inventory becomes available within the defined Future Date Limit. For a shipment to transition into a *Future* status, Future Inventory must be enabled at both the product and site levels. Once validated, a new shipment is created with a *Future* status, representing a confirmed and planned delivery commitment to the customer.
Business Application Example:\
Industry: Marketplace Operator\
Scenario\*\*:\*\* A marketplace vendor offers made-to-order furniture with an estimated delivery window based on manufacturing lead time. When a customer places an order, the system checks projected inventory availability and confirms that materials and components will be available within 45 days. The system then creates a *Future Delivery Shipment* linked to the planned completion and dispatch date. This functionality enables the marketplace to manage forward delivery promises efficiently—providing customers with clear, reliable delivery expectations while maintaining visibility and control over future fulfillment activities.
### **Capability 4: Package Consolidation of Multiple Delivery Shipments**
**Functional Explanation:** Package Consolidation is an optional feature available to Delivery shipments that allows fulfillment staff to group up to **10 qualifying shipments** into shared physical packages.4 Shipments qualify for consolidation if they are in the **Ready** state, assigned to the **same fulfillment location**, destined for the **same B2C customer or B2B account**, and utilize the **same shipping address and fulfillment type**.4 During the **Prepare for Delivery** step, the fulfiller must manually toggle the Consolidate Packages across Shipments option. This enables them to associate the contents and packing slips of multiple distinct shipments with shared packages, resulting in a single set of tracking numbers for the combined packages.
Business Application Example:\
Industry: Fashion & Apparel Retailer (Omnichannel)\
Scenario: A customer places a late-night order for shoes and then, an hour later, places a separate order for accessories, both routed for Delivery from the same nearby retail store.\
When the fulfillment associate processes the first order, the system displays Package Consolidations Available. The associate selects the second order for grouping. After picking both orders, during the Prepare for Delivery step, they pack all items into one shipping container and utilize the consolidation toggle. This process generates only one shipping label for the combined box, reducing the overall carrier fees incurred by the retailer and guaranteeing the customer receives both purchases simultaneously, which reduces logistics cost and improves customer convenience.
### **Capability 5: Dynamic Location Selection via Distance Routing**
**Functional Explanation:** Delivery fulfillment utilizes the sophisticated Order Routing framework, which allows configuration of Scenarios to prioritize candidate locations using the **Distance** Sort Strategy.1 This process involves the system selecting the location that is geographically closest to the shopper's specified address. This routing process can also power the storefront experience by displaying the optimal fulfillment location based on the shopper’s address or zip code.
Business Application Example:\
Industry: Direct-to-Consumer (DTC) Brand\
Scenario: A high-growth DTC brand focuses intensely on rapid delivery times to new customers to build loyalty. An order is placed from a metropolitan area near three potential fulfillment points.\
The brand’s Order Routing Strategy utilizes Distance as the primary sorting metric for all Delivery shipments. Based on the customer's exact geo-location, the order is automatically assigned to the brand's local micro-fulfillment center (MFC) located 5 miles away, rather than the main distribution center 150 miles away that uses slower transit times. This strategy ensures the fastest possible delivery times for key customer acquisition orders, directly supporting loyalty initiatives and mitigating early subscription churn risk.
### **Capability 6: Exclusion and Mitigation during Stock Validation**
**Functional Explanation:** The **Validate Items in Stock** step is a mandatory audit point in the Delivery flow\.1 If the fulfillment location identifies that not all items are available and Delivery Consolidation is *not* enabled, the system presents mandatory actions.1 The fulfiller must choose to either **Split the shipment** (if partial inventory is available) or **Reassign** the entire shipment to a new location with full inventory.1 Additionally, the Fulfiller UI offers the ability to temporarily **Block Location Assignments** during the validation process. This capability prevents the location from receiving further assignments for products that have been identified as short, ensuring efficient inventory allocation across the network.
Business Application Example:\
Industry: Enterprise Electronics Retailer\
Scenario: A regional store is assigned a Delivery order for two specialized gaming keyboards. Upon picking, the associate finds they are critically short on one keyboard model due to an unlogged internal sale.\
Since consolidation is not configured for these high-turnover items, the associate must choose to either split the shipment (delivering one keyboard now and one later) or reassign the full order. They choose to reassign the full order to the central warehouse to maintain the customer's expectation of a single delivery. Concurrently, they utilize the Blocking Location Assignments option to temporarily pull the store out of the routing pool for this specific keyboard model, preventing further assignment failures until the next inventory shipment arrives.
### **Capability 7: Preparation and Assembly of Fulfillment Service Items**
**Functional Explanation:** The **Prepare for Delivery** state is the designated operational stage within the Delivery process where value-added services, formally defined as Fulfillment Service Items (such as specialized finishing or assembly), must be executed.1 This sequencing guarantees that the product is fully prepared, correctly assembled, packed, and accurately labeled according to the customer's request and all carrier requirements (package dimensions and weight entry are integral to this step) prior to the handover for dispatch.
Business Application Example:\
Industry: B2B Industrial Distributor\
Scenario: A B2B client orders customized equipment that includes a specific finishing treatment service (a Fulfillment Service Item) requiring specialized equipment only available at a dedicated service center.\
The order is routed and accepted by the service center. Once all components are picked, the shipment enters the Prepare for Delivery step. The fulfillment team performs the custom finishing treatment. Upon completion, they update the final package specifications, including the new weight and dimensions post-treatment, and print the required specialized freight label. This capability ensures that the service fulfillment is tightly integrated into the delivery timeline, guaranteeing quality control and accurate shipment manifesting before carrier handover.
## **5. Platform Integration Map**
The effectiveness of Delivery fulfillment is highly dependent on its seamless integration with core platform systems, acting as a data consumer for prerequisites and a data producer for process outcomes.
### **Upstream Dependencies**
| Required Configuration/Data | Rationale |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Location Configuration:** | Fulfillment locations must have the Delivery fulfillment type explicitly enabled.1 |
| **Product Configuration:** | Products must have the Delivery option checked in the catalog to be eligible for purchase.1 |
| **Shipping Methods and Rates:** | Carrier methods must be defined, and corresponding rates should be automatically retrieved during checkout. |
| **Order Routing Logic:** | Scenarios must be configured to define assignment parameters and failover actions, prioritizing metrics such as Distance or Velocity.1 |
| **Transfer BPM (Optional)** | A specific Business Process Manager workflow can be configured at the location group level to customize the internal process steps for transfer shipments.3 |
### **Downstream Impacts**
| Enabled Capability/System | Process Change |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shipment State Progression:** | Tracks the order through nine distinct states, from Acceptance through to the final Complete status.1 |
| **Inventory Allocation:** | Confirmed orders trigger stock reservation and allocation, ensuring real-time inventory counts are maintained across the network.1 |
| **Fulfiller UI Display:** | Provides a dedicated dashboard card for the Delivery fulfillment type, listing the precise number of shipments stalled or progressing in each state.1 |
| **Delivery Label Generation:** | Package details entered during preparation are used to generate compliant carrier labels during the Prepare for Delivery stage.1 |
###
### **Synergistic Features**
1. **Delivery Consolidation via Transfers:** Prevents shipment fragmentation by enabling the internal transfer of missing inventory, guaranteeing single package delivery.
2. **Package Consolidation:** Allows staff to physically group multiple, fully qualified shipments destined for the same customer into shared packages, optimizing logistics spend.
3. **Pick Waves:** Enables the inclusion of Delivery shipments in high-efficiency, multi-order picking batches, significantly improving labor output and speed.
4. **Fulfillment Service Items (Assembly):** Integrates the execution of value-added services as a mandatory step within the fulfillment process (Prepare for Delivery).
5. **Suggest Candidates API / Extensions:** Enables dynamic calculation and suggestion of the optimal fulfillment location on the storefront based on the shopper's address.
6. **BPM Customization:** Allows configuring a specific Business Process Manager workflow at the location group level to customize the internal process steps for Delivery shipments.
## **6. Related Conceptual Guides**
For foundational knowledge, refer to:
* **[Fulfillment](/concept-guides/fulfillment):** Provides the necessary background to understand the core differences and similarities between Delivery, Ship to Home (STH), and Buy Online Pickup In Store (BOPIS), establishing the context for the Delivery type within the broader OMS architecture.
To understand downstream impacts, refer to:
* **[Ship to Home (STH)](/concept-guides/sth):** Details the initial fulfillment steps (picking, stock validation) that are shared with the Delivery process. Consulting this guide helps users recognize where the Delivery process introduces specialized, final-mile steps (Prepare, Dispatch, Confirmation).
For complementary strategies, refer to:
* **[STH and Delivery Consolidation](/pages/sth-and-delivery-consolidation):** Offers detailed instructions and background on the configuration and management of the transfer-based consolidation logic. This guide explains how the system manages the Waiting for Transfer state to ensure the goal of a single, unified customer shipment is achieved.
* **[Order Routing](/concept-guides/order-routing):** Provides in-depth guidance on configuring scenarios, filters, and assignment logic. This is vital for strategically determining how Delivery orders are assigned based on key metrics such as Distance, Velocity, and inventory availability, enabling fine-tuned operational strategy.
* **[Package Consolidation](/pages/package-consolidation):** Explains the functional capability to group multiple distinct shipments for the same customer into shared physical packages. This supports efficiency strategies aimed at reducing carrier costs when a customer has generated multiple open Delivery orders.
# Fulfillment
Source: https://docs.kibocommerce.com/concept-guides/fulfillment
Manage the complete process of getting ordered items from inventory to customers
# **Kibo Commerce Conceptual Guide: Fulfillment**
See the Shipments API documentation for programmatic access
See the Shipment Packages API documentation
See the Location Admin API documentation for programmatic access
See the Location Group API documentation
See how configurable shipment release controls when shipments are created during fulfillment
## **1. Strategic Overview**
### **Concept Definition**
Fulfillment is the essential process in Kibo Commerce that manages everything required to get an ordered item from inventory to the customer, whether through shipping from a warehouse or pickup at a physical location, ensuring timely delivery or collection.
### **Business Context**
The Kibo Commerce platform uses Fulfillment as the operational backbone for unified commerce, executing complex omnichannel strategies (Ship to Home (STH), Buy Online Pickup In Store (BOPIS), Delivery) by bridging order capture and physical execution.
### **Value Drivers**
1. **Workflow Agility:** Configurable Business Process Management (BPM) flows allow rapid alignment of digital workflow states with complex, real-world operational procedures, supporting custom state transitions without reliance on external implementation schedules.
2. **Performance Transparency:** A centralized, real-time dashboard visualizes operational health against Service Level Agreements (SLAs), driving proactive management and immediate intervention in locations exhibiting at-risk performance.
3. **Inventory Network Integrity:** Fulfillers can temporarily or permanently exclude their location from automatic assignments for problematic products, preventing fulfillment failure loops and preserving Order Routing efficiency.
### **Scope Statement**
This guide details the structure of the **shipment details**, the centralized Fulfiller UI dashboard architecture (Map and List Views), the general framework of BPM flows and customization, and specific operational capabilities for managing shipment exceptions (Rejection, Splitting, Transfer, Substitution, Cancellation, and Location Blocking). It excludes specific implementation details for individual fulfillment methods or API endpoints.
## **2. Core Concepts Explained**
### **2.1 What is Fulfillment?**
Fulfillment serves as the execution layer that bridges the order capture phase with the physical delivery of goods.2 Functionally, it is a sequence of managed steps, encompassing internal logistics like verifying inventory, accurate item selection (picking), secure packaging, appropriate carrier assignment (shipping), and post-delivery support, particularly reverse logistics (returns).
The platform’s fulfillment solution is integrated into the OMS core, acting as the execution mechanism for orders generated. The system must be capable of managing a diverse set of requirements based on the business model. For B2C businesses, the focus is typically on speed and convenience, meeting consumer expectations for fast delivery and seamless returns. Conversely, B2B fulfillment often involves handling larger, more complex orders, specialized packaging, compliance with industry standards, and maintaining long-term reliability over rapid speed.2 This need for flexibility is accommodated by the platform’s customizable fulfillment processes.
### **2.2 Why Does Fulfillment Matter?**
Fulfillment capabilities offer major business advantages by boosting operational efficiency, securing financial transactions, and ensuring customers have a positive experience.
| Benefit Category | Description |
| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Operational Efficiency** | The centralization of management, combined with tools like Pick Waves, allows staff to consolidate picking across different types of shipments (STH, BOPIS, Delivery). This reduces the time spent collecting items and accelerates preparation across the network.2 |
| **Financial Optimization** | Fulfillment is important for margin management. Cost optimization achieved through sophisticated consolidation and minimized split shipments directly protect profitability against unforeseen operational changes. Furthermore, the system enforces financial security by blocking shipments from entering the fulfillment workflow if the associated order has unpaid or completely errored payments, ensuring operational resources are only applied to secured transactions. |
| **Customer Experience Enhancement** | The ability to execute flexible strategies, such as providing estimated delivery dates (EDD) enhanced by real-time location capacity 2, or offering partial fulfillment via split shipments, allows businesses to meet, and often exceed, modern customer expectations regarding speed and transparency.7 |
## **3. Functional Components & Configuration Deep Dive**
### **3.1 Component Architecture Hierarchy**
The Fulfillment subsystem is an integrated flow:
1. **Order Routing:** This upstream component decides the optimal fulfillment location by evaluating factors like inventory availability, proximity, cost, and adherence to defined strategies.
2. **BPM Engine (Business Process Management):** This engine defines the specific, sequential state transitions (workflow) that a shipment must pass through based on its determined Fulfillment Type.
3. **Shipment Details:** The core digital record that carries the item details, assigned location, current status, and custom metadata.
4. **Fulfiller UI:** The operational execution interface used by fulfillers to process shipments and by managers to monitor network health.
### **3.2 Business Process Management (BPM) Framework**
BPM flows dictate the required chronological steps for a shipment to transition from its initial assignment to its completed state.
**Workflow Structure and Customization**
The platform provides out-of-the-box (OOTB) BPM flows for standard fulfillment types (such as Ship to Home , Buy Online Pickup In Store and Delivery). These default workflows contain specific, fulfillment-related steps that all shipments must transition through to be considered Completed.
**Customization Framework:** While default flows are provided, Kibo supports advanced customization. Businesses can create custom Business Process Management flows by developing their own fork of Kibo's fulfillment workflows repository. This modern framework eliminates the need to rely on the Kibo development team for custom BPM creation, allowing greater speed and autonomy. Once a customized BPM is created, it is uploaded and installed through the Kibo Dev Center, enabled via API, and subsequently executed through the Kibo Fulfiller UI, aligning technical workflows with unique operational needs.
### **3.3 Configuration-Level Deep Dive**
The platform provides granular control over key business decisions through configurable attributes related to financial integrity, omnichannel flexibility, and transfer management.
Table 3.1: Shipment Configuration Attributes Deep Dive (Key Attributes)
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable Inventory Transfers for Store Pickup9 | Enables the core logic that allows inventory to be transferred from a sourcing location to a customer pickup location if stock is insufficient at the destination. | **Impact:** Significantly increases the likelihood of successfully fulfilling BOPIS orders, maximizing sales conversion. but Introduces transfer shipping costs and transit time, potentially delaying customer pickup beyond initial expectations.12 | A Fashion & Apparel Retailer enables this system-wide to ensure a seasonal item, though out of stock at the local mall store, can be transferred from the regional distribution center within 48 hours for customer pickup. |
| Always Create Transfer Shipments for BOPIS Orders | Forces the automated creation of a transfer shipment, regardless of whether inventory is currently confirmed as available at the potential transfer-enabled sourcing locations. | **Impact:** Accelerates the reservation of expected incoming inventory and speeds up the initial transfer attempt. but Increases the risk of subsequent cancellation or failed transfer if the inventory does not materialize, potentially leading to customer dissatisfaction.12 | An Enterprise Electronics Retailer uses this during the launch of a highly anticipated new product to secure stock immediately, trusting the inventory forecast despite momentary depletion. |
| Auto-Cancel Linked Transfer Shipments | Configures cascaded cancellation logic, determining whether a cancellation on the parent BOPIS shipment or item should automatically trigger the cancellation of the related transfer shipment or item. | **Impact:** Maintains inventory accuracy and releases transferred stock back to the general pool immediately if the customer cancels the parent BOPIS order. | A Marketplace Operator managing store fulfillment ensures that if a customer cancels a BOPIS order, the associated internal transfer shipment carrying the items is instantly canceled, making that stock available for a new order. |
| Remorse period | Configurable delay (1 to 7200 minutes) between order submission and final creation of the shipment.8 | **Impact:** Provides time for fraud checks or manual order edits, balancing risk mitigation against initial fulfillment velocity.8 | Setting a 15-minute delay allows automated fraud screening before the fulfillment workflow starts. |
| Allow Partial Fulfillment | Permits partial shipment of an order when not all items are immediately available. | **Impact:** Accelerates delivery of available items and improves customer satisfaction. | A beauty retailer uses this to ship in-stock products immediately while waiting for Transfer items to arrive |
| Enable ShiptoHome/ Delivery Consolidation | Groups multiple items or orders for a single customer into one delivery shipment when stock is split across locations. | **Impact:** Reduces shipping costs and enhances customer experience with a single consolidated delivery. | A home goods retailer enables this to consolidate items from different stores into one delivery to reduce logistics costs. |
## **4. Key Capabilities and Business Applications**
### **Capability: Real-Time Operational Visibility via Fulfiller UI Dashboard**
**Functional Explanation:** The Fulfiller UI dashboard provides real-time operational management using Fulfillment SLA thresholds (Compliant, At Risk, Non Compliant).4 **Map View** displays a geographical representation of locations, showing current shipment counts and color-coded threshold status upon selection.4 **List View** provides a detailed, filterable shipment grid indicating each shipment's current SLA threshold status.
**Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** A manager needs to assess which DCs are struggling with high-value smartphone orders against a 3-hour SLA.
* **Action:** The manager navigates to the **Map View**, filters by the relevant SLA, and the map highlights two DCs in **Red (Non Compliant)**, indicating failure to meet the processing deadline.4 This visualization enables immediate intervention.
* **Outcome:** Rapid, data-driven resource reallocation is enabled, resulting in the successful and timely completion of high-priority shipments and minimizing negative customer experiences associated with operational delays.
### **Capability: Dynamic Inventory Shortage Resolution (Split Shipment)**
**Functional Explanation:** If only partial inventory is available during the *Validate Items in Stock* step, the fulfiller can **split the shipment**. The available portion is processed, and the remaining unavailable quantity is automatically placed into a new child shipment for re-routing. During the split, the fulfiller gains the ability to choose to **temporarily block further automatic assignments** of the unavailable product(s) to their location until inventory is refreshed.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor (Complex pricing, bulk ordering)
* **Scenario:** A distribution center receives an order for 500 units but finds only 380 are accessible due to temporary maintenance.
* **Action:** The fulfiller validates the 380 available units, initiates a **Split Shipment**, and checks the **Exclude location from future assignments checkbox** for the solvent product, knowing the shortage is systemic.
* **Outcome:** The client receives the majority of their order immediately. The remaining units are successfully routed to an alternative fulfillment center, demonstrating maximum inventory utilization, while the exclusion ensures the constrained DC is not assigned similar tasks until maintenance is complete.
### **Capability: System-Controlled Location Assignment Exclusion (Manage Blocked Locations)**
**Functional Explanation:** The platform provides fine-grained control over Order Routing eligibility. A location can be temporarily blocked (until inventory refresh) or persistently blocked (via the **Keep location excluded** toggle, even after inventory refresh) from receiving automatic assignments for specific problematic products, with all excluded locations centralized on the **Manage Blocked Locations** page.
**Business Application Example:**
* **Industry:** Direct-to-Consumer (DTC) Brand (Subscription models, customer acquisition focus)
* **Scenario:** A micro-fulfillment center repeatedly fails to process large product bundles due to space constraints, an issue that will not be immediately resolved.
* **Action:** The operations lead uses the **Keep location excluded** toggle during a shipment split for the large bundle product.5 The lead then verifies the center is strategically blocked for all future assignments containing the large bundles on the **Manage Blocked Locations** page.
* **Outcome:** The persistent block ensures Order Routing immediately bypasses the operationally constrained location for problematic, high-volume SKUs, guaranteeing higher initial fulfillment success rates and preventing the accumulation of failed shipments.
### **Capability: Product Substitutions**
* **Functional Explanation:** If the Substitutions feature is configured, it allows fulfillers to replace an ordered product with a similar, eligible substitute product during the fulfillment process when the original item is unavailable.16 This action is performed specifically at the *Validate Stock* step in the Fulfiller UI. The system displays eligible substitutes along with their available inventory at the fulfillment location.16 The process requires the fulfiller to enter a specific **reason for the substitution**. The platform also supports **Pre-Fulfillment Substitutions**, where Admin users (such as customer service representatives) can select a substitute and replace the original item on Pending orders or shipments in the *Accept Shipment* state, using advance knowledge of stock availability.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A manufacturing client places a bulk order for 50 specialized chemical filters. During the *Validate Stock* step, the warehouse fulfiller identifies that only 40 units are available due to a recent quality control hold. An eligible equivalent substitute filter with 100 units in stock is displayed. The fulfiller performs a manual substitution for the remaining 10 units, recording the original item shortage as the *Reason for Substitution*.
* **Action:** The fulfiller replaces the unavailable quantity with the approved substitute product, ensuring the full order quantity is fulfilled in one shipment without delay.
* **Outcome:** The distributor fulfills 100% of the customer’s required volume, avoids a backorder scenario, secures full order revenue, and maintains business continuity and customer trust through proactive substitution management.
### **Capability: Inter-Location Transfer and Reassignment**
**Functional Explanation**: Shipments can be transferred or reassigned between different fulfillment locations within the network. This capability is used to acquire items that are locally unavailable at the assigned fulfillment location from a separate transfer location. The core goal of this functionality is to move the missing inventory to the final fulfillment location so that the original shipment can be fulfilled completely and shipped as a single unit. The system logs the details, including the identity of the location that initiated the action, in the shipment's Internal Notes. For the location designated to receive the transferred goods, the Fulfiller UI provides a dedicated function, Receive Transfers, accessible via the navigation menu, allowing fulfillers to formally accept inbound shipments from another fulfiller location.
**Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** A small retail branch receives a BOPIS order for a specialized monitor, but upon checking, the inventory is missing. The customer is relying on the single pickup.
* **Action:** The branch manager initiates a Transfer of the missing monitor from a nearby warehouse that has verified stock. The system moves the shipment into a Wait for Transfer state. Once the item physically arrives at the branch, the staff uses the Receive Transfers page to formally accept it. With the inventory now consolidated, the original BOPIS shipment is fulfilled completely for the customer to pick up as a single transaction.
* **Outcome:** By utilizing the transfer capability to consolidate the unavailable item to the original fulfillment location, the business avoids splitting the order or forcing the customer to travel to a second location, resulting in a single, timely fulfillment event and a seamless customer experience
### **Capability: Package Consolidation**
**Functional Explanation:** Package consolidation provides the ability for fulfillers to group multiple separate shipments—which may originate from different customer orders—into fewer physical packages during the preparation and picking process. This feature is available for Ship-to-Home, Delivery, and Transfer shipments. Shipments must adhere to strict qualification criteria to be consolidated: they must be in the *Ready* state, assigned to the *same fulfillment location*, use the *same fulfillment type*, and be destined for the *same B2C customer or B2B account* at the *same shipping address* using the *same shipping method*. The Fulfiller UI assists by suggesting qualifying shipments, allowing the user to select up to 10 shipments for consolidation. A single tracking number is generated and shared across all consolidated items within that package.
**Business Application Example:**
* **Industry:** Direct-to-Consumer (DTC) Brand (Subscription Models)
* **Scenario:** A customer places a spontaneous add-on order for a new product, followed 30 minutes later by the automated fulfillment run for their scheduled monthly subscription box. Both generate ready *Ship-to-Home* shipments assigned to the same regional distribution center and destined for the same customer via expedited shipping.
* **Action:** When the fulfiller initiates the first shipment, the *Fulfiller UI* alerts that the second shipment qualifies for consolidation. The fulfiller consolidates both shipments, grouping and picking them together under a single package and tracking number.
* **Outcome:** The brand achieves meaningful shipping cost savings by merging two packages into one and enhances the customer experience by ensuring both orders arrive together—delivering operational efficiency and improved delivery satisfaction.
### **Capability: Pick wave**
**Functional Explanation:** The Pick wave capability replaces standard sequential order line picking with optimized zone or wave picking, ensuring efficient execution within the fulfillment location. This sophisticated toolset is designed to group and prioritize shipments into waves based on predefined operational constraints and business logic. Shipments are grouped and optimized utilizing factors such as urgency and priority defined by **Service Level Agreements (SLAs)**, **Carriers**, **Shipment Methods , Customer Segments** etc to coordinate the picking schedule. This ensures that the picking process maximizes efficiency and meets customer expectations for delivery speed.
**Business Application Example:**
* **Industry:** Fashion & Apparel Retailer
* **Scenario:** A large, high-volume apparel retailer operating under a *Ship-from-Store* model must efficiently manage hundreds of daily online orders across multiple store locations. Each morning, the system leverages the *Pick Wave* capability to coordinate and optimize picking activities. Rather than generating a simple sequential order list, the system intelligently groups all ready shipments based on their *Shipment Methods*—for instance, consolidating all premium next-day delivery orders into a *Priority Wave* and organizing the pick route by inventory zones within the store.
* **Action:** Store fulfillers initiate the *Priority Wave*, enabling focused picking of high-value, time-sensitive shipments using zone-based guidance that minimizes travel time and increases throughput.
* **Outcome:** The retailer consistently meets stringent delivery SLAs by processing urgent shipments first, reducing the likelihood of late deliveries or penalty costs, and achieving greater operational efficiency across its distributed fulfillment network.
**5. Platform Integration Map**
### **5.1 Upstream Dependencies**
* **Payment Object States:** Fulfillment is blocked if order payments are **unpaid or completely errored**.
* **Order Routing Strategies:** Shipment assignment relies on active routing strategies defined upstream, including **Sort Strategy** (e.g., distance, quantity), **Assignment Preference** (single/multiple), and **Scenarios** (groups of eligible locations).
* **Configurable Shipment Release:** The time delay for shipment creation (Create Shipments \_ Minutes After Order Submit) requires the Enable Configurable Shipment Release toggle to be active.
### **5.2 Downstream Impacts**
* **External System Integration via SLA Events:** The system can send **event notifications when shipments are missing SLA targets**, allowing external systems (WMS, custom dashboards) to trigger automated recovery workflows.
* **Shipment Update Transmission (Marketplaces):** Updates made in Kibo (carrier details, tracking numbers) are relayed to integrated applications like ChannelAdvisor, which transmits this detail to associated marketplaces and the customer.
* **Fulfiller Returns Process:** The Fulfilled status is typically a prerequisite state for initiating a Fulfiller Return, managing reverse logistics and refunds.
### **5.3 Synergistic Features**
Table 5.1: Fulfillment Synergistic Features (Key Synergies)
| Synergistic Feature | Fulfillment Functionality Leveraged | Combined Value Proposition |
| :------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fulfillment SLAs** | Utilizes the **shipment's** status and BPM flow steps to track processing time against defined, time-based performance thresholds.4 | Provides measurable performance standards with real-time alerts (Compliant/At Risk/Non Compliant), improving network accountability.2 |
| Estimated Delivery Date (EDD) Calculation 10 | Leverages fulfillment capacity data and location-specific performance metrics (e.g., Average Hours to Fulfill) to provide dynamic, accurate delivery windows to the shopper. | Improves customer confidence during the checkout phase, which is a key driver for conversion, and drastically reduces post-purchase inquiries regarding delivery status by providing proactive transparency. |
##
## **6. Related Conceptual Guides**
### **For foundational knowledge, refer to:**
* **Concept Guides for [Ship to Home](/concept-guides/sth), [BOPIS](/concept-guides/bopis) and [Delivery](/concept-guides/delivery-fulfillment):** Essential for understanding the structural categories (STH, BOPIS, Delivery) that define the required BPM state transitions executed by the fulfillment system.
* **[Inventory](/concept-guides/inventory):** This guide explains how item quantities are handled ensuring proper stock levels, on-hand counts, and product availability.
* **[Order Routing](/concept-guides/order-routing):** This guide outlines how Delivery orders are integrated into the broader order management and routing workflows, ensuring shipments are efficiently routed and processed.
### **To understand downstream impacts, refer to:**
* **[Returns and Reverse Logistics](/concept-guides/returns-and-reverse-logistics):** Details the integrated process for managing inventory restocking, financial refunds, and appeasements that occur subsequent to the fulfillment of a shipment.
### **For complementary strategies, refer to:**
* **[Fulfillment SLAs](/concept-guides/fulfillment-slas):** Describes the necessary framework for defining and measuring time-based fulfillment performance, which is integrated into the Fulfiller UI dashboard.
# Fulfillment SLAs
Source: https://docs.kibocommerce.com/concept-guides/fulfillment-slas
Measure and enforce time constraints for fulfillment processes to ensure reliable operational performance
# **Kibo Commerce Platform Conceptual Guide: Fulfillment SLAs**
Learn how to define and manage fulfillment service level agreements (SLAs)
## **1. Strategic Overview**
**Concept Definition**
Shipment Fulfillment Service Level Agreements (SLAs) are system-defined constraints that measure and enforce the maximum allowable time duration for specified internal fulfillment processes at the **shipment level**, ensuring reliable operational performance and customer promise delivery.
**Business Context**
The Kibo Commerce platform employs Fulfillment SLAs to integrate customer expectations directly into the operational mechanics of the Order Management System (OMS). By establishing objective time boundaries on the internal processes of picking, packing, dispatch etc.., the platform provides retailers and distributors with the essential mechanism to transform centralized commitments into reliable, location-specific execution.1 This structured approach is essential for enabling seamless omnichannel experiences and superior execution velocity across a distributed fulfillment network.
**Value Drivers**
1. **Operational Consistency and Standardization:** SLAs impose a standardized, measurable performance expectation across all fulfillment locations. This standardization ensures labor at any facility performs fulfillment tasks efficiently and consistently, regardless of the order type or the specific location profile.
2. **Proactive Risk Mitigation:** Utilizing defined compliance thresholds (Compliant, At-Risk, Non-Compliant), the system shifts operational monitoring from reactive failure reporting to proactive intervention. The generation of necessary event signals facilitates automated responses designed to avert potential service failures before they negatively impact the customer experience.
3. **Reliable Customer Experience:** SLAs establish a direct and measurable link between the consumer promise and the internal process execution. This enforcement mechanism reduces the variability inherent in distributed fulfillment networks, thereby solidifying brand trust and ensuring predictable service delivery.
**Scope Statement**
This conceptual guide details the functional configuration, application hierarchy, real-time monitoring, and enterprise integration capabilities of Kibo Commerce Fulfillment SLAs. It focuses exclusively on defining and enforcing **shipment-level** time constraints and measuring performance based on fulfillment progress. Explicitly excluded from this guide are implementation details related to API usage, front-end theme adjustments, specific Business Process Modeling (BPM) code structures, or any quantitative assertions regarding potential performance improvements.
***
## **2. Core Concepts: The Role of SLAs in Omnichannel Fulfillment**
### **What are Shipment Fulfillment SLAs?**
Shipment Fulfillment SLAs function as time constraints defined between two specific points within a fulfillment workflow, designated as the Start Point and the End Point. These constraints are fundamentally applied at the level of the individual shipment, not the order.1 This means that if a single order is split into multiple shipments—perhaps because items originate from different locations or utilize distinct fulfillment methods—each shipment may be governed by different SLAs simultaneously. The SLA acts as a key, measurable control layer that overlays the internal Fulfillment Workflow defined by the business.1 Businesses define the maximum total time duration and unit (minutes, hours, or days) 1 necessary to honor the external commitment made to the customer.
### **Why Fulfillment SLAs Matter**
**Operational Benefits**
SLAs are instrumental in achieving sophisticated operational Coordination. They provide the necessary context to allow fulfillment systems to prioritize picking schedules dynamically based on time sensitivity, available labor, and operating hours. By integrating time constraints directly into the workflow, SLAs establish objective, data-driven prioritization mechanisms essential for complex strategies like wave or zone picking, reducing reliance on manual decision-making.
**Financial Benefits**
By rigorously measuring and seeking to minimize the internal segment of the Order Cycle Time—the period from order receipt to dispatch or readiness for pickup —SLAs directly contribute to more efficient capital utilization. The structure provided by SLAs offers the necessary framework to proactively mitigate expensive failure modes, such as expedited shipping fees and extensive manual customer service interventions, by identifying potential non-compliance early.
**Customer Experience Benefits**
The key benefit of utilizing SLAs is establishing Reliability. When a retailer commits to a specific service timeframe—such as guaranteeing same-day delivery preparation—the SLA enforces the requisite operational discipline to meet that promise consistently. This operational consistency is vital for high-value or time-sensitive goods and is the foundation for maintaining high customer satisfaction and fostering long-term repeat business.
The key benefit of utilizing SLAs is establishing Reliability. When a retailer commits to a specific service timeframe—such as guaranteeing same-day delivery preparation—the SLA enforces the requisite operational discipline to meet that promise consistently. This operational consistency is vital for high-value or time-sensitive goods and is the foundation for maintaining high customer satisfaction and fostering long-term repeat business.
## **3. Functional Components & Configuration Deep Dive**
### **3.1. SLA Component Architecture**
Fulfillment SLA management is structured around a three-tiered hierarchy that ensures centralized governance while allowing for local operational flexibility.
1. **SLA Entity Definition:** This is the core time constraint (including Name, Time Duration, and Fulfillment Type) defined centrally. This definition sets the *maximum time permitted* for the measured process segment.
2. **Assignment Mechanism:** Assignment controls *where* the SLA applies, occurring at the Location Group level for standardization and scalability, and optionally at the individual Location level for exceptions or overrides.
3. **Shipment Workflow Integration:** The SLA timer is tethered to defined Start and End points within the shipment's operational workflow. These points are specifically based on a selected tracking mechanism: Shipment Status, Workflow Task, or Workflow State.
### **Configuration-Level Deep Dive: SLA Creation Attributes**
To define a new Fulfillment SLA, administrators configure the core attributes 1:
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | Identifies the specific commitment being measured for organizational clarity and reporting ease. | Important for filtering and accurate reporting in the Fulfiller UI dashboard and external monitoring systems. | Naming an SLA BOPIS\_2HOUR\_Promise clearly identifies its purpose for fulfillment staff and reporting users. |
| **Code** | Provides an optional, unique, machine-readable identifier for efficient system integration and lookup processes. | Facilitates reliable API interaction and integration with external systems that require short, unique identifiers. | Using a code like CP\_RUSH allows external systems to reliably reference the constraint for curbside rush orders. |
| **Description** | Provides necessary context regarding the SLA’s specific purpose, scope, and target process segment. | Improves internal documentation and reduces ambiguity across different operations, management, and training teams. | Including the text "Measures total time from order acceptance to customer notification of ready for pickup" clarifies the SLA scope. |
| **Fulfillment Type** | Determines the specific fulfillment channels to which the SLA constraint will apply (Pickup, Ship to Home, Transfer, Delivery, Curbside, or Curbside Pickup or for All Fulfillment Types).1 | Ensures appropriate measurement; E.g an SLA designed for customer pickup should not apply to an internal Transfer process. | Selecting the Transfer type ensures the SLA only measures the time for inventory movement between two internal locations. |
| **Time Duration** | The numeric value representing the maximum allowable time for the process segment being measured. | Directly dictates the stringency of the operational performance requirement and the internal deadline calculation. | Setting the duration to 12 hours establishes a hard deadline for the fulfillment process. |
| **Unit of Measurement** | Defines the time unit corresponding to the duration value (minutes, hours, or days).1 | Required for the accurate calculation of the deadline and the associated compliance threshold triggers. | Selecting 'minutes' as the unit provides highly granular measurement essential for rapid fulfillment processes. |
### **3.2. Threshold Management and Compliance Statuses**
Compliance status is calculated dynamically based on the percentage of the total allowed Time Duration that has elapsed. Kibo Commerce utilizes three color-coded thresholds to provide real-time status updates and facilitate proactive alerts.
Fulfillment SLA Threshold Definitions
| Status | Visual Indicator (Fulfiller UI) | Conceptual Definition based on Elapsed Time | Operational Implication |
| :---------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Compliant** | Green | The elapsed time is well within the acceptable performance window, falling significantly below the maximum duration.1 | The fulfillment process is on schedule and requires no intervention. |
| **At Risk** | Yellow | The elapsed time has crossed a defined internal threshold, indicating potential jeopardy to the deadline.1 | Requires immediate operational prioritization; triggers the shipment.slacomplianceatrisk event for proactive intervention.1 |
| **Non-Compliant** | Red | The elapsed time has exceeded 100% of the defined maximum duration.1 | The customer commitment has been formally missed; triggers the shipment.slacompliancenoncompliant event for required escalation and service recovery actions.1 |
The At Risk threshold provides the most strategic value, as it generates a predictive alert via Eventing that enables the business to execute mitigation steps before the shipment officially misses the deadline.
### **3.3. Shipment Tracking Mechanisms**
Fulfillment SLAs derive their accuracy by measuring the duration between a specified **Start** and **End** point within the shipment’s life cycle. The selection of the tracking mechanism determines the operational granularity of the measurement 1:
| Tracking Mechanism | Functional Scope | Measurement Precision |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
| **Shipment Status** | Measures time between high-level, overarching fulfillment stages (e.g., from 'Accepted' to 'Shipped').1 | Low Precision |
| **Shipment Workflow Task** | Measures time spent specifically on discrete labor actions defined within the BPM workflow (e.g., 'Picking Complete', 'Packing Started').1 | High Precision |
| **Shipment Workflow State** | Measures time between defined transition points within the BPM (e.g., moving from the 'Initial' state to the 'Ready for Pickup' state).1 | Medium Precision |
### **3.4. Assignment Hierarchy: Location Groups and Individual Locations**
Fulfillment SLAs are assigned using a hierarchy to balance standardization and localized flexibility.
1. **Assignment to Location Groups:** SLAs are applied to groups of similar locations (e.g., all high-volume distribution centers) via the Location **Config Settings** tab.1 This ensures that all similar nodes operate under the same standardized time commitment. The **Target SLA Percentage** for an assigned SLA can be individually adjusted at this level, providing a uniform performance expectation across locations.
2. **Assignment to Individual Locations:** Administrators can assign specific SLAs to individual locations or override the group’s default settings.1 Notably, the **Target SLA Percentage** for an assigned SLA can be individually adjusted at this level.1 This operational agility accounts for constraints such as temporary staffing fluctuations or facility size limitations without changing the core customer promise.
## **4. Key Capabilities and Business Applications**
### **Capability: Real-Time Monitoring and Performance Visibility in the Fulfiller UI**
**Functional Explanation:** The Fulfiller UI dashboard features a sophisticated real-time map visualization that displays fulfillment locations accompanied by their current SLA performance status.1 The map can be filtered by specific location(s), lookback period, shipment type, and specific SLA. Clicking on a location displays a pop-up containing a graph that visualizes the percentage breakdown of shipments currently residing in the Compliant (Green), At Risk (Yellow), and Non-Compliant (Red) thresholds.1 This capability is central to operational management by providing visual, dynamic performance data.
Business Application Example:\
Industry: Marketplace Operator (Multi-vendor management, compliance)\
Scenario: A major marketplace must monitor and enforce the contractual fulfillment SLAs of numerous small, third-party vendors who utilize the Kibo OMS.\
A dedicated compliance analyst uses the Fulfiller UI dashboard, applying a filter to display the Ship-to-Home SLA defined in all vendor contracts. The analyst visually compares the performance graphs across different vendor warehouse locations displayed on the map.1 The analyst immediately identifies a vendor whose location exhibits a disproportionately high percentage of shipments in the Non-Compliant threshold. This real-time, comparative visibility allows the analyst to initiate targeted vendor coaching immediately, resulting in consistent fulfillment quality across the entire marketplace network.
### **Capability: Defining Granular Commitments based on Fulfillment Channel**
**Functional Explanation:** This capability allows the business to leverage the **Fulfillment Type** attribute to segment measurement based on the specific operational flow. Since the system supports types including Pickup, Ship to Home, Transfer and Delivery an organization can create unique, non-overlapping SLAs. This ensures that the appropriate internal time limit is applied to each channel, preventing the metrics of high-speed customer channels (like BOPIS) from being conflated with those of internal logistics (like Transfers).
Business Application Example:\
Industry: Fashion & Apparel Retailer (Omnichannel, seasonal)\
Scenario: During peak season, a fashion retailer must ensure an extremely fast path for customer-facing Bopis Pickup orders (mandating a 30-minute completion time) while simultaneously managing slower, inter-facility Transfers necessary for inventory stock balancing (which may require 72 hours).\
A business user defines a central SLA\_BOPIS\_30MIN applied only to the Bopis Pickup fulfillment type, tracking the duration between two specific Shipment Workflow States. They also define a separate SLA\_TRANSFER\_72HR applied exclusively to the Transfer fulfillment type. This functional separation ensures that the performance of time-critical, customer-facing channels is monitored with precision, providing clear performance reporting without distortion from internal logistics, resulting in reliable customer commitments across all channels.
### **Capability: Proactive Risk Mitigation through Automated Event Generation**
**Functional Explanation:** When a shipment’s compliance status changes to **At Risk** or **Non-Compliant**, Kibo’s Eventing service automatically generates corresponding event payloads (shipment.slacomplianceatrisk or shipment.slacompliancenoncompliant).1 These data payloads can be configured to be consumed by virtually any external application subscribed to the relevant webhook topic, thereby establishing robust, automated, enterprise-wide monitoring and structured escalation procedures.
Business Application Example:\
Industry: Direct-to-Consumer (DTC) Brand (Subscription models, customer acquisition focus)\
Scenario: A DTC brand relies on exceptionally fast initial fulfillment of subscription boxes, requiring immediate service recovery if a delay occurs. They need to integrate all SLA failures immediately into their Customer Relationship Management (CRM) system.\
The technical team subscribes the CRM system's API endpoint to the shipment.slacompliancenoncompliant event.1 When a Red status is triggered, the event payload automatically updates the specific customer record in the CRM, flagging the order delay. This orchestration enables the automated generation of a proactive customer service email offering a small service credit before the customer even inquires, resulting in swift, controlled service recovery and improved customer retention.
### **Capability: Measuring Time Constraints on Granular Labor Steps**
**Functional Explanation:** By utilizing the **Shipment Workflow Task** tracking option 1, the SLA can measure the exact duration spent on specific, discrete labor actions defined within the fulfillment workflow. This high-precision capability allows for detailed performance analysis that transcends high-level status changes, ensuring accountability and efficiency at the most granular operational level.
Business Application Example:\
Industry: B2B Industrial Distributor (Complex pricing, client accounts, bulk ordering)\
Scenario: An industrial distributor needs to optimize the specific labor step of ‘Item Verification’ within their complex distribution center (DC) workflow, as mis-picks of specialized parts are expensive. They define a maximum time of 15 minutes for this task.\
The operations team creates an SLA that uses Shipment Workflow Task as the tracking option, setting the Start Point when the ‘Item Verification’ task is assigned and the End Point when the task is marked ‘Complete’. By monitoring this specific SLA in the Fulfiller UI 1, managers can rapidly identify which DC locations or even which teams are exceeding the 15-minute verification limit. This granular focus allows for targeted process redesign and labor training, resulting in fewer assembly errors and a demonstrable increase in overall order accuracy.
## **5. Platform Integration Map**
Fulfillment SLAs function as consumers of prerequisite upstream configurations and as essential triggers for key downstream actions.
### **Upstream Dependencies**
| Required Configuration/Data | Rationale |
| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Location Setup and Grouping** 1 | SLAs must be assigned at the location or location group level; accurate location definition and strategic grouping are necessary prerequisites for efficient, scalable SLA deployment. |
| **Fulfillment Workflows (BPM)** 1 | SLAs must define precise Start and End points based on Shipment Status, Task, or State; the underlying workflows must be thoroughly modeled to provide these measurable tracking points. |
### **Downstream Impacts**
| Enabled Capability/System | Process Change |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fulfiller UI Prioritization** 2 | The color-coded statuses (Green, Yellow, Red) provide clear visual cues for fulfillment staff, allowing them to prioritize workload dynamically based on urgency rather than simple receipt order. |
| **Real-Time Event Notifications via Eventing** 1 | The system triggers automated alerts and updates to external enterprise systems when compliance thresholds are violated, enabling enterprise connectivity. |
### **Synergistic Features**
1. **Location Groups:** These are fundamental for achieving efficient, standardized application of SLAs across similar fulfillment nodes, significantly reducing the administrative burden that would result from configuring individual SLAs for hundreds of separate locations.
2. **Fulfillment Workflows (BPM):** The BPM defines the operational checkpoints (Tasks and States) that the SLA timer precisely measures. Without granular BPM definitions, SLA tracking is limited to broad, high-level status changes, diminishing its strategic value.
3. **Eventing Service:** This service acts as the mechanism required to translate internal operational metrics (SLA status changes) into consumable, cross-enterprise data flows. The ability to subscribe to the proactive shipment.slacomplianceatrisk and reactive shipment.slacompliancenoncompliant events is essential for enabling automated response and achieving comprehensive management visibility.
## **6. Related Conceptual Guides**
**For foundational knowledge, users should refer to:**
[Location Admin](/developer-guides/location-admin) and [Location Group](/developer-guides/location-group): These guides are a prerequisite because effective, scalable SLA deployment is contingent upon the strategic organization and accurate configuration of fulfillment centers and the subsequent definition of Location Groups, which streamline the process of SLA assignment and control.
**To understand downstream impacts, users should refer to:**
[Event Subscriptions](/pages/event-subscription): This developer guide explains the technical mechanisms for receiving and reliably processing event payloads. Understanding Eventing is important for leveraging the generated slacomplianceatrisk and slacompliancenoncompliant events in systems external to the core OMS.
**For complementary strategies, users should refer to:**
[Fulfillment](/concept-guides/fulfillment): This guide details the creation and sequencing of Shipment Workflow States and Tasks. These workflow elements must be defined correctly, as they serve as the mandatory Start and End points for highly granular SLA tracking, ensuring the measurement aligns precisely with the labor process being executed.
# Concept Guides Overview
Source: https://docs.kibocommerce.com/concept-guides/index
Comprehensive guides to understanding Kibo Commerce platform capabilities and features
# Concept Guides
Welcome to the Kibo Commerce Concept Guides. These guides provide in-depth explanations of the platform's core capabilities, helping you understand how different features work together to power your unified commerce experience.
## Core Commerce Capabilities
Hierarchical catalog architecture for managing products, sites, and categories
Aggregating shopper selections and finalizing transactions with flexible payment options
Real-time tracking of product quantities and availability across all locations
Intelligent decision logic for optimal fulfillment location selection
Secure transaction processing across all sales channels
Dynamic price lists for B2C tiers, B2B contracts, and product entitlements
## Fulfillment Methods
Traditional direct-to-consumer shipping from any fulfillment location
Omnichannel fulfillment allowing customers to collect orders at physical locations
Local delivery options from stores and distribution centers
End-to-end process management for getting products to customers
## Operational Excellence
Service level agreements to ensure reliable operational performance
Complete return process from initiation to resolution
## Growth & Engagement
Flexible campaigns and discounts to drive conversion and loyalty
Product discovery and strategic presentation tools
Automated recurring purchases for predictable revenue
## Platform Intelligence
In-platform assistant that completes tasks across Kibo Admin in plain language
## How to Use These Guides
Each concept guide follows a consistent structure designed to help you quickly understand and apply the concepts:
1. **Strategic Overview** - High-level definition, business context, and value drivers
2. **Core Concepts** - Detailed explanations of what the feature is and why it matters
3. **Functional Components** - Architecture and configuration options
4. **Key Capabilities** - Specific features with real-world business applications
5. **Platform Integration** - Dependencies and relationships with other features
6. **Related Documents** - Links to complementary guides
## Getting Started
If you're new to Kibo Commerce, we recommend starting with these foundational guides:
1. [Catalog & Products](/concept-guides/catalog) - How catalogs, sites, and products are organized
2. [Inventory Management](/concept-guides/inventory) - Understanding how inventory flows through the platform
3. [Pricing](/concept-guides/pricing) - Dynamic pricing strategies for B2C and B2B
4. [Cart & Checkout](/concept-guides/cart-and-checkout) - The core purchase flow
5. [Order Routing](/concept-guides/order-routing) - How orders are intelligently distributed
6. [Fulfillment](/concept-guides/fulfillment) - Converting orders into delivered products
## Need Help?
These concept guides explain the "what" and "why" of platform features. For technical implementation details, API specifications, and step-by-step configuration instructions, please refer to the technical documentation sections.
# Inventory Overview
Source: https://docs.kibocommerce.com/concept-guides/inventory
Track quantity, location, and availability status of products across your unified commerce platform
## **1. Strategic Overview**
See the Inventory API documentation for programmatic access
See the Reservation API documentation for programmatic access
Get an introduction to inventory management in Kibo
**Concept Definition:** Inventory is the functional core that tracks the quantity, location, and availability status of every product unit to fulfill customer demand across all channels.
**Business Context:** The Inventory Management System within the Kibo Commerce platform is positioned as the single, authoritative **Source of Truth** for all product stock. Its purpose is to synchronize inventory across the enterprise—from warehouses and distribution centers to physical store locations and third-party vendor sites—to power accurate order promising and omnichannel fulfillment strategies.
**Value Drivers:**
* **Optimized Order Fulfillment:** Provides a holistic view of stock across the entire network, enabling intelligent order routing to the most cost-effective and fastest fulfillment location, which shortens delivery times and reduces shipping costs.
* **Maximized Sell-Through & Revenue:** Ensures that every available unit is visible and sellable on the storefront, minimizing lost sales from stock-outs or inaccurate inventory display and maximizing the revenue potential of existing stock.
* **Enhanced Customer Trust and Experience:** Guarantees that product availability is accurately promised at the time of purchase (Available to Promise), drastically reducing the rate of order cancellations due to inventory errors, thereby building long-term customer confidence.
**Scope Statement:** This guide covers the conceptual framework, core definitions, functional components, and business applications of the Inventory module, including quantity types, future inventory, segmentation, and granular tracking. It **explicitly excludes** specific API endpoints, code-level implementation details, or instructions on using the Inventory Import/Export tools.
***
## **2. Core Concepts Explained**
### **What is Inventory?**
Inventory within the Kibo Commerce platform is a dynamic record, primarily maintained at the **UPC (Universal Product Code) and Location** level. It is the real-time record of all product units, categorizing them into various quantity types to support a range of business processes, including sales, allocation, and fulfillment. Its role in the platform ecosystem is to act as the central point of truth, constantly communicating product availability to the storefront (via the Real-Time Inventory Service) and to the Order Management System (OMS) for fulfillment decisions.
### **Why does Inventory matter?**
Inventory is foundational because it directly links sales and fulfillment, dictating what a business can promise and deliver to its customer.
* **Operational Benefits:** It enables complex omnichannel fulfillment methods like **Buy Online, Pick Up In-Store (BOPIS)** or **Ship-from-Store**, by knowing the precise quantity and location of every item. This operational flexibility allows a retailer to utilize all of its assets (store stock) for e-commerce fulfillment, improving inventory turnover.
* **Financial Benefits:** Proper inventory management prevents both overselling (leading to expensive cancellations, customer churn) and underselling (missing revenue opportunities by holding back available stock). It ensures capital is not unnecessarily tied up in inventory that is not being actively sold.
* **Customer Experience Benefits:** Providing accurate, real-time availability on the storefront prevents customer frustration that arises from ordering a product only to be informed later that it is out of stock. This transparency creates a seamless and trustworthy shopping experience.
### **Core Definitions and Calculations**
The Kibo Commerce platform tracks inventory using a set of key, interdependent quantity types:
| Quantity Type | Definition | Calculation/Logic | Importance |
| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------- |
| **On Hand** | The total physical count of product units physically present at a specific location, regardless of their current sales status (allocated or unallocated). | *Source of truth based on physical counts/updates.* | The base unit quantity; used to track physical stock levels. |
| **Allocated** | The quantity of product units that have been allocated for a confirmed order | *Quantity allocated to confirmed shipments/orders.* | Represents committed stock that is no longer available for new orders. |
| **Available** | The quantity of product units that are immediately available and sellable to a new customer (Available to Sell). | Available = On Hand - Allocated | The key metric for storefront visibility and immediate order promising. |
| **Safety Stock** | A buffer quantity of units that is deliberately withheld from the **Available** quantity to mitigate the risk of stock-outs caused by unexpected demand spikes or fulfillment delays. | Safety Stock is a configurable setting applied against the Available quantity. | Protects against overselling by creating an intentional cushion. |
| **Pending Items** | The quantity that was overallocated and is waiting for inventory. This occurs anytime there is an allocation greater than the Available amount of inventory. Pending items will be "released" and automatically converted to Allocated when stock is available. | Any quantity that is Pending for an item is applied against Available quantity. | Used to handle overallocation. Pending items get created only on an exception basis. |
| **Available to Promise (ATP)** | The total sellable inventory, including currently available stock and any confirmed incoming inventory (Future Inventory) within a defined time frame. | ATP = Available (Current )+ Future Inventory | The most comprehensive metric for promising an item with an immediate or future delivery date. |
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
The Inventory functionality is built upon an interconnected set of core records and services:
1. **Inventory Record (UPC-Location Level):** The base unit of inventory tracking.
* **Core Components:** For a UPC, Location Code: On Hand, Allocated, Available, Safety Stock, Future Inventory.
* **Sub-Components (Optional)**
* **Granular Inventory Fields:** SKU, Lot Code, Date, Serial Number, Condition
2. **Location:** Defines the physical entity where inventory is held (Warehouse, DC, Store).
* **Configuration:** Location Supports Inventory (Boolean), Location Type. 3. **Future Inventory:** Incoming Inventory
* **Site:** Future Inventory Enabled (Boolean) with Future Date Limit for allocation.
* **Product:** Future Inventory Enabled (Boolean) 4. **Inventory Segmentation:** Custom, user-defined labels (tags) applied to Inventory Records.
* **Configuration:** Segment Type, Allocation Percentage/Quantity Rules. 5. **Real-Time Inventory Service (RIS):** A dedicated, highly performant service that processes and delivers availability data to the storefront.
***
### **Configuration-Level Deep Dive**
Inventory configuration controls how stock is tracked, protected, and offered to the customer.
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Location-Level Inventory Enabled Flag** | Toggles the active tracking of inventory for all products at a specific physical location (e.g., a specific store or warehouse). | Enabling inventory allows the location to be selected for order fulfillment and stock-level updates. Disabling it means the location's stock is excluded from the total sellable pool. | A **Direct-to-Consumer (DTC) Brand** marks a temporary pop-up fulfillment center as **Enabled** only for the 4th quarter holiday rush. |
| **Future Inventory Enabled (Site)** | Controls whether the platform considers incoming stock that has a confirmed delivery date as part of the total **Available to Promise (ATP)** quantity. | Enabling allows allocation against incoming stock, maximizing pre-sales potential. | An **Enterprise Electronics Retailer** enables this to take pre-orders on a highly anticipated new gadget 4 weeks before it arrives at the DC. |
| **Future Date Limit(Site)** | Sets the maximum look-ahead period (set as Days/Weeks/Months) for which incoming **Future Inventory** is considered sellable and calculated into the ATP | A longer look-ahead maximizes long-term sales but increases the risk of delivery delays causing customer experience issues. A shorter window is safer but limits pre-sale capability. | A **Fashion & Apparel Retailer** sets a 6-week limit to only allocate against new seasonal collections arriving in the near term. |
| **Safety Stock Value (Per UPC-Location)** | Defines the quantity buffer that is not included in Available quantity. | A higher value significantly reduces the risk of overselling but artificially decreases the sellable inventory, potentially leading to missed sales opportunities. | A **B2B Industrial Distributor** sets a Safety Stock of 10 units for an essential maintenance part to ensure immediate fulfillment of emergency client orders. |
***
## **4. Key Capabilities and Business Applications**
The platform's Inventory management capabilities support granular control and real-time visibility across complex retail networks.
### **Capability: Real-Time Availability for Storefront Experience (RIS)**
**Functional Explanation:** The **Real-Time Inventory Service (RIS)** is a high-performance, dedicated service that provides immediate, accurate inventory visibility to the storefront. RIS is engineered to support the heavy traffic and low latency requirements of Product Listing Pages (PLP) and Product Detail Pages (PDP) by maintaining a single, unified source of inventory availability across the entire fulfillment network. It enables the storefront to display:
* Real-time in-stock/out-of-stock status on **PLPs (Product Listing Pages)** and **PDPs (Product Detail Pages)**.
* Accurate and near real-time quantities, and potential urgency messaging (e.g., "Only 3 Left!"), on the **PDP (Product Detail Page)**.
* Store-specific availability for BOPIS/Ship-from-Store options.
Inventory levels can be requested as the total aggregate quantity across all locations or filtered to a specific location (or group of locations).
**Business Application Example:**
* **Industry:** **Fashion & Apparel Retailer**
* **Scenario:** A customer is browsing the *New Arrivals* category page (PLP) on their mobile device. Without RIS, the page would rely on less-frequent inventory updates, risking showing an item as "In Stock" when it has already sold out. By leveraging RIS, the retailer ensures that only items with confirmed **Available** quantity are displayed as purchasable. When the customer clicks through to a specific jacket's PDP, they immediately see the accurate stock count (e.g., "Only 5 left in Size Medium"). This transparency drives an informed purchase decision, resulting in fewer customer support calls about canceled orders and a higher rate of completed purchases due to guaranteed stock.
### **Capability: Future Inventory Allocation**
**Functional Explanation:** This capability allows the platform to accept orders and allocate stock against product units that are not yet physically On Hand but have a confirmed inbound delivery date. This stock is designated as **Future Inventory**. When a customer's order utilizes Future Inventory, the system will prioritize **Current Available** inventory first. Once current stock is exhausted, the system begins allocating against the earliest dated future inventory records. This mechanism enables pre-selling and maximizes the **Available to Promise (ATP)** quantity.
**Business Application Example:**
* **Industry:** **Enterprise Electronics Retailer**
* **Scenario:** A major new gaming console is being released, and the retailer knows they have 5,000 units arriving at their main distribution center in 6 weeks. By enabling Future Inventory and importing the inbound stock record with the future date, they can immediately begin taking pre-orders online. When a customer checks out, the system allocates from the ATP (which includes the 5,000 future units) and assigns a future shipment date, creating a highly anticipated and guaranteed order for the customer. This business practice allows the retailer to capture 5,000 sales and realize the revenue weeks before the product physically arrives, resulting in a maximized product launch sales volume and better cash flow management.
### **Capability: Inventory Segmentation**
**Functional Explanation:** Inventory Segmentation allows for the logical partitioning of physical stock (Inventory Records) at a location using custom tags. This partitioning enables a business to ring-fence or prioritize specific portions of their Available inventory for particular channels, customer groups, or fulfillment types. Allocation rules can be defined by a **Percentage** of the total Available quantity or a **Discrete Unit Quantity** to be reserved for a segment. Inventory is allocated from the requisite segment.. If that segment's quantity is depleted, the remaining quantity will be handled by after actions (cancelled/backorder/customer care)
**Business Application Example:**
* **Industry:** **Marketplace Operator**
* **Scenario:** A marketplace offers products from third-party vendors (Shipped-by-Vendor) as well as its own inventory (Shipped-by-Marketplace). To ensure a fast-moving special promotion for VIP customers is not jeopardized by high demand from general sales, the operator creates an **Inventory Segment** called "VIP-Allocation" and reserves 20% of the inventory for a select high-demand product. This rule ensures that even if general sales deplete the primary inventory pool, VIP customers will still be able to successfully purchase the product, resulting in improved loyalty and retention for their most profitable customer segment.
### **Capability: Granular Inventory Tracking and Allocation**
**Functional Explanation:** While inventory is fundamentally tracked by UPC and Location, **Granular Inventory** allows for deeper differentiation of individual units within that grouping. The configurable Granular Fields include: **SKU, Lot Code**, **Date**, **Serial Number**, and **Condition**.
* **SKU:** This field differentiates inventory for each individual SKU. A UPC may be associated with multiple SKUs. Aggregate amounts across SKUs roll up to the UPC.
* **Lot Code:** A batch number used to identify a group of items produced together.
* **Date:** Used as Expiry Date. The date after which an item should not be sold).
* **Serial Number:** A unique identifier for a single product unit (e.g., for high-value electronics).
* **Condition:** The quality status of the item (e.g., *New*, *Refurbished*, *Damaged*).
Allocation logic can be configured to use these granular fields. For example, allocation can be set to prioritize items with the earliest **Expiry Date** first (First-Expired, First-Out or FEFO) to minimize spoilage/loss, or to only allocate stock with a specific **Condition** (e.g., only "New" items for direct-to-consumer sales).
**Business Application Example:**
* **Industry:** **B2B Industrial Distributor**
* **Scenario:** A distributor of chemical components tracks stock with short shelf lives. To minimize loss from expired inventory, they configure their allocation rules to prioritize the **earliest Expiry Date** first.. A large client places an order for 50 units. The system checks the inventory records and automatically allocates the 50 units from **Lot Code A** because its expiration date is 30 days sooner than **Lot Code B**, ensuring the oldest, highest-risk stock is sold first. This business practice dramatically reduces losses from inventory write-downs due to expiration.
### **Capability: Inventory Quantity Retrieval**
The platform's Inventory APIs and services support two primary methods for retrieving inventory quantity, which provides flexibility for various storefront and business applications.
### **Retrieval by UPC at a Location**
This method provides the most granular view of current inventory: the On Hand, Allocated, Available, and other quantities for a **single UPC at a specific Location**.
**Business Application Example:**
* **Industry:** **Fashion & Apparel Retailer**
* **Scenario:** A customer on the PDP clicks the "Check In-Store Availability" option. The storefront makes a request for the quantity of *Product SKU 1234, Size Medium* specifically at *Store Location 'NYC-Flagship'*. The system returns the inventory record for that exact UPC-Location combination, showing **3 Available** units. This enables the customer to confidently choose BOPIS (Buy Online, Pick Up In-Store) at that single location.
### **Retrieval as Aggregate: UPC Across All Locations**
This method provides a consolidated view, summing the Available(or ATP quantity for a **single UPC across all eligible Locations** in the retail network.
**Business Application Example:**
* **Industry:** **DTC Brand**
* **Scenario:** A customer is viewing the **Product Detail Page (PDP)** for a new item. The retailer wants to display the total availability to encourage the sale, regardless of which location will fulfill it. The storefront makes an aggregate request for *Product SKU 5678* across all active distribution centers. The system returns a single value of **2,500 Available** units. This total aggregate quantity is displayed as the primary stock indicator, maximizing confidence in the product's general availability.
***
## **5. Working with Inventory in the Admin UI**
**Note:** The Inventory UI has been updated with a new look and feel and new functional changes, and has been renamed to **Supply/Demand UI**. Contact [Kibo Support](https://help.kibocommerce.com/) to opt in and begin using it. All sandbox tenants will receive the new UI on July 21. Select the tab below based on which UI your tenant is currently using..
You can manage product inventory in Admin, which allows you to associate products with inventory and track quantities for your products. The products' storefront behavior can then be selected based on whether inventory exists for each individual product while the available quantities at different locations are considered when routing orders for fulfillment.
Inventory can be used with either Kibo eCommerce, Order Management-only, or a full solution implementation of the Kibo Composable Commerce Platform.
### **Inventory UI**
This section provides a general overview of the Inventory UI. See the [Configure Inventory](/pages/configure-inventory "Configure Inventory") guide for more details about creating and updating inventory levels, as well as the [inventory segmentation](/pages/inventory-segmentation-overview "Inventory Segmentation Overview"), [granular inventory fields](/pages/granular-inventory-fields "Granular Inventory Fields"), or [future inventory](/pages/future-inventory "Future Inventory") guides for information about additional inventory tracking features.
### **Search Inventory**
1. Go to **Main** > **Orders** > **Inventory**.
2. You must select a location or enter a product name/code before inventory is displayed. Either enter a value or select a location in the appropriate field in the table.
* You must have a catalog enabled in order to use Product Name, then select the appropriate master and child catalogs from the drop-down menus on the left. Matching results will appear once you begin typing. You can either click a product from these results or click **Enter**.
3. Expand the menu in the top right corner of the table to hide and unhide columns as desired depending on what type of inventory levels you want to see.
4. The Product Code (which maps to the `upc` in [the Inventory API](/api-overviews/openapi_inventory_overview)), Part Number, SKU, Location Code, and Location Name columns can all be searched on. If only a single product is selected without a specific location, then the aggregate inventory levels will be displayed.
* Entering a base product code that has variations will trigger a popup that allows you to select which variants you want displayed in the results. You can view these as either a list of their variant codes or as drop-down options. Upon confirming your selections, those results will populate the inventory table.
If inventory is out of stock (in other words, if the available inventory is 0) at a particular location, then its table row will be highlighted red. If available inventory is less than the safety stock but is not yet 0, then it will be highlighted yellow to warn that it will be going out of stock soon.
Go to **Main > Orders > Inventory**. The new UI expands into four left-nav sub-links:
| Sub-link | What it does |
| :--------------------- | :------------------------------------------------------------- |
| **Inventory** | Search, results grid, record management, Supply & Demand Modal |
| **Future Inventory** | Dedicated page — table view, calendar view, CRUD |
| **Shipments** | Full shipment search and detail view |
| **Settings** | Inventory Tags and Condition Availability configuration |
| **Safety Stock Rules** | Allows to set safety Stock Rules |
**Search**
Search does not trigger on page load. Supported fields:
* **Master Catalog / Child Catalog Dropdown** — catalog-enabled tenants only
* **Product Name** — typeahead (3+ characters), Variants product Support, multi-select; catalog-enabled only
* **Product Attributes** — AND across attributes, OR within an attribute; catalog-enabled only
* **Product Code/Variant Code** — single or multi-value chip input comma separated
* **Location** — single or multi-select; accepts location name or code
* **Inventory Attribute** — AND across attributes, OR within an attribute
By Location selection allows you to select 20 locations .This is configurable via a tenant attribute if clients needs more than 20 as a selection limit they can contact [Kibo Support](https://help.kibocommerce.com/) to increase the selection limit.
Click **Advanced Filter** for: SKU, Part Number, Future Date Range, Use Condition availability (checkbox, for granular-enabled tenants), Exclude Expired Inventory (for granular-enabled tenants).
All applied filters appear as pills below the search bar. Click **×** on a pill to remove it. Click **Clear All** to reset all filters.
**Results Grid**
Results display in a paginated, sortable table. On hand , Allocated and Available column support sorting and column-level filter overlays are supported for all columns.
Stock status is color-coded per row:
| Color | Status | Condition |
| :----- | :----------- | :----------------------------- |
| Green | In Stock | Available ≥ safety stock |
| Yellow | Low Stock | Available \< safety stock, > 0 |
| Red | Out of Stock | Available = 0 |
| Purple | Excess | Excess quantity > 0 |
| Blue | Infinite | `hasInfiniteInventory` =true |
**Note:** When an inventory record has `hasInfiniteInventory` enabled, the **On Hand** and **Available** columns display `∞` instead of a numeric value, and the status displays as **Infinite** rather than **Out of Stock**. This ensures that items configured for infinite inventory are correctly identified as always available. For more information on enabling infinite inventory, see [Assume Infinite Inventory](#assume-infinite-inventory) below.
Each row has four actions: **View**, **Edit**, **Allocations**, **Delete**.
**Supply & Demand Modal**
The Supply & Demand Modal gives inventory operators a complete, consolidated picture of supply versus demand across multiple UPCs and multiple locations at once.
**It answers the critical question at a glance**: can your current on-hand stock and incoming supply cover projected demand across the time period you care about? Rather than piecing together data from separate Inventory, Future Inventory and Shipments the popup surfaces everything in a single, real-time, unified view — with no manual aggregation and no lag. The result is faster, more confident inventory decisions.
Select one or more rows using the checkboxes on the left, then click **View Supply & Demand**.
The modal shows:
| Metric | Calculation (**B2B Wholesale OMS** =ON) |
| :----------- | :----------------------------------------------------------------------------------------------------------- |
| Total Supply | Current On Hand + Future Incoming Inventory (90-day default window) |
| Total Demand | Unfulfilled shipments (Ready, Future, On Hold, Backorder, Pending) + Orders in remorse period |
| Net Position | Total Supply – Total Demand. Green = positive, Red = negative, Yellow = If sum is positive but less than 100 |
Orders in remorse period are included only when site setting is set to not create shipments for orders in remorse period
The tabs:
**Shipments tab** — Status sub-tabs: All · Ready · On Hold · Backorder · Future, each showing record count and total qty. Columns: Shipment ID, Status, Customer, Order Number, UPC, Location, Future Date, Qty.
**Supply tab** — Two sub-tabs:
* *Current*: UPC, Location, On Hand, Available, Allocated, Safety Stock
* *Future*: Code, Location, External ID, Future On Hand, Future Allocated, Future Available, Expected Date
**Reservations tab** — Displays active B2B inventory reservations for the selected item and location. *(Visible only when the B2B Supply Chain feature is enabled for your tenant)*
**Note:** The **Reservations** tab is only displayed when the B2B Supply Chain feature is enabled for your tenant. For standard tenants where this feature is not enabled, the Reservations tab is not rendered. See the [Reservations](/pages/reservations) for more information on B2B reservations.
A **B2B Account** filter inside the modal scopes all demand data to a specific account. Without a selection, combined B2B + B2C data is shown. By default it shows all account data.
### **View Allocated Shipments**
Click any Allocated value in the inventory table to view a list of Ready shipments that have allocated quantity for that item at the selected location. You can filter this list by Shipment Type or Shipment ID. Click a Shipment ID to open its details in the Orders UI.
If you use [future inventory](/pages/future-inventory "Future Inventory") and have selected a future date limit, then you can view shipments allocated with incoming inventory in the Future Inventory tab. All incoming inventory up to the date limit will be included, but you can filter for a specific date within that range. If your future inventory record is unique by External ID, a column will also be displayed with that ID.
Displayed shipment types include STH, BOPIS, Transfer, and Delivery shipments. Reservations in the cart are not reflected at this time, meaning that the actual allocated quantity of a shipment with reservations may not match the allocations displayed here.
In the new UI, allocated shipments are accessed in three ways depending on the context.
**From the main Inventory page**
Click the **Allocations** button in the actions menu on any inventory row. This opens the [Shipments page](/pages/shipments) pre-filtered by the UPC and location of that row, showing all shipments with allocated inventory for that record.
**Viewing future allocations from the Inventory page**
**Note:** The **Future** tab inside the View/Edit drawer is only visible when you have searched using a future date range filter (via Advanced Filter). Run your search with a future date range first, then open the side panel to access this tab.
Open any inventory record via the **View** or **Edit** action and go to the **Future tab** in the drawer. If future allocations exist for that record, click the **Allocations** button within the Future tab. This redirects to the [Shipments page](/pages/shipments) showing only shipments with Status = Future for that UPC and location.
**View future allocations from the Future Inventory page**
On the [Future Inventory](/pages/future-inventory) page, click the **Allocations** button in the actions menu on any future inventory row. This opens the Shipments page in a new tab, pre-filtered by UPC, location, and the specific future date of that record. It displays all future shipment allocations tied to that incoming inventory record.
### **Managing Inventory Attributes**
#### Set Attribute Values via the API
Once an [Inventory attribute](/pages/schema-inventory-attributes) is defined under **System > Schema > Inventory Attributes**, set its value for a specific product-location combination by including it in the `extensibleAttributes` object of a [Refresh](/api-reference/modifyinventory/refresh) or [Adjust](/api-reference/modifyinventory/adjust) request, or through the [inventory import process](/pages/inventory-import-file).
```json theme={null}
{
"locationCode": "111",
"items": [
{
"upc": "PRODUCT-123",
"extensibleAttributes": {
"seasonal": ["Spring2026"]
}
}
]
}
```
#### Setting Attributes Before Inventory Exists
You can set inventory attributes on a product-location combination before any on-hand stock is received. This is useful if you want storefront visibility or order routing decisions to be driven by attributes ahead of a product's stock arrival.
To do this, send a **Refresh**, **Sync Refresh**, or **Smart Refresh** request that omits `quantity` but includes at least one settable field (`extensibleAttributes`, `safetyStock`, `ltd`, `floor`, `inventoryLocatorName`, or `excessInventoryThreshold`):
* **If a matching product-location record already exists**, the request updates only the specified fields. On-hand quantity is not changed.
* **If no matching record exists**, the request creates the product-location inventory record with `onhand: 0` and persists the provided attributes. The new record is then visible via [Get Inventory](/api-reference/inventory/get-inventory-post).
Requests that omit both `quantity` and any settable metadata field will fail validation. To explicitly create a record with zero stock and no attributes, pass `quantity: 0` instead of omitting it.
#### Viewing Attributes on Inventory Records
Inventory extensible attributes are visible on the inventory UI for each inventory record at the product-location level. The system displays extensible attributes for a product-location record only if at least one attribute has a value. If all attributes are null, the UI will not display any extensible attribute section.
#### Updating Attribute Values
* Navigate to the specific inventory record in the inventory UI
* Locate the extensible attributes section
* Click on View/Edit link and Update one or more attribute values as needed
* Save your change
Inventory attributes are displayed within the View/Edit side panel as inline chips: `AttributeName: Value`. A **Manage Attributes (n)** button shows the count of populated attributes. Add, edit, and remove attributes directly in the pop up on clicking on Manage Attribute button without navigating away.
**First attribute limitation:** The first inventory attribute on a record must be set via the [Refresh](/api-reference/modifyinventory/refresh) or [Adjust](/api-reference/modifyinventory/adjust) API. Once at least one attribute has a value, all subsequent attributes can be managed from the side panel.
You can always update inventory attributes via the [Refresh](/api-reference/modifyinventory/refresh) and [Adjust](/api-reference/modifyinventory/adjust) APIs or [inventory import process](/pages/inventory-import-file).
### **Returns and Inventory Interaction**
During return processing, when you receive the return you can specify whether the product should be restocked at a return location as documented in the [Returns](/pages/receive-a-return) guide.
If you choose to restock the product, then the on-hand quantity is automatically increased appropriately.
### **Assume Infinite Inventory**
The Assume Infinite Inventory feature allows allocation beyond available inventory levels for specific inventory records. You can set this flag via the [Refresh](/api-reference/modifyinventory/refresh) and [Adjust](/api-reference/modifyinventory/adjust) APIs or [inventory import process](/pages/inventory-import-file). It can also be applied at a [inventory segmentation Level](/pages/inventory-segmentation-overview "Inventory Segmentation Overview"), [granular inventory level](/pages/granular-inventory-fields "Granular Inventory Fields") or on [future inventory](/pages/future-inventory "Future Inventory").
When enabled, this Boolean field overrides standard allocation rules, permitting allocation even when inventory is not available. This is an optional field and does not require any tenant or site-level setting to be enabled. If the flag is set to `true`, the system will apply the Assume Infinite Inventory logic for allocation. If the flag is not set or is `false`, standard allocation rules will continue to apply.
To identify which inventory records have this flag enabled, use the [Get Inventory](/api-reference/inventory/get-inventory-post) API with the parameter `includeItemsWithInfiniteInventoryFlag`. Records with infinite inventory will return `hasInfiniteInventory: true` in the response.
**Note:** In the Supply & Demand modal, inventory records with `hasInfiniteInventory` enabled display `∞` in the **On Hand** and **Available** columns, with a status of **Infinite**. This provides a clear visual distinction from standard numeric inventory records and prevents these items from being incorrectly displayed as "Out of Stock."
***
## **6. Platform Integration Map**
### **Upstream Dependencies**
* **Locations:** Physical locations (warehouses, stores) must be configured and set to **Inventory Enabled** before stock can be tracked or allocated at that location.
* **Order Management System (OMS):** Order creation and shipment processes trigger the key **Allocation** and **Deallocation** events that update the inventory quantities.
### **Downstream Impacts**
* **Storefront / E-commerce Site:** Inventory data, driven by the **Real-Time Inventory Service (RIS)**, powers product availability messaging, in-stock filtering, and fulfillment options (BOPIS).
* **Order Routing / Fulfillment:** The Available and Future Inventory quantities are the core inputs for the platform's order routing logic, determining the optimal location to fulfill a shipment.
* **Financial Reporting:** Inventory consumption affects Cost of Goods Sold (COGS) and is essential for accurate balance sheet valuation.
### **Synergistic Features**
* **Order Routing Engine:** Inventory provides the *what* and *where* (product quantity and location), while the Order Routing Engine provides the *how* and *why* (business rules for selecting the best fulfillment source), resulting in minimized fulfillment costs and maximized delivery speed.
* **Location Management:** Defining the properties of a location (like its proximity or fulfillment capabilities) combined with its inventory levels allows for highly accurate and flexible omnichannel experiences, such as offering Ship-from-Store only from locations within a certain radius of the customer.
***
## **7. Related Conceptual Guides**
**For foundational knowledge, refer to:**
* **[Catalog](/concept-guides/catalog):** This guide is a prerequisite because inventory records are tied directly to the product definitions (UPCs) and their attributes defined in the Catalog.
**To understand downstream impacts, refer to:**
* **[Order Routing](/concept-guides/order-routing):** This guide explains how the Available and Future Inventory quantities are used as the foundational data points to select the final, most cost-effective fulfillment location for a customer's order.
**For complementary strategies, refer to:**
* **[Location Admin](/developer-guides/location-admin):** This guide details how to configure the physical entities (stores, warehouses) that hold the inventory, explaining how location-specific settings (like fulfillment capabilities) combine with stock to achieve a greater omnichannel strategy.
# Kibo AI Overview
Source: https://docs.kibocommerce.com/concept-guides/kibo-ai
Learn how Kibo AI, the in-platform assistant, helps operators complete tasks across Kibo Admin by describing them in plain language
## **1. Strategic Overview**
See Kibo AI in action — connect a model, configure it, and watch it create a promotion end-to-end
**Concept Definition**
Kibo AI is the in-platform assistant that lets operators complete work across Kibo Admin by describing it in plain language. It interprets a request, works through the task on the platform, and either fills in the relevant Kibo Admin screen for the operator to review and save, or returns a read-only answer — without the operator needing to know where every setting lives.
**Business Context**
Kibo AI is delivered as a native capability inside the existing Operator Portal (Kibo Admin). It appears as a floating assistant available from anywhere in the platform, and spans the modules operators already use — promotions, catalog and categories, search and merchandizing, order routing, order and returns operations, and analytics. It runs on a bring-your-own-model basis: the operator connects their own model provider credentials, and Kibo AI uses them to reason about requests and generate content. It is enabled per tenant, so each customer turns it on where they want it.
**Value Drivers**
1. **Platform work in plain language:** Operators, merchandisers, and customer service representatives complete multi-step Admin tasks — creating a promotion, building a routing scenario, enriching a product, processing a return, answering a business question — by describing the outcome, rather than navigating and filling every screen by hand. This lowers the expertise required to operate the platform and speeds up routine work.
2. **Human-in-the-loop by design:** For any task that changes data, Kibo AI prepares and fills in the Kibo Admin screen and stops; the operator reviews and clicks Save. Explain and Analyze tasks are read-only. Control of every change stays with the operator, which keeps the assistant safe to adopt on a live production tenant.
3. **Bring Your Own Model — your key, your data, your spend:** Kibo AI runs on model credentials the operator supplies. API keys are stored securely, requests run against the operator's own provider account, and per-model monthly limits cap usage. Operators choose their providers and control cost and data flow.
4. **One assistant across the platform:** Because Kibo AI reaches every major module through a single conversational surface, operators get consistent behavior — the same request pattern, the same review-and-save step, the same transparency — whether they are merchandizing, routing orders, or reporting on revenue.
**Scope Statement**
* **In Scope:** The Kibo AI assistant surface (floating panel, conversation threads, browse-by-capability); the three capability modes (Configure, Explain, Analyze); bring-your-own-model configuration (Agent Models, model slots, credentials, spend limits); brand voices; the capability areas across promotions, catalog and categories, search and merchandizing, order routing, order and returns operations, and analytics; conversation management; and the assistant's step-by-step transparency.
* **Explicitly Excluded:** Step-by-step UI walkthroughs (covered in the Kibo AI how-to guides); API, developer, and model-provider account setup details; the canvas and workflow functionality (not part of the current release); and specific model performance, quality, or pricing, which depend on the provider and model the operator connects.
## **2. Core Concepts Explained**
### **What is Kibo AI?**
Kibo AI is a conversational assistant embedded in Kibo Admin. An operator opens it from a floating icon, then either types a request in plain language or picks a capability area to see what the assistant can do. Kibo AI interprets the request, determines which capability applies, and works through the task on the platform.
Opening the **Choose an area** menu lists the capability areas Kibo AI covers, each with a short description. Selecting one shows example prompts for that area, so an operator new to the assistant can see what it can do without knowing what to ask for.
The interaction follows a consistent pattern. The operator describes an outcome. Kibo AI works through the steps — navigating to the relevant Kibo Admin screen, gathering the details it needs, and asking the operator for any missing decision. For a task that changes data, it fills in the screen and hands control back to the operator, who reviews and clicks Save. For a task that explains a decision or reports on the business, it returns a read-only answer. Throughout, Kibo AI shows its reasoning and the actions it is taking, so the operator can follow along and verify the result.
### **The three modes**
Kibo AI's capabilities fall into three modes, and the mode determines what the assistant does with the result.
1. **Configure** — makes changes. Kibo AI fills in the matching Kibo Admin screen; the operator reviews and clicks Save. Covers promotions, categories, search and merchandizing, order routing, order operations, returns, and product enrichment.
2. **Explain** — read-only. Kibo AI helps the operator understand a decision the platform has already made, such as why an order routed to a particular location or how a promotion is configured.
3. **Analyze** — read-only. Kibo AI answers business questions with charts and numbers directly in the conversation.
Only Configure changes data, and even then only after the operator saves. Explain and Analyze never change anything.
### **Why does Kibo AI matter?**
1. **Operational:** Complex Admin tasks that previously required knowing exact screens, fields, and sequences become a plain-language request. The assistant reaches across modules, so an operator does not switch mental models between merchandizing, routing, and order care.
2. **Governance:** The review-and-save step, read-only Explain and Analyze modes, per-tenant enablement, and secure credential handling make the assistant adoptable on a live tenant without ceding control of production changes.
3. **Cost and data control:** Bring-your-own-model means the operator selects the provider, holds the key, runs requests on their own account, and caps monthly usage per model.
### **When to use Kibo AI**
1. **Configuration at speed:** Setting up promotions, building or editing routing strategies and scenarios, creating categories, and creating merchandizing rules by describing the intended result.
2. **Content enrichment:** Generating and translating product descriptions, titles, SEO metadata, and images in the brand's voice.
3. **Frontline order care:** Looking up orders, applying appeasements and adjustments, and processing returns, refunds, and replacements.
4. **Investigation and reporting:** Understanding why an order routed the way it did, reviewing how a promotion is set up, and answering ad-hoc analytics questions without building a report.
## **3. Functional Components & Configuration Deep Dive**
### **Prerequisites**
Before Kibo AI can be used, three things must be in place: the assistant is enabled on the tenant by Kibo Customer Support; the operator has administrator access to configure models; and at least one model provider credential is connected through Bring Your Own Model. Brand voices are an optional prerequisite for content-generation tasks. Until a model is connected, Kibo AI shows a setup screen that links back to model configuration.
### **Component Architecture**
1. **Assistant surface** — a floating panel available throughout Kibo Admin. It provides a plain-language chat box, a browse-by-capability menu that groups tasks into areas with example prompts, conversation threads with history and search, and a step-by-step view that shows the assistant's reasoning and the actions it takes.
2. **Agent Models (Bring Your Own Model)** — where the operator connects provider credentials and assigns them to model slots. There are three slots: **Thinking** (the reasoning model), **Flash** (a faster model for lighter steps), and **Image** (for image generation). Each slot has spend controls.
3. **Brand Voices** — named, reusable tone-and-style definitions. When Kibo AI generates product or category content, it applies an active brand voice so the wording matches how the brand speaks.
4. **Capability set** — the tasks Kibo AI can perform across modules, organized into the three modes. Configure tasks fill Admin screens for the operator to save; Explain and Analyze tasks are read-only.
### **Configuration-Level Deep Dive**
#### **Model Slots (Bring Your Own Model)**
Each slot uses the credential the operator assigns to it, and spend is capped per slot.
| Slot | Business Purpose | Impact and Trade-offs | Concrete Example |
| :------- | :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |
| Thinking | The reasoning model that plans and works through tasks. | Drives most of the assistant's behavior; a stronger model improves complex tasks but consumes more tokens. | A capable general model is assigned and capped with a monthly token limit. |
| Flash | A faster model for lighter, quicker steps. | Reduces latency and cost on simple steps. | A lower-cost model handles quick lookups. |
| Image | The model used for image-generation tasks. | Only needed if the operator uses product or category image generation; capped by a monthly image limit. | An image-capable model is connected for catalog imagery. |
Credentials store the connection to one model from one provider. Supported providers are OpenAI, Anthropic, Google, and Other (a custom, compatible endpoint). API keys are stored securely and are not shown again after saving. Because requests run on the operator's provider account, usage is billed by the provider, and monthly token and image limits cap consumption per slot.
#### **Brand Voices**
A brand voice pairs a name with a prompt that describes the desired tone and style. Operators can maintain multiple active voices and tell Kibo AI which voice to apply when generating content. Brand voices shape wording only; they do not change what content is created or where it is saved.
| Attribute | Business Purpose | Impact and Trade-offs | Concrete Example |
| :-------- | :------------------------------------------------- | :----------------------------------------------------------------------------- | :------------------------------------------------------- |
| Name | Identifies the voice when the operator selects it. | Makes voices easy to choose in a request. | "Whimsical", "Sporty", "Professional". |
| Active | Makes the voice available to Kibo AI. | Only active voices can be applied. | A voice is marked Active so it appears to the assistant. |
| Prompt | Defines the tone and style the assistant follows. | Directly shapes generated copy; a clear prompt produces more on-brand content. | A prompt instructing a lighthearted, playful tone. |
## **4. Key Capabilities and Business Applications**
### **Natural-Language Merchandizing and Catalog Enrichment**
Kibo AI enriches existing products — descriptions, titles, SEO metadata, translations, and images — in the brand's voice, and controls storefront search through merchandizing rules, redirects, facets, and synonyms. It edits existing products rather than creating new ones.
*Example — Merchandiser:* facing hundreds of products with thin copy, a merchandiser asks Kibo AI to find products missing a short description and to write punchier descriptions in the "Sporty" brand voice; the assistant fills each product screen, and the merchandiser reviews and saves.
### **Promotions Across Their Full Lifecycle**
Kibo AI creates and edits order-level, product, shipping, and Buy X Get Y discounts, sets coupon codes and redemption limits, targets by segment or price list, and controls stacking and state — and, on the Explain side, reviews how existing promotions are configured.
*Example — Marketing Manager:* to launch a summer campaign, a marketing manager asks for a 20% sitewide promotion running specific dates and a coupon limited to the VIP segment; Kibo AI fills the discount screen for review and save, and later answers "which promotions are active this month?" as a read-only review.
### **Order Routing Configuration and Explanation**
Kibo AI configures routing strategies and scenarios — locations, sort order, filter conditions, and split-shipment behavior — for both forward and reverse order types, and separately explains, read-only, why a placed order routed the way it did.
*Example — Fulfillment Manager:* a fulfillment manager builds a Direct Ship strategy that sorts by distance then inventory; Kibo AI fills the strategy and scenario, confirms before any activation because live orders are affected, and later explains why a specific order split across two locations.
### **Frontline Order and Returns Operations**
Handled by the Order (Customer Service) agent and the Returns capability, Kibo AI looks up and modifies orders, applies appeasements and adjustments, and processes returns, refunds, and replacements — with read-only lookups for order summaries, returnable items, reasons, and financials before an operator acts.
*Example — Customer Service Representative:* a representative resolves a damaged-item claim by asking Kibo AI to summarize the order, confirm the item is returnable, and process a refund return with a reason — reviewing each step before saving.
### **Self-Service Analytics in the Conversation**
Kibo AI answers business questions about orders, revenue, fulfillment, products, discounts, and customers, rendering charts and tables inline and interpreting relative time periods.
*Example — Ecommerce Manager:* instead of building a report, an ecommerce manager asks for revenue over the last six months and top products by revenue, and reads the charts directly in the conversation.
## **5. Supported Capabilities & Current Behavior**
**How to read this section.** This guide describes the capabilities Kibo AI exposes in the current release. Any capability not described here is not part of the current release. Where the assistant's behavior has intentional boundaries, they are called out under *Current Behavior Notes*.
**What Kibo AI supports today**
* **Plain-language requests** in chat, or a guided start from browse-by-capability areas.
* **Configure** tasks that fill Kibo Admin screens for the operator to review and save, across promotions, categories, search and merchandizing, order routing (forward and reverse), order operations, returns, and product enrichment.
* **Explain** tasks (read-only) for order routing, promotions, and returns information.
* **Analyze** tasks (read-only) that answer business questions with charts and numbers.
* **Bring Your Own Model** with Thinking, Flash, and Image slots, provider credentials, and per-slot spend limits.
* **Brand voices** applied to content generation.
* **Conversation management** — multiple threads with history, search, rename, delete, and a copyable thread ID.
* **Step-by-step transparency** — the assistant shows its reasoning and the actions it takes.
**Current Behavior Notes** — intentional boundaries of the current release:
| Behavior | How Kibo AI works today | What this means for operators |
| :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| **Operator saves every change** | For Configure tasks, Kibo AI fills the Kibo Admin screen and stops; it does not save. Search synonyms are the exception and save immediately. | Nothing goes live until the operator reviews and clicks Save. |
| **Explain and Analyze are read-only** | These modes describe decisions or report on the business. | They never change data and can be used freely to investigate. |
| **Products are enriched, not created** | The product capability edits and enriches existing products. | Create the product in Kibo Admin first, then use Kibo AI to enrich it. |
| **Some actions are manual** | Kibo AI does not delete synonyms, clone or delete merchandizing rules, name or save a new search-configuration profile, or delete routing strategies or scenarios. | Complete these directly in Kibo Admin. |
| **Routing changes are not instant** | Saved routing changes rely on a cache refresh. | Allow up to about 15 minutes for a saved routing change to take effect. |
| **Routing explanations need a routed order** | Explanations read from the routing logs. | An order that has not been routed yet cannot be explained. |
| **Enabled per tenant** | The assistant is turned on for a tenant by Kibo Customer Support. | If the assistant is not visible, request enablement from Kibo Customer Support. |
| **A connected model is required** | Agentic capabilities need a model connected through Bring Your Own Model. | Without a model, Kibo AI shows a setup screen linking to model configuration. |
## **6. Platform Integration Map**
**Upstream Dependencies**
1. **Tenant enablement** — the agentic capability is turned on for the tenant by Kibo Customer Support. Without it, the Kibo AI assistant does not appear in Kibo Admin.
2. **A connected model (Bring Your Own Model)** — the assistant reasons and generates content using the models assigned to the Thinking, Flash, and Image slots. Without a connected model, no capability runs and Kibo AI shows the setup screen instead.
3. **Model provider account and API key** — requests run on the operator's own provider account. Without a valid key and available spend headroom, requests to that model fail until the credential or limit is corrected.
4. **Administrator access to Agent Models and Brand Voices** — required to connect credentials, assign slots, and configure voices. Without it, the assistant cannot be set up and stays inactive.
5. **Existing module records** — the assistant acts on data that already exists: products, discounts, categories, search configuration, routing strategies, orders, and reporting data. It edits rather than bootstraps an empty module — for example, it enriches existing products rather than creating them.
6. **Active brand voice** — required only for content generation. Without one, generated product and category copy uses a default tone rather than the brand's.
**Downstream Impacts**
1. **Module records change on Save** — when the operator saves a Configure result, the change is written to the underlying module (Discounts, Categories, Search & Merchandizing, Order Routing, Orders, or product content) exactly as if it were entered by hand, and it inherits that module's normal effects. Disabling a category, for example, cascades to its subcategories, and activating a routing strategy changes how live orders route once the routing cache refreshes, in about 15 minutes.
2. **Provider consumption and spend** — every request consumes the operator's model provider account and counts against the per-slot monthly token and image limits, giving one lever to cap agentic spend.
3. **No change from read-only modes** — Explain reads the routing logs and Analyze reads reporting data; neither writes anything back to the platform.
**Synergistic Features**
* **Kibo AI + Bring Your Own Model** — assigning different models to the Thinking, Flash, and Image slots lets operators tune capability, latency, and cost independently for reasoning, quick steps, and imagery.
* **Kibo AI + Brand Voices** — content generation inherits a consistent, reusable tone, so catalog enrichment scales across many products without diluting the brand's voice.
* **Kibo AI + Order Routing (Configure and Explain)** — the same assistant that builds a routing strategy can later explain how a specific order routed under it, closing the loop between how routing is configured and what actually happened.
* **Kibo AI + Analytics** — read-only reporting lets an operator check the effect of a change, such as a promotion's redemptions, in the same conversation right after making it.
* **Kibo AI + native Kibo screens and controls** — because Configure results save through the standard Admin screens, they respect the platform's existing validation, publishing, permissions, and audit behavior rather than bypassing them.
## **7. Related Guides**
* [**Set Up and Use Kibo AI**](/pages/kibo-ai-setup) — connect a model, configure brand voices, and use the assistant.
* [**Kibo AI Agent Capabilities**](/pages/kibo-ai-configure) — the full list of Configure, Explain, and Analyze tasks.
* [**Configure with Kibo AI**](/pages/kibo-ai-configure) · [**Explain with Kibo AI**](/pages/kibo-ai-explain) · [**Analyze with Kibo AI**](/pages/kibo-ai-analyze) — capabilities by mode.
* The module conceptual guides for the areas Kibo AI works across: [Promotions](/concept-guides/promotions), [Catalog](/concept-guides/catalog), [Search & Merchandizing](/concept-guides/search-and-merchandizing), [Order Routing](/concept-guides/order-routing), [Fulfillment](/concept-guides/fulfillment), and [Returns & Reverse Logistics](/concept-guides/returns-and-reverse-logistics).
# Order Routing Overview
Source: https://docs.kibocommerce.com/concept-guides/order-routing
Determine optimal fulfillment locations for customer orders using dynamic business rules
## **1. Strategic Overview**
See the Order Routing API documentation for programmatic access
Get an introduction to order routing in Kibo
See an overview of the order routing strategies dashboard
**Concept Definition:** Order Routing is the dynamic decision-making logic that determines the optimal fulfillment location(s) for a customer order based on a configured set of business rules and real-time inventory and location data.
**Business Context:** Kibo Commerce's Order Routing serves as the central orchestration engine within the unified commerce platform, translating overall fulfillment strategy into action. It is essential for maximizing inventory utilization across all network nodes—warehouses, stores, and suppliers—to meet customer expectations and operational goals.
**Value Drivers:**
* **Optimized Fulfillment Cost:** By factoring in criteria like geographic proximity or inventory carrying costs, routing logic minimizes shipping expenses and reduces the need for costly markdowns by prioritizing the movement of slower-moving inventory.
* **Enhanced Customer Experience:** Intelligent location assignment allows the platform to offer faster delivery options and a higher probability of fulfillment, significantly improving the ability to meet delivery promises.
* **Maximized Inventory Utilization:** The system leverages a single view of inventory across the entire enterprise, allowing retailers to treat store stock as sellable online inventory, effectively increasing the available pool of products and reducing stockouts.
**Scope Statement:** This guide provides a complete conceptual framework for Order Routing, detailing its core components, configuration attributes, and functional capabilities. It covers how routes, scenarios, filters, and after actions are used to define the routing hierarchy and logic. It explicitly excludes the technical details of API implementation, specific configuration *steps* in the Admin UI, and deep dives into the separate concepts of **Fulfillment**, **Reverse Logistics**, **Order Routing Extensibility** configuration.
***
## **2. Core Concepts Explained**
### **What is Order Routing?**
Order Routing is a powerful service within the Kibo Commerce platform that designs and executes order-specific assignment and visibility logic. It operates on a hierarchical structure of **Routes**, **Scenarios**, **Filters**, and **After Actions** to create a **Routing Strategy**. When a new order or shipment is created, Order Routing evaluates this strategy against the line items, customer address, and fulfillment location data to recommend or assign the single best location or set of locations to fulfill the order.
### **Why does Order Routing matter?**
Order Routing provides the sophisticated control required for enterprise-level omnichannel operations.
* **Operational Benefits:** It eliminates manual assignment, reducing errors and processing time. It enables advanced strategies like Ship-from-Store (SFS) and Delivery from Store, which are important for leveraging store assets as mini-distribution centers and increasing the speed of delivery to nearby customers.
* **Financial Benefits:** By dynamically choosing the lowest-cost or fastest-moving inventory location, it directly impacts the profitability of each order. It helps reduce markdowns by prioritizing locations with slower-moving inventory, ensuring products are sold at full price.
* **Customer Experience Benefits:** The system can be invoked early in the buying process, such as during the cart or checkout steps, to perform a preliminary routing check. This **early invocation** determines *in real-time* if a specific delivery or pickup method is viable based on the customer's location and product availability. This prevents customers from completing an order only to be notified later of a stock issue, thereby improving conversion rates by maintaining high customer confidence in fulfillment promises.
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture: The Routing Hierarchy**
The Order Routing system is organized into a hierarchy that translates high-level strategy into executable logic:
1. **Routes (or Strategies):** The highest level, representing the overall fulfillment approach for a general order type (e.g., all standard home delivery orders). A route contains one or more Scenarios.
2. **Scenarios:** A specific set of locations, a set of Filters, and a set of After Actions. A single order or shipment is evaluated against scenarios in a defined sequence until a successful location assignment is made or the route is exhausted.
3. **Locations:** The individual physical or virtual entities (e.g., warehouse, store, dropshipper) that hold inventory and can fulfill orders. Locations are added directly to a Scenario.
4. **Filters:** Logic defined within a Scenario to exclude locations that do not meet certain criteria, narrowing the pool of candidates.
5. **After Actions:** Logic that executes *after* Order Routing has attempted to assign an order within a Scenario. Common after actions include failing over to the next Scenario or splitting the order to fulfill different items from different locations or putting the items in customer care / cancellation.
***
### **Configuration-Level Deep Dive**
Order Routing logic supports two primary fulfillment types and their consolidation requirements:
#### **Fulfillment Types Supported in Order Routing**
| Fulfillment Type | Description in Order Routing |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Direct Ship** | The order is shipped directly to the customer's delivery address from the assigned fulfillment location (e.g., warehouse or store). This is the standard Ship-to-Home (STH) method. |
| **Delivery** | The order is delivered from the fulfillment location (often a store) directly to the customer's location via local/in-house delivery or a third-party last-mile service, typically used for local, scheduled, or perishable goods delivery. |
#### **Consolidation and Transfer Routes**
Consolidation is the process of attempting to source all items in an order from a minimal number of locations to reduce shipping costs and customer shipments. When consolidation requires moving inventory between locations, **Transfer Routes** are utilized.
A **Transfer Route** defines the logic for moving inventory from a **source location** to a **receiving location**. Order Routing is invoked for the transfer to determine the best location to supply the missing inventory.
Transfer Routes are supported for:
* **Direct Ship with Transfers (Consolidation):** If an order is intended for Direct Ship but requires items from multiple locations, the platform can be configured to attempt a **consolidation transfer**. A selected receiving location (e.g., a primary Distribution Center) that has *most* of the items can request the remaining items from other source locations via a transfer route. The order is then fully consolidated at the receiving location before shipping to the customer.
* **Delivery with Transfers (Consolidation):** Similar to Direct Ship, an order flagged for local delivery can have its inventory consolidated at the designated delivery-originating location via a transfer route before the final-mile delivery is executed.
* **BOPIS with Transfers:** Buy Online, Pickup In Store (BOPIS) itself **never uses Order Routing** for the initial assignment, as the customer has explicitly chosen the pickup location. **However**, if BOPIS is configured to support transfers and if the chosen pickup location does not have the inventory, Order Routing is **invoked for a Transfer Route** to assign the optimal source location to send the missing item(s) to the designated BOPIS store. The final customer fulfillment is still BOPIS, but the underlying inventory movement uses Order Routing's transfer logic.
***
## **4. Functional Components & Configuration Deep Dive (Continued)**
### **Filters: Defining Assignment Logic**
**Filters** are conditional logic rules that restrict the pool of potential fulfillment locations within a Scenario. They ensure that an order is only assigned to locations that meet the required operational, inventory, or order-specific criteria. Filters can be built using both **first-class fields** (out-of-the-box attributes) and **Extensible Attributes** (custom attributes).
| Filter Category | Business Purpose | First-Class Field Example | Extensible Attribute Example |
| :-------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Item** | To assign items based on item characteristics. | **Weight (Numerical)**Filter assignment based on the weight of the item | **Hazardous Good (Boolean):** Filter to only include fulfillment locations certified for shipping hazardous materials. |
| **Location** | To match fulfillment location capabilities or operational constraints. | **Fulfillment Location Zip/Postal Code (List)**Contained in the location address, this may be used to either prevent or allow assignment to locations that match a particular zip or postal code. | **Insulated Packaging (Boolean)**Route items that are perishable to locations that support insulated packaging. |
| **Order** | To route based on the characteristics of the entire order. | **Order Total Price:** Only include locations for orders where the total price is over a set high-value threshold. | **CustomShippingWindow (Date Range):** Only route orders that fall outside a location’s pre-configured black-out dates for maintenance. |
| **Customer** | To provide differentiated fulfillment based on customer segments or loyalty. | **Customer Account Type:** Assign to specific locations designated to handle only B2B accounts. | **VIPTier (Text):** Route orders from customers with a 'Platinum' tier custom attribute to a warehouse known for premium packaging. |
| **Inventory** | To match the stock status or inventory-specific settings. | | **HoldForKiosk (Boolean):** Exclude locations that have stock marked as 'True' for a custom attribute indicating inventory is reserved for in-store kiosk sales. |
The **Extensible Order Routing** capability allows the business to select which custom product, location, customer, order, and inventory attributes are available to be used in filter logic, providing maximum flexibility in defining unique routing rules.
***
## **5. Key Capabilities and Business Applications**
The true value of Order Routing is demonstrated in its ability to execute complex, real-world fulfillment strategies.
### **Capability: Geographic Proximity Routing for Cost Optimization**
**Functional Explanation:** This capability uses the latitude and longitude of the customer's shipping address and all candidate fulfillment locations to calculate the distance. This distance can then be used in the routing logic, either as a primary sorting mechanism to prioritize the closest location or as a filter to exclude locations beyond a cost-effective radius. This directly impacts shipping costs and delivery speed.
Business Application Example:
Industry: Direct-to-Consumer (DTC) Brand
Scenario: A high-growth DTC apparel brand is fulfilling orders from three regional distribution centers (DCs) and 50 retail stores. To manage rising parcel carrier costs, the operations team needs to ensure standard ground orders are fulfilled by the closest inventory source that can complete the entire shipment. Order Routing is configured such that the order is assigned to the closest location to the customer that can source all items. This results in faster delivery times and a significant qualitative reduction in average shipping expense per order.
### **Capability: Excess Inventory Prioritization**
**Functional Explanation:** This capability enables locations to be prioritized based on Excess Inventory. Routing based on Excess Inventory can be used as a sorting rule within a scenario to actively select the location that holds the highest excess stock for the item, accelerating inventory turnover.
Business Application Example:
Industry: Fashion & Apparel Retailer (Omnichannel, seasonal)
Scenario: A major fashion retailer carries seasonal goods that must be cleared to make space for new collections. To minimize end-of-season markdowns, the Inventory Manager creates a specific routing scenario for current season items. The scenario applies a sorting logic that prioritizes locations with the highest Inventory Excess for the specific item. When a customer places an order for a sweater, the system assigns it to the store or DC that has the highest Excess Inventory.. This proactively handles inventory overstock, resulting in fewer required markdowns and improved gross margin realization.
### **Capability: Daily Order Assignment Thresholds**
**Functional Explanation:** This allows the business to configure a maximum number of orders that a specific fulfillment location can receive or process in a defined period (e.g., daily). This serves as a capacity constraint filter to prevent overloading a location, especially for stores where associates have other primary duties.
Business Application Example:
Industry: Enterprise Electronics Retailer (High-value items, complex fulfillment)
Scenario: A national electronics chain uses its retail stores to fulfill a high volume of accessory orders (ship-from-store). Store managers report that exceeding 75 orders per day negatively impacts their in-store customer service. Once a store's assignment count for the day reaches this limit, Order Routing automatically excludes it from the assignment pool for new orders until the next day. This prevents burnout of store staff and results in better in-store service and a more consistent, reliable fulfillment process for online customers.
### **Capability: Dynamic Routing Based on Custom Attributes**
**Functional Explanation:** This capability leverages **Extensible Order Routing** to enable dynamic assignment logic based on custom (non-standard) data points associated with the Item, Location, Order, Customer, or Inventory. By enabling a custom attribute (like a `Boolean`, `Text`, or `Integer`, `List` field) in the respective platform component, the attribute becomes available for use in routing **Filters**. This allows the business to build sophisticated, highly granular routing rules that reflect unique operational requirements or specialized fulfillment programs not covered by standard, out-of-the-box fields.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor (Complex pricing, client accounts)
* **Scenario (Customer Attribute):** An industrial equipment distributor has high-value B2B customers who have negotiated specific Service Level Agreements (SLAs) for fast fulfillment. These 'Preferred Accounts' are flagged with a custom **Customer Attribute** called **"ServiceTier: Gold."** The Order Routing strategy includes a dedicated Gold Tier Scenario with a customer filter for this attribute. This scenario only includes locations that are guaranteed to ship within four hours of order placement. If a Gold Tier customer places an order, the system first attempts to route to these premium locations. This ensures the business meets its contractual SLA obligations, resulting in fewer penalties and a stronger long-term customer relationship.
* **Industry:** Marketplace Operator (Multi-vendor management)
* **Scenario (Item and Location Attributes):** A marketplace operator needs to route bulky, high-freight-cost items only to specific fulfillment partners that have the logistical capacity to handle them. The operator adds a custom **Item Attribute** called **"OversizedShippingFlag"** (Boolean) to all applicable products. Simultaneously, they add a custom **Location Attribute** called **"FreightCertified"** (Boolean) to the certified fulfillment partner warehouses. The routing scenario uses a Filter: **`Item.OversizedShippingFlag = True` AND `Location.FreightCertified = True`**. This precisely links the specialized product requirement to the specialized location capacity, resulting in lower freight exceptions and reliable fulfillment for large items.
***
## **6. Platform Integration Map**
### **Upstream Dependencies**
* **Inventory Management:** Requires accurate, real-time inventory visibility across all potential fulfillment locations (warehouses, stores, suppliers) to function. Outdated or inaccurate stock levels will lead to fulfillment failures.
* **Location/Facility Management:** Requires all physical locations to be properly set up, enabled for fulfillment, and have their operational attributes (e.g., coordinates, transfer-enabled status) correctly configured in the platform.
* **Product Catalog:** Optional - required if using Item extensible attributes. Requires all items to have necessary attributes (both first-class and extensible) populated, as these are used by Item-based filters in the routing logic.
### **Downstream Impacts**
* **Fulfillment/Order Management System (OMS):** Order Routing directly dictates the destination of the shipment, initiating the fulfillment workflow (e.g., picking, packing, shipping) at the assigned location.
* **Shipping & Logistics:** The assigned location determines the origin of the shipment, which impacts the available carrier options, shipping rates, and expected delivery time provided to the customer.
* **Customer Service:** The assignment decision drives all post-purchase inquiries, as Customer Service Representatives (CSRs) need to know the fulfilling location to assist with status updates, changes, or cancellations.
### **Synergistic Features**
* **Reverse Logistics:** When Reverse Logistics is enabled in Kibo Commerce, Order Routing can support returns processing through return routes and disposition routes. These specialized routing configurations determine where returned items should be sent for inspection, restocking, or disposal based on return reason / product condition. Return routes handle the initial inbound movement of customer returns to the appropriate receiving location. Disposition routes determine the subsequent routing of returns based on their final disposition (restock, refurbish, liquidate, discard). This capability extends Order Routing's intelligence to the post-purchase phase, enabling businesses to automate returns handling and optimize reverse supply chain costs.
* **Inventory Segmentation:** This complementary feature allows businesses to ring-fence specific inventory for certain channels or orders. Order Routing logic can target or exclude these segments, ensuring, for example, that stock reserved for in-store purchases is not routed to an online order.
***
## **7. Related Conceptual Guides**
For foundational knowledge, refer to:
* **[Inventory](/concept-guides/inventory):** This guide is a prerequisite to understanding Order Routing, as routing rules are entirely dependent on having an accurate, unified view of inventory across the enterprise.
To understand downstream impacts, refer to:
* **[Fulfillment](/concept-guides/fulfillment):** This guide details the actual operational processes that are executed at the fulfillment location once Order Routing has successfully assigned the shipment.
For complementary strategies, refer to:
* **[Extensible Order Routing](/pages/extensible-order-routing):** This guide explains how to define and manage the custom product, location, order, customer, and inventory data points that are utilized by Order Routing's advanced filtering capabilities to achieve greater business specificity.
# Payments
Source: https://docs.kibocommerce.com/concept-guides/payments
Accept, authorize, and manage monetary transactions across all sales channels securely
# **Payments: A Conceptual Guide to the Kibo Commerce Financial Core**
***
## **1. Strategic Overview**
**Concept Definition:** Payments in Kibo Commerce represents the foundational platform capabilities and integrated processes for securely accepting, authorizing, capturing, crediting, and refunding monetary transactions across all sales channels.
**Business Context:** The platform's payment framework is an agile, API-driven solution positioned as the central financial core for enterprise e-commerce operations, ensuring secure, compliant, and channel-agnostic transaction management to drive a unified commerce experience.
**Value Drivers:**
1. **Increased Revenue Velocity:** Support for a diverse array of configurable payment types, including credit cards, digital wallets, and alternative methods, removes checkout friction and broadens market reach, designed to increase customer conversion.
2. **Optimized Working Capital:** Flexible authorization and capture settings, align fund collection with fulfillment activities, which is designed to improve cash flow and mitigate financial risk associated with order changes.
3. **Reduced Compliance and Security Risk:** Integration with specialized payment gateways and built-in tokenization features protect sensitive customer data and help maintain adherence to Payment Card Industry Data Security Standards (PCI DSS), securing the overall transaction ecosystem.
**Scope Statement:** This guide covers the conceptual and functional configuration of payment types, payment gateways, authorization/capture logic, and key payment actions within the Kibo Commerce platform. It explicitly excludes deep technical details such as API specifications, payment gateway setup credentials, or third-party fraud service implementation instructions.
***
##
## **2. Core Concepts Explained**
**What is Payments?**
Payments is the core subsystem within the Kibo Commerce platform responsible for managing the **lifecycle of a financial transaction** from the customer's intent to pay through to the final settlement or refund. It serves as the secure layer between the storefront, the **Order Management System (OMS)**, and external **Payment Gateways** (which handle the secure authorization and money movement). Each step in the transaction is recorded as a detailed **Payment Interaction** to maintain a comprehensive audit trail and status history, which is fundamental to financial reconciliation.
* **Authorization:** The initial process where the payment gateway confirms the availability of funds and reserves the required amount on the customer's account.
* **Capture (Redeem):** The process of transferring the reserved funds from the customer's account to the merchant's account; for gift cards, this action is referred to as redeem.
* **Void:** The cancellation of a payment that has been **Authorized** but **not Captured**. It releases the reserved funds back to the customer.
* **Credit/Refund:** The process of returning captured funds to the customer.
**Why does Payments matter?**
The payment framework is important because it dictates the operational efficiency, financial integrity, and customer experience of an enterprise commerce solution.
* **Operational Benefits:** The system provides flexibility by allowing merchants to define the precise **timing of fund capture** (e.g., authorizing at order submit and capture at shipment fulfillment), which is essential for complex omnichannel and distributed fulfillment models, such as back-ordered items or ship-from-store. This prevents customer chargebacks due to premature billing.
* **Financial Benefits:** By supporting **multiple payment types** and enabling **payment ranking**, the system can be configured to minimize payment failure rates and maximize the success of capture and refund operations, directly protecting profit margins. Furthermore, the use of payment tokenization allows for secure storage of customer payment details, promoting repeat purchases without increasing the merchant's PCI compliance scope.
* **Customer Experience Benefits:** Offering a wide, configurable array of payment methods, including digital wallets, B2B-specific options like Purchase Orders, and store credit/gift cards, provides a frictionless, personalized, and convenient checkout experience, which is designed to improve customer satisfaction and reduce cart abandonment.
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
The Payment subsystem is composed of a tightly integrated set of components that manage the transaction lifecycle:
1. **Payment Gateway Service:** The configured external service connection responsible for secure transaction processing.
* **Functionality:** Handles authorization, capture, credit, and void interactions with financial institutions.
2. **Payment Types:** Defines the acceptable payment instruments.
* **Support for Credit Cards:** Allows for various card types (e.g., Visa, Mastercard) assigned to a gateway.
* **Support for Digital Wallets:** Integration with external providers like PayPal, Apple Pay, etc.
* **Support for Gift Cards and Store Credit:** Includes both external (Gateway) and internal (Platform) gift cards.
* **Support for Purchase Orders:** A dedicated B2B credit-based payment method.
3. **Payment Interactions:** The chronological, auditable log of all actions (Authorize, Capture, Void, Credit, Decline) performed on a payment.
* **Purpose:** Tracks the payment's **Payment State** (e.g., Authorized, Captured, Voided) and history for reconciliation.
4. **Security and Compliance:** Mechanisms ensuring data protection.
* **Functionality:** Tokenization of payment data to protect sensitive information and adherence to industry security standards.
5. **Payment Ranking and Auto Capture Settings:** Business rules for prioritizing and timing financial actions.
* **Purpose:** Govern the sequence in which the system executes captures and refunds on multiple payment types for a single order.
***
###
### **Configuration-Level Deep Dive**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment Gateway** | Defines the unique connection credentials for a specific external processor (e.g., a specific instance of Cybersource). | Choosing an industry-leading gateway like Cybersource provides comprehensive fraud management tools and support for various tokenized transactions, | An Enterprise Electronics Retailer configures a Cybersource instance with specific credentials to handle all Visa and Mastercard transactions. |
| **Payment Type (e.g., Visa, Check by Mail, Purchase Order)** | Enables or disables a specific payment type offered to the customer on a per-site basis. | Enabling new payment types expands customer options but requires corresponding fulfillment or reconciliation processes to be established. | A DTC Brand enables "PayPal Express" as a Payment Type to allow customers to check out directly from the cart page. |
| **Payment Type: Order Processing Behavior** | Controls whether authorization and capture occur simultaneously or as separate steps during the order process. | Setting this to Authorize and Capture on Order Placement risks customer dissatisfaction and potential chargebacks if the order is delayed or cancelled after funds are collected. Separating them (Capture on Order Shipment) reduces this risk and improves the customer experience by ensuring funds are collected only when goods are ready. | A Fashion & Apparel Retailer sets this to Authorize and Capture on Order Placement but immediately faces customer frustration when an item is back-ordered and the customer's funds were collected well before fulfillment. |
| Auto Capture Toggle (General) | A global site setting that enables the system to automatically trigger the capture of authorized funds based on fulfillment events. | Enabling this automates revenue collection and is vital for scaling high-volume operations, but requires rigorous, accurate fulfillment status updates from the OMS. | A Marketplace Operator enables Auto Capture across all credit card payments to ensure timely revenue collection as soon as their vendors fulfill a shipment. |
| Flexible Auto Capture Settings (Shipment State/Workflow) | Allows the merchant to select a specific, granular Shipment State (e.g., *Customer Picked Up* or *In Transit*) as the definitive trigger for payment capture. | This granular control is vital for omnichannel scenarios. Setting the trigger too early creates friction; setting it at the final step (e.g., *Shipped*) optimizes financial timing. | For a "Click & Collect" flow, the capture is set to trigger only when the shipment status changes to Customer Picked Up in the Fulfiller UI. |
| Payment Ranking (Capture) | Prioritizes the sequence in which multiple payment methods (e.g., Gift Card and Credit Card) are drawn down to cover the order total. | Higher-ranked methods are targeted first for capture, allowing merchants to enforce business logic, such as always depleting store credit before charging external payment accounts. | The retailer sets the Capture Ranking as "Store Credit, Visa," ensuring that the customer's internal credit balance is always fully utilized before any charge is made against their credit card. |
| Purchase Order: Credit Limit (Customer Account Setting) | The maximum total monetary credit amount a specific customer is permitted to spend using the Purchase Order payment method. | Setting a limit manages financial risk for the merchant. The available balance increases when the customer pays an outstanding PO. | The B2B account for a university department is assigned a Credit Limit of \$75,000 for all Purchase Order transactions on the site. |
## **4. Key Capabilities and Business Applications**
### **Capability: Manual Capture**
**Functional Explanation:** Manual Capture is the direct merchant intervention to initiate the collection of funds after an initial **Authorization** has been successfully performed. While **Auto Capture** automates this, Manual Capture provides granular control in scenarios where the fulfillment process is handled externally or requires special validation. Merchants can manually capture the full authorized amount or a partial amount through the Admin UI or API, provided the capture occurs before the authorization expires.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor (Complex pricing, client accounts, bulk ordering)
* **Scenario:** A client places a large, complex order for custom-cut materials using a credit card. Due to the custom nature, the final quantity and price are adjusted only after the items are physically fabricated, days after the initial order and authorization. The distributor has disabled auto-capture for this product line. A customer service representative (CSR) later uses **Manual Capture** to charge the customer the precise, final, lower-than-authorized amount for the fabricated material, avoiding the need for a separate refund process and resulting in accurate initial billing and a better customer experience.
### **Capability: Auto Capture**
**Functional Explanation:** Auto Capture is a site-level configuration that automates the process of converting a payment **Authorization** (reserved funds) into a **Capture** (collected funds). Auto capture can be configured to capture on a specific shipment step or status, capture the order total when the first shipment on the order is fulfilled or force a capture on a specific day. When enabled, the system automatically checks for and initiates the capture action based on the configured **Order Processing Behavior** or **Flexible Auto Capture Settings** (typically tied to a shipment's fulfillment status). This eliminates the need for manual intervention by a CSR or system user to collect payment after the authorization is in place, reducing the administrative overhead associated with payment reconciliation.
**Business Application Example:**
* **Industry:** Direct-to-Consumer (DTC) Brand (Subscription models, customer acquisition focus)
* **Scenario:** A DTC brand experiences high order volume and uses a complex, distributed fulfillment network with multiple warehouses. To maintain efficiency and ensure timely revenue recognition, the brand enables **Auto Capture** with the trigger set to the "Fulfilled" shipment state. As each order portion is packaged and shipped from the respective warehouse, the OMS automatically updates the shipment status, which triggers the platform to charge the customer's credit card for the exact value of the shipped items. This automation ensures revenue collection is synchronized with product shipment across the distributed network, resulting in significant time savings for the finance and order management teams.
### **Capability: Payment Extensibility**
**Functional Explanation:** Payment Extensibility is a core platform feature that leverages the Kibo Commerce developer framework, allowing merchants to implement a **custom payment gateway** that is not supported natively out-of-the-box. This is achieved by creating an application in the Dev Center, configuring it as a **gateway adapter**, and then installing that application in the tenant. This framework allows the merchant to define the logic for essential payment interactions—such as authorization, capture, and credit—to communicate with a specific, external third-party payment processor or system.
**Business Application Example:**
* **Industry:** Marketplace Operator (Multi-vendor management, compliance)
* **Scenario:** The marketplace operator has an existing, preferred relationship with a financial services provider whose payment gateway is not one of Kibo Commerce’s Out-of-the-Box (OOB) integrations. The operator uses **Payment Extensibility** to build a **custom gateway adapter application** that facilitates communication between the Kibo platform and their preferred third-party gateway. This allows the operator to maintain their existing financial infrastructure and negotiated processing rates while leveraging the Kibo Commerce platform, resulting in seamless financial continuity and reduced integration switching costs.
### **Capability: Purchase Order (PO) Payment Method**
**Functional Explanation:** The Purchase Order payment type is a B2B-focused feature that allows an authorized corporate customer to pay for goods using a formal, pre-approved **PO Number** against a configurable **Credit Limit**. This is a site- and customer-specific setting. The system tracks the customer’s available credit. The PO payment is typically authorized instantly against the customer's available credit.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor (Complex pricing, client accounts, bulk ordering)
* **Scenario:** A purchasing manager for a large manufacturing firm needs to place a time-sensitive, \$30,000 order for spare parts. The customer's account is pre-configured with a \$50,000 credit limit and the PO payment type is enabled. The manager selects **Purchase Order** at checkout, enters the required PO number and the system authorizes the payment instantly against the remaining credit. This capability eliminates the delay of invoicing and payment negotiation for established clients, resulting in a significantly faster order-to-delivery cycle.
### **Capability: Automatic and Manual Refunds**
**Functional Explanation:** The platform provides two distinct methods for returning funds to the customer: **Automatic Refunds** and **Manual Refunds**.
* **Automatic Refunds:** These are system-triggered actions, typically initiated when a return is successfully processed and accepted within the Order Management System (OMS). The system determines which payment method to credit first based on the configured **Payment Ranking** for refunds, ensuring a consistent and automated financial reconciliation process.
* **Manual Refunds:** These are initiated directly by a business user, such as a Customer Service Representative (CSR), through the Admin UI. A CSR has the flexibility to select the specific, preferred payment type to refund on
**Business Application Example:**
* **Industry:** Fashion & Apparel Retailer (Omnichannel, seasonal, complex sizing)
* **Scenario:** A customer returns a high-cost dress that was purchased using a credit card and a small amount of promotional **Store Credit**. To manage the high volume of standard returns, the retailer relies on **Automatic Refunds** to credit the customer's credit card instantly upon verification of the returned item. However, in a scenario where the customer paid with two credit cards, a CSR can perform a **Manual Refund** to split the refunded amount between the two cards exactly as requested by the customer. This flexibility ensures efficiency for standard returns while allowing customer-centric adjustments for unique financial situations, resulting in high customer satisfaction and minimal manual financial adjustments.
***
## **5. Platform Integration Map**
| Direction | Component | Description and Combined Value |
| :------------------------ | :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Upstream Dependencies** | **Order Creation/Checkout** | The checkout process is the primary input, providing the payment details, payment type selection, and the authorization request amount. This is the prerequisite for all subsequent payment actions. |
| | **Customer Accounts** | Required for securely storing **Saved Payment Methods** (tokens) and to apply customer-specific financial rules, such as the **Credit Limit** for Purchase Orders. |
| | **Promotions/Discounts** | The final, net order total after all discounts are applied is the exact monetary value that the Payments system must authorize and capture, ensuring billing accuracy. |
| **Downstream Impacts** | **Order Management System (OMS)** | The OMS relies on the payment's current state (**Authorized** or **Captured**) to trigger and advance fulfillment workflows (e.g., fulfilling a shipment). The OMS also triggers the final capture based on its shipment status. |
| **Synergistic Features** | **API Extensions** | The core feature enables **Payment Extensibility** by providing the mechanism to build and deploy custom gateway adapters, allowing the platform to connect to any required external payment service. |
| | **Fraud Checking Applications** | These third-party services can be integrated (often via API Extensions) to analyze the payment and order details *before* the Authorization interaction is sent, mitigating risk and reducing payment processor fees associated with declined transactions. |
***
## **6. Related Conceptual Guides**
**For foundational knowledge, refer to:**
* **[Fulfillment](/concept-guides/fulfillment):** This guide explains the order and shipment life cycles, which are the direct system triggers for payment capture and important for utilizing **Flexible Auto Capture**.
* **[Customer API](/developer-guides/customer):** This guide details how customer records are managed, which is a prerequisite for saving payment methods and enabling B2B credit-based features like the **Purchase Order Credit Limit**.
**To understand downstream impacts, refer to:**
* **[Returns and Reverse Logistics](/concept-guides/returns-and-reverse-logistics):** This guide details the process for returning funds and managing customer monetary adjustments, which is directly affected by the configured **Payment Ranking** and the original payment method's disposition.
**For complementary strategies, refer to:**
* **[API Extensions](/pages/getting-started-with-api-extensions):** This guide explains the development framework that enables **Payment Extensibility**, detailing how the two concepts work together to achieve greater business goals like connecting to localized or specialized payment gateways.
**For specific payment settings, refer to:**
* **[Payment Gateway Settings](/pages/payment-gateways):** This guide provides detailed instructions on the configuration, credential management, and supported providers for external payment processors that authorize and capture funds.
* **[Payment Type Settings](/pages/payment-types):** This guide covers the process for enabling specific payment methods (like credit cards, checks, or digital wallets) on a per-site basis and assigning them to a configured payment gateway.
* **[Auto Capture Settings](/pages/payment-ranking-and-auto-capture):** This guide details the configuration of the general Auto Capture toggle, the definition of the capture event trigger, and the use of the **Flexible Auto Capture Settings** tied to shipment states.
# Pricing
Source: https://docs.kibocommerce.com/concept-guides/pricing
Learn how price lists enable dynamic, targeted pricing strategies for B2C and B2B commerce
# **KiboCommerce Conceptual Guide: Pricing**
See the Pricing API documentation for programmatic access
Learn how to create and manage price lists to control product pricing
### **1. Strategic Overview**
This guide provides a comprehensive conceptual overview of the **Price List** system in KiboCommerce. This system is the engine that drives all pricing and product entitlement strategies on the platform. It moves far beyond simple price tags, enabling businesses to execute complex, multi-layered pricing based on customer segments, purchase volume, and specific commercial agreements.
* **Concept Definition:** A Price List is a collection of rules that can override a product's standard catalog price and control its visibility for specific shoppers or contexts.
* **Business Context:** Mastering the Price List system allows a business to implement sophisticated pricing strategies for B2C (e.g., VIP tiers, scheduled sales) and B2B (e.g., negotiated contract pricing, curated catalogs) commerce, directly impacting revenue, customer loyalty, and competitive positioning.
* **Scope Statement:** This document covers the complete functionality of Price Lists, including their core settings, the inheritance model, the resolution logic that determines which price list applies, the use of exclusivity for product entitlement, and the detailed configuration of individual price entries.
***
### **2. Core Concepts Explained: Dynamic and Targeted Pricing**
After defining your products, the next step is to determine their price. In KiboCommerce, this is managed through a flexible and hierarchical Price List system. A Price List is not just a list of prices; it's a powerful rules engine.
#### **2.1 The Price List: A Layer of Pricing Rules**
A Price List is a set of "price entries," where each entry can override the default catalog price for a specific product under certain conditions. You can have many price lists, each designed for a different purpose, such as a "Wholesale Price List," a "VIP Customer Price List," or a "Holiday Sale Price List."
**Business Application Example:**
* **Industry:** Direct-to-Consumer (DTC) Brand
* **Scenario:** A brand's flagship product has a standard catalog price of \$100. They create a "Loyalty Club" Price List. Within that list, they create a single price entry for the flagship product, setting its price to \$85. Now, any customer who is part of the Loyalty Club will see the \$85 price instead of the standard \$100.
#### **2.2 Inheritance: Building Tiered Pricing with Parent Price Lists**
A cornerstone of the Price List architecture is **inheritance**. A price list can be assigned a **Parent Price List**, from which it will inherit all price entries. The child list can then be used to override just a few of those inherited prices, creating a tiered structure that is efficient and easy to manage.
**Business Application Example:**
* **Industry:** B2B Office Supply Distributor
* **Scenario:** The distributor creates a "Silver Tier" Price List with standard wholesale pricing. They then create a "Gold Tier" Price List and set its parent to the "Silver Tier" list. The "Gold Tier" list only needs to contain entries for the 10 products where Gold customers get an *additional* 5% discount. For all other thousands of products, it automatically falls back to the pricing inherited from the Silver Tier list, avoiding massive data duplication.
#### **2.3 Resolution: How KiboCommerce Determines the Correct Price**
When a shopper visits your site, KiboCommerce runs a "resolution" process to determine which price list (and therefore which price) is the correct one to show them. This is controlled by a few key settings.
* **Customer Segments:** The primary method of targeting. A Price List can be assigned to one or more customer groups (e.g., "Wholesale Accounts"). When a user from that segment logs in, the price list is applied.
* **Resolution Rank:** An integer used to break ties. If a shopper belongs to two segments, each with a different price list, the list with the **lowest** rank number wins.
* **Default Price List:** A price list can be marked as the "default" for a site. This is the fallback price that is shown to anonymous visitors or any shopper who doesn't qualify for a more specific price list.
**Business Application Example:**
* **Scenario:** A shopper is in both the "Loyalty Club" (Rank 10) and "Email Subscribers" (Rank 20) segments. Because the "Loyalty Club" Price List has a lower rank, its prices will be shown to the customer, even if the other list also applies.
#### **2.4 Exclusivity: Using Price Lists for Product Entitlement**
The Exclusive setting transforms a Price List from a pricing tool into a powerful catalog visibility and entitlement engine. When a shopper resolves to a price list marked as Exclusive, they can **only** view and purchase the products explicitly defined in that price list (and its parents). All other products in the catalog become invisible to them.
This is a key feature for B2B commerce, as it allows you to define a complete commercial agreement—both the curated product assortment and the negotiated pricing—in a single place.
**Business Application Example:**
* **Industry:** Medical Device Manufacturer
* **Scenario:** The manufacturer has a large corporate client that is only permitted to purchase a specific set of 50 pre-approved devices. They create an Exclusive Price List named "Client ABC Contract," add only those 50 devices with their contract pricing, and assign it to the client's customer segment. When employees from Client ABC log in, the storefront transforms into a curated portal showing only the products they are entitled to buy, at the prices they are entitled to pay.
***
### **3. Functional Components & Configuration Deep Dive**
This section details every configurable attribute for Price Lists and the Price Entries within them.
#### **3.1 Price List Configuration**
These are the main settings that define a Price List's behavior.
| Name | Business Purpose | Available Options/Data Type | Concrete Example |
| :-------------------- | :--------------------------------------------------------------------------------------------------- | :-------------------------------- | :------------------------------------------------------------------------------------------------------- |
| **Name / Code** | Human-readable name and unique system identifier for the price list. | Text | Name: "Wholesale Tier 1", Code: "wholesale\_t1" |
| **Status** | Enables or disables the price list. | Active / Disabled | A disabled list is not applied but can still be inherited from by its children. |
| **Parent Price List** | Establishes an inheritance relationship with another price list. | Dropdown of existing price lists. | Setting "Wholesale Base" as the parent for the "Wholesale Tier 1" list. |
| **Exclusive** | Restricts a shopper's view to only the products contained within this price list. | Yes/No Toggle | Setting this to "Yes" for a B2B client's contract price list. |
| **Resolvable** | A master switch allowing a price list to be directly applied to a shopper. | Yes/No Toggle | Unchecking this for a parent list that only exists to be inherited from can improve performance. |
| **Resolution Rank** | An integer used to break ties when a shopper qualifies for multiple price lists (lower number wins). | Integer | Setting a "VIP" list to rank 5 and a "General Sale" list to rank 10 ensures VIPs always get their price. |
| **Default** | Designates the price list as the fallback for a site when no other list applies. | Yes/No Toggle | Setting the "Standard Retail Prices" list as the default for your main B2C site. |
#### **3.2 Price Entry Configuration**
Each line item within a Price List is a Price Entry, which contains the specific details of a price override.
##### **Conditions**
| Name | Business Purpose | Available Options/Data Type | Concrete Example |
| :------------------------ | :-------------------------------------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------------------------- |
| **Product** | The specific product (or variant) whose price is being overridden. | Product Selector | Selecting the "Pro-Grade Hiking Boots - Size 10" variant. |
| **Currency Code** | The currency for this specific price override. | Dropdown of ISO currency codes. | Setting the price in EUR for a European price list. |
| **Active Start/End Date** | Schedules the price entry to be effective only for a specific period. | Date/Time Pickers | Setting a sale price to be active from Friday at 9 AM to Sunday at 11 PM for a weekend flash sale. |
##### **Adjustments**
This section specifies which pricing values are being overridden. You can adjust one or more of the following:
| Attribute Name | Business Purpose | Concrete Example |
| :----------------- | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
| **Price** | Overrides the standard list price of the product. | Changing the base price from \$199 to \$189. |
| **Sale Price** | Overrides the sale price, often used to show a "slash-through" price on the storefront. | Setting a Sale Price of \$149 while leaving the list Price at \$199. |
| **MSRP** | Overrides the Manufacturer's Suggested Retail Price. | Adjusting the MSRP to comply with a manufacturer's policy. |
| **Cost** | Overrides the internal cost of the product for reporting purposes. | Updating the cost from \$50 to \$52 after a supplier price increase. |
| **MAP** | Overrides the Minimum Advertised Price. | Setting a MAP of \$179 to prevent the item from being sold below a certain threshold. |
| **Volume Pricing** | Allows you to set tiered pricing based on the quantity purchased. | Setting a price of \$10 each for 1-9 units, \$9 each for 10-49 units, and \$8 each for 50+ units. |
***
### **4. Key Capabilities and Business Applications**
This section details the practical value of the Price List system by exploring its core capabilities.
**Capability: Tiered B2B and Wholesale Pricing**
* **Functional Explanation:** The parent-child inheritance model allows for the efficient creation of complex, tiered pricing structures. A base price list can define standard wholesale pricing, and subsequent child price lists for different customer tiers (e.g., Gold, Platinum) only need to contain the specific price overrides for that tier, inheriting all other prices.
* **Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A distributor has three tiers of resellers. They create a base "Reseller" Price List. They then create a "Premier Reseller" list that inherits from the base list but overrides prices on 50 key products. Finally, they create a "Platinum Reseller" list that inherits from the "Premier" list, giving those top partners even deeper discounts on 10 specific items. This structure is easy to manage and ensures pricing is always applied correctly based on the reseller's tier.
**Capability: Automated, Time-Bound Promotions**
* **Functional Explanation:** Price entries can be scheduled with specific start and end dates. This allows a business to set up an entire promotion, such as a Black Friday sale, in advance. The promotional prices will automatically activate and deactivate at the scheduled times without any manual intervention.
* **Business Application Example:**
* **Industry:** DTC Brand
* **Scenario:** A DTC brand plans a 48-hour flash sale. A merchandiser creates a "Flash Sale" Price List and adds sale prices for 20 products. They schedule every price entry to activate at midnight on Friday and deactivate at 11:59 PM on Saturday. The sale runs automatically, and prices revert to normal after it ends, eliminating the need for staff to work overnight to manage the promotion.
**Capability: Curated B2B Purchasing Portals**
* **Functional Explanation:** The Exclusive setting is a powerful entitlement tool. When a Price List is marked as exclusive, any customer who resolves to it can only see and purchase the products contained within that list. This effectively transforms the public storefront into a private, curated catalog for that specific customer.
* **Business Application Example:**
* **Industry:** Marketplace Operator
* **Scenario:** A marketplace operator has a large corporate partner who wants a private portal for their employees to buy company-approved office supplies. The operator creates an Exclusive Price List containing only the 100 approved items, with the partner's negotiated contract pricing. When the partner's employees log in, they see a custom portal with only the products they are allowed to buy, simplifying their purchasing process and ensuring compliance with company policy.
**Capability: Subscription-Based Pricing**
* **Functional Explanation:** The pricing for subscription products and their recurring continuity orders is determined by Price Lists. A business can create specific price lists that define the recurring price for a product, which may be different from its one-time purchase price. A recommended best practice is to create an empty parent price list for all subscription-related price lists. This allows subscription-specific discounts to be tied to the parent list, ensuring they are inherited correctly by all child price lists that govern subscription pricing.
* **Business Application Example:**
* **Industry:** DTC Coffee Retailer
* **Scenario:** A coffee retailer wants to offer a "Subscribe & Save 15%" incentive. They create a "Coffee Subscribers" Price List. For their most popular coffee blend, which has a standard catalog price of \$20, they create a price entry in this list and set the Sale Price to \$17.00. This price list is applied to any customer who chooses the subscription option for that product, ensuring they receive the discounted price on their initial order and all subsequent recurring orders.
**Capability: Powering B2B Quote Negotiations**
* **Functional Explanation:** Price Lists serve as the starting point for the B2B quoting process. When a buyer or seller initiates a quote, the system automatically applies the B2B account's specific Price List to populate the initial item prices. This can be a price list assigned directly to the B2B account, which takes precedence, or a price list determined by the customer segments the account belongs to. From there, the seller can make manual adjustments to the pricing within the quote as part of the negotiation process with the buyer. If changes are made to the quote (like quantity or shipping), the system can re-evaluate the price list to ensure accuracy.
* **Business Application Example:**
* **Industry:** Manufacturing
* **Scenario:** A sales representative for a manufacturer creates a new quote for a long-standing B2B client. The client's account has a "Gold Tier Partner" Price List assigned to it. As the rep adds products to the quote, the prices are automatically filled in from this Gold Tier list. The client requests a quote for a very large quantity and asks for better pricing on a key component. The sales rep edits the quote, applies a manual percentage adjustment to that one line item, and submits the revised quote back to the client for approval, blending automated contract pricing with manual negotiation.
***
### **5. Platform Integration Map**
Price Lists are a transactional feature that integrates deeply with catalog, customer, and order data.
* **Upstream Dependencies:**
* **Catalogs & Products:** Price Lists are created within the context of a Master Catalog. Price entries can only be created for products that exist in that catalog.
* **Customer Segments:** To target price lists to specific groups of shoppers, Customer Segments must be created and populated first.
* **Sites:** A Price List can be set as the default for one or more Sites.
* **Downstream Impacts:**
* **Storefront Experience:** The resolved price list directly controls the prices a shopper sees on category and product pages. Exclusive price lists also control product visibility.
* **Cart & Checkout:** The prices of items added to the cart are determined by the active price list.
* **Order Management:** When an order is placed, the system records which price list was used. This information is visible on the order details and is important for financial reporting and customer service.
* **Search & Merchandizing:** Price can be used as a filter or sorting option. The price ranges displayed are based on the indexed, resolvable price lists.
* **Synergistic Features:**
* **Discounts:** While Price Lists set the base price, the KiboCommerce discount engine can apply further promotions on top of the price list price (unless explicitly restricted).
* **B2B Accounts:** The B2B account management feature allows you to group individual buyers under a corporate account, which can then be added to a Customer Segment to receive specific price list entitlements.
***
### **6. Real-World Example: Onboarding a New B2B Client**
Let's walk through an end-to-end scenario of a B2B distributor setting up a custom pricing and catalog experience for a new, high-value corporate client.
* **The Business:** "SupplyCore," a distributor of maintenance and repair parts, onboards a new national client, "MegaCorp." MegaCorp has negotiated special pricing and wants a simplified purchasing experience for its facility managers.
* Step 1: Creating the Customer Segment
The first action is to create a new Customer Segment in KiboCommerce called "MegaCorp Accounts." The account manager then adds all of MegaCorp's registered user accounts to this segment. This group will be the target for all special rules.
* Step 2: Building the Exclusive, Curated Price List
MegaCorp is only allowed to purchase from a list of 500 pre-approved parts. The SupplyCore pricing manager creates a new Price List named "MegaCorp Contract Pricing."
1. In the settings, they check the **Exclusive** box. This is the key step that will hide all other products.
2. They add 500 **Price Entries**, one for each approved part. In the adjustments for each entry, they input the specific, negotiated contract price for MegaCorp.
3. For 20 of the most frequently purchased items, they also configure **Volume Pricing**, offering deeper discounts for buying in bulk.
* Step 3: Assigning and Prioritizing the Price List
With the price list built, the manager assigns it to the "MegaCorp Accounts" Customer Segment. They also set the Resolution Rank to 5. This is a very high priority (a low number), ensuring that even if a MegaCorp user is also part of a general "Holiday Sale" segment (which might have a rank of 20), their specific contract pricing will always win and be applied.
* The Outcome:
When a MegaCorp facility manager logs into the SupplyCore website, their experience is completely transformed:
* The public catalog of 50,000 parts disappears. They can only search for and view the 500 parts on their exclusive price list.
* For every product they see, the price displayed is their unique, negotiated contract price.
* When they add one of the 20 key items to their cart, the price per unit automatically adjusts as they increase the quantity, reflecting the volume discount.
This provides a secure, compliant, and user-friendly purchasing portal for the B2B client, all managed by a single, powerful Price List.
### **7. Related Conceptual Guides**
For foundational knowledge and to understand the full impact of your pricing setup, refer to these related guides.
* [Catalog & Product Architecture](/concept-guides/catalog)
* Foundational Knowledge: The Catalog guide is a prerequisite. Price Lists are created within the context of a Master Catalog, and their price entries are applied to specific products defined in that catalog. You must have a product catalog before you can create pricing rules for it.
* Downstream Impacts: The Pricing concept directly impacts the visibility of the catalog. Using an "Exclusive" Price List will hide all products from a shopper except for those explicitly defined in the price list, effectively creating a private, entitled catalog.
* Complementary Strategies: The Catalog guide explains how to set a product's base price (e.g., in a specific currency for a Child Catalog), while this Pricing guide explains how to override that base price for specific customer segments. They work together to create complex, multi-layered pricing for B2B and international markets.
* [Search and Merchandizing](/concept-guides/search-and-merchandizing)
* Foundational Knowledge: This Pricing guide is a prerequisite for effective price-based merchandizing. The search engine indexes the prices from your "Resolvable" Price Lists, which is what powers the shopper's ability to filter and sort products by price on a category page.
* Downstream Impacts: Your Price List settings directly control the faceted search experience. The price ranges shown in the "Price" filter are based on the values from your indexed price lists. This also impacts merchandizing, as "Dynamic Realtime Categories" can be built using the final sale price you define in a Price List.
* Complementary Strategies: The two concepts work together to automate promotions. You can create a time-bound "Flash Sale" Price List to set temporary sale prices. A "Dynamic Realtime Category" (a merchandizing tool) can then be set to automatically find and display all products whose sale price is active, creating a "Sale" page that runs itself.
* [Promotions](/concept-guides/promotions)
* Foundational Knowledge: Pricing is the foundational step. The Price List determines the product's base price before any discounts are applied. The Promotions engine then runs and applies discounts (e.g., "10% off") on top of the price set by the Price List.
* Downstream Impacts: The Price List has a direct downstream impact: a price entry can be set to "Restrict Discounts." This setting will block the Promotions engine from applying any further order-level or item-level discounts to that specific product, which is often used to protect margins on already-low B2B contract prices.
* Complementary Strategies: These two systems work in tandem to create layered offers. For example, a "VIP" Price List can give a loyal customer segment a permanent 10% off. A "Weekend Sale" Promotion can then be layered on top, giving that customer an additional 15% off, resulting in a special, compounded discount that rewards loyalty.
# Promotions
Source: https://docs.kibocommerce.com/concept-guides/promotions
Apply conditional price adjustments using campaigns, discounts, and coupon sets
# **Kibo Commerce Conceptual Guide: Promotions**
See how to extend discounts with custom logic and configuration
## **1. Strategic Overview**
### **Concept Definition**
Promotions in Kibo Commerce are a comprehensive set of rule-based tools that apply conditional price adjustments to products and shipping, orchestrated through a hierarchical system of Campaigns, Discounts, and Coupon Sets.
### **Business Context**
The Promotions engine is a core marketing and sales capability within the Kibo Commerce unified platform. It is designed to provide business users with granular control over promotion strategies to drive conversions, increase order value and inventory turnover.
### **Value Drivers**
* **Increased Conversion and Acquisition**: Dynamically applying compelling offers at key moments in the customer journey is designed to reduce cart abandonment and attract new customers. By creating targeted discounts, businesses can create urgency and provide the necessary incentive to complete a purchase.
* **Higher Average Order Value (AOV)**: Structuring promotions with order-level thresholds (e.g., "Spend \$100, get 10% off") or "Buy More, Save More" logic incentivizes shoppers to add more items to their cart to meet the criteria for a better deal, directly contributing to a higher AOV.
* **Enhanced Margin Control & Inventory Management**: The platform allows for precisely targeting discounts to specific products, categories, or even individual product variants. This enables strategic price reductions to clear excess stock and promote high-margin items.
### **Scope Statement**
This guide provides an exhaustive conceptual overview of the Kibo Commerce Promotions engine. It covers the architecture, configuration, and business application of all native discount types, including stackable, variant-specific, and subscription-based promotions. It also details the platform's extensibility through custom attributes and external discount systems. This document explicitly excludes API implementation guides, focusing instead on the functional capabilities and their strategic business impact.
## **2. Core Concepts Explained**
### **What are Promotions? The Three-Part Architecture**
The promotions framework in Kibo Commerce is built on a three-tiered architecture that separates strategic planning from tactical execution and redemption control. This modular design provides both flexibility and power.
* **Campaigns**: At the highest level, a Campaign acts as a strategic container for a marketing initiative. It is defined by a start and end date and serves as an umbrella under which various activities are grouped. A single campaign can orchestrate not only price-based promotions (Discounts) but also corresponding changes to the storefront experience (Site Variations) and how products are sorted in search and category listings (Merchandizing Rules).
* **Discounts**: The Discount is the tactical rule engine of the promotions system. This is the core object where the specific logic of an offer is defined. A Discount specifies the conditions that a shopper or cart must meet, the products or shipping methods it targets, and the type of price reduction it applies (e.g., percentage off, fixed amount off, free shipping).
* **Coupon Sets**: This component serves as a distribution and redemption control mechanism. Coupon Sets are collections of single-use or multi-use codes that can be associated with one or more discounts. They enable businesses to create targeted offers for specific audiences, track the redemption of unique codes, and manage redemption limits.
### **Why does this Architecture matter?**
The separation of these components provides significant operational, financial, and customer experience benefits.
* **Operational Efficiency**: This architecture allows for a clear separation of concerns. A marketing team can schedule a "Back to School" Campaign and attach several pre-configured, reusable discounts like "20% off Backpacks" and "Free Shipping over \$50" without having to redefine the discount logic each time. This modularity streamlines the management of complex marketing calendars, as a library of tactical discounts can be built and deployed either as standalone, evergreen offers or as part of larger, coordinated, time-sensitive campaigns.
* **Financial Precision**: The platform's interaction rules with Price Lists and the granular control over discount stacking provide powerful tools to protect profit margins. By default, discounts do not apply to B2B or segment-specific pricing defined in a Price List, requiring a deliberate action to enable them. This prevents the accidental layering of a public promotion on top of an already negotiated contract price. Similarly, the discount stacking engine allows for controlled combinations of offers and ensuring profitability.
* **Superior Customer Experience**: The ability to create highly targeted and relevant offers enhances the shopping journey. For example, a business can offer a special discount to a "VIP" customer segment. The system can also automatically add a free gift to the cart when a condition is met, creating a delightful surprise for the shopper instead of requiring them to manually find and add the free item.
### **When to deploy Promotions?**
* **Business Triggers**: Common triggers for deploying promotions include seasonal campaigns (e.g., holidays), new product launches, efforts to clear end-of-life inventory, customer acquisition goals, or tactical responses to competitor pricing strategies.
* **Maturity Requirements**: Basic promotions, such as a site-wide percentage-off discount, can be configured and deployed immediately with minimal prerequisites. More advanced strategies require foundational data to be in place. For instance, leveraging Discount Extensibility to target customers based on their loyalty tier requires that customer attributes for loyalty tiers are already defined and populated within the platform.
* **Timeline to Value**: Simple, standalone discounts can be created, configured, and activated in minutes, providing immediate value. More complex, multi-layered campaigns that involve coordinating discounts with site variations and merchandizing rules may require more planning but deliver a more cohesive and impactful customer experience that can drive higher engagement and sales over the campaign's duration.
### **The Discount Application Lifecycle: Conditions, Targets, and Effects**
Every promotion within Kibo Commerce is built upon a consistent and logical abstraction model that breaks the offer down into three fundamental components. Understanding this model is key to unlocking the full creative potential of the promotion engine.
* **Conditions:** These are the "if" statements of a promotion. Conditions define the criteria that a shopper's cart, session, or customer profile must satisfy before a discount becomes eligible for application. The platform offers a wide range of conditions, from simple order-level thresholds (e.g., the pre-discounted order total must exceed \$50) to complex product-based rules (e.g., the shopper must purchase at least three items from the "Clothing" category).
* **Targets:** Once the conditions are met, the "what" of the promotion is defined by its Target Criteria. The target specifies which precise items, categories, or charges the discount will modify. The target can be the same product that fulfilled the condition (as in a "Buy One, Get One" scenario) or an entirely different product or charge (as in a "Buy a laptop, get 50% off a printer" scenario).
* **Promotion Application:** This defines the "how" of the promotion, the actual calculation applied to the target's price. The type of application chosen determines what the shopper experiences. For example, on a \$50 item, a Percentage type discount of 10% will drop the price to \$45, whereas an Amount type discount of \$10 will drop it to \$40. The platform supports several application types, including Percentage, Amount, Free, Fixed Price, and Auto-Add Free Product.
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
A discount is a complex entity configured through a series of dedicated sections within the Kibo Commerce Admin UI. Each section controls a distinct aspect of the discount's logic and behavior, allowing for granular control over its application.
* **General Settings:** This section defines the fundamental nature of the discount. Here, users set its internal name and code, its active date range, and its core operational logic: whether it Applies To a Line Item or the entire Order; whether it Affects the Product cost or the Shipping cost; and its calculation Type (e.g., Percentage, Amount, Free).
* **Discount Conditions:** This is where the purchase requirements that trigger the discount are established. For order-level discounts, this includes setting minimum order values or quantities. For item-level discounts, it involves specifying the products or categories that must be purchased to qualify.
* **Target Criteria:** Once the conditions are met, this section specifies which products, categories, or shipping methods are eligible to receive the discount. It includes settings for defining the scope of eligible products and excluding specific items or categories from the promotion.
* **Attribute Conditions (Extensibility):** This advanced section allows for the creation of conditions based on custom data. It leverages attributes attached to customers, B2B accounts, orders, or fulfillment locations to enable highly targeted and personalized promotions.
* **Discount Limitations:** This component provides essential guardrails to control the discount's usage and financial impact. It includes settings for requiring coupon codes, setting maximum redemption counts per order or per customer, and defining a maximum monetary value for the discount.
### **Configuration-Level Deep Dive**
The following table provides an exhaustive reference for the key configurable fields within the discount editor. Each attribute represents a specific business decision, and understanding its purpose and impact is important for designing effective and profitable promotions.
**1. General Section Fields**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :-------------------- | :----------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| Enable/Disable Toggle | Controls the immediate operational status of the discount. | Enabled: The discount is active, subject to its Start/End dates. Disabled: The discount is inactive, even if its dates are current. | A merchandiser disables the "SpringSale" discount on its End Date to manually stop it. |
| Name | Provides a human-readable identifier for the discount in the Admin UI. | This name is used for internal organization, reporting, and searching. It is not shopper-facing. | The discount is named "VIP Holiday Sale 2024" for easy reference by the marketing team. |
| Start Date | Defines the exact date and time a promotion becomes active. | Allows for scheduling. If left blank, the discount is "evergreen" and starts as soon as it's enabled. | A "Black Friday Sale" is set to start on November 28th at 12:01 AM. |
| End Date | Defines the exact date and time a promotion automatically deactivates. | Creates urgency for time-boxed sales. If left blank, the discount will run indefinitely until manually disabled. | A "Flash Sale" is set to end just two hours after its start time. |
| Applies To | Specifies the level of the purchase (the "target") to which the discount is applied. | Line Item: Applies the discount to specific item(s) in the cart. This is required for product-specific promotion. Order: Applies the discount to the subtotal of all items in the order. | A "10% off your entire purchase" promo is set to "Order," while a "BOGO Free on Shirts" promo is set to "Line Item." |
| Affects | Specifies which charge the discount value will be subtracted from. | Product: Applies the discount to the cost of the product(s). Shipping: Applies the discount to the cost of shipping. | A "Free Shipping" promo is set to "Shipping," while a "20% Off" promo is set to "Product." |
| Type | Defines the kind of reduction the discount offers | Percentage (%): Reduces the cost by a percentage (e.g., 20% off). Amount: Reduces the cost by a fixed currency value (e.g., \$10 off). Free: Makes the affected item(s) free (e.g., Free Shipping or a BOGO product). Fixed Price: Reduces the cost of an item or shipping to a specific price (e.g., "\$5 Shipping") | A "10% off" promo uses "Percentage," a "\$5 off" promo uses "Amount," and a "BOGO Free" promo uses "Free." |
| Stackable | Controls whether this discount can be combined with other stackable discounts. | Enabling this allows for layered promotions but requires careful assignment to a Layer (1, 2, or 3) to prevent margin erosion. Only visible if stackable discounts are enabled under Discount Settings. | A "10% off" site-wide sale and a "Free Shipping" offer are both marked as Stackable. |
#### **2. Discount Conditions (Pre-conditions)**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :------------------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| Minimum Order Amount | Sets a minimum purchase amount (pre-discount) the order must meet to qualify. | A primary tool for increasing Average Order Value (AOV). | A "Free Shipping" discount is configured with a Minimum Order Amount of \$50. |
| Maximum Order Amount | Sets a maximum purchase amount the order must *not* exceed to qualify. | Used for specific scenarios, like "Save \$10 on orders *under* \$50" to target smaller carts. | A "Small Order Bonus" discount is set with a Maximum Order Amount of \$49.99. |
| Total Order Quantity | Requires a minimum number of *total items* in the cart to qualify. | Encourages purchasing multiple items, regardless of their individual value. Visible only for Order Level discounts. | A "Buy 3, Get 10% Off" discount sets Total Order Quantity to 3. |
#### **3. Target Criteria (Post-conditions)**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| Scope (Specific/All) | The "Get Y" part of a deal. Defines the pool of eligible items: All products, Specific Products, or Specific Categories. | This is the primary targeting mechanism for Line Item discounts. | For a "20% off all shoes" discount, the Scope is set to Specific Categories and "Shoes" is selected. |
| Shipping Method | Restricts a shipping discount to apply only to specific methods (e.g., "Ground"). | Allows for targeted shipping promotions, like "Free Ground Shipping" without discounting "Next Day Air". Visible only when Affects is Shipping | A "Free Economy Shipping" discount selects only the "Ground" and "Economy" Shipping Methods. |
####
#### **4. Message Conditions**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
| Include Threshold Message | Master toggle to enable shopper-facing messages | This feature is used to "upsell" shoppers to meet a discount threshold. It may require theme modifications to display. Requires Minimum Order Amount (Order Level). | A discount for "Free Shipping over \$50" enables this message. |
| Threshold Value | The cart value at which to *start* showing the message. | Must be set *lower* than the Minimum Order Amount to notify shoppers they are *close* to qualifying. Requires Minimum Order Amount (Order Level). | For a "Free Shipping at \$50" discount, the Threshold Value is set to \$40. |
| Message Text | The text content of the message shown to the shopper. | This is the actual marketing copy the shopper will see. | "You are only away from free shipping!"(where is the remaining amount) |
####
####
#### **6. Discount Limitations**
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :----------------------------- | :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
| Max Discount Value (Per Order) | Limits the total currency value this discount can provide to a single order. | Used to cap high-percentage sales. E.g., a "40% off" promo with a \$100 limit will stop discounting after \$250 of qualifying goods. | A "BOGO 50% Off" discount sets this to \$100, so a shopper can't get more than \$100 off in one order. |
| Total Redemptions | Limits the total number of times the discount can be used across all orders | Used for "First 100 shoppers" promos. Requires shopper to be logged in. For guests, this must be set on the Coupon Set. | A "New Product Launch" discount is limited to 500 Total Redemptions. |
| Max Redemptions (Per Order) | Limits the number of times a discount can be redeemed within a single order. | Used for "Buy 2, Get 1 Free" type deals. If set to 1, only one item (the most expensive qualifying item) gets the discount.Only visible for Line Item discounts. | A "Buy 1, Get 1" deal has this set to 1; a "Buy 4, Get 2" deal would set this to 2. |
### **Promotion Type and Scope Matrix**
The combination of a discount's Type, Applies To (Scope), and Affects attributes determines its fundamental behavior. This matrix clarifies the supported primary configurations.
| Applies To | Affects | Percentage | Amount | Free | Fixed Price | Auto-Add Free Product |
| :--------- | :------- | :--------- | :----- | :--- | :---------- | :-------------------- |
| Line Item | Product | Yes | Yes | Yes | Yes | Yes |
| Line Item | Shipping | Yes | Yes | Yes | Yes | No |
| Order | Product | Yes | Yes | No | No | No |
| Order | Shipping | Yes | Yes | Yes | Yes | No |
*Note: When Affects is set to Shipping, the Target Criteria section will require specifying the eligible Shipping Methods or Shipping Zones for the discount to apply.*
## **4. Key Capabilities and Business Applications**
The Kibo Commerce promotions engine provides a range of distinct capabilities that address common and complex e-commerce scenarios.
### **Capability: Stacking Tiered Discounts for Loyalty Programs**
* **Functional Explanation**: Using the Stackable toggle and Discount Layer settings, a business can create multiple discounts that apply sequentially to an order. The system automatically optimizes the application order of discounts *within* the same layer to provide the best deal for the customer. The order value is then recalculated before applying discounts from the next layer. This allows for building complex, multi-level promotions.
* **Business Application Example**:
* **Industry**: Fashion & Apparel Retailer
* **Scenario**: To reward loyalty, a retailer creates two stackable promotions: a site-wide "20% off all Dresses" discount assigned to Layer 1, and a "VIP Members get an additional 10% off their entire order" discount assigned to Layer 2. A VIP member adds a \$100 dress to their cart. The system first applies the Layer 1 discount, reducing the item price to \$80. It then recalculates the order subtotal and applies the Layer 2 discount, for a final price of \$72. This layered approach creates a clear, enhanced value proposition for top customers, resulting in higher loyalty and repeat purchases.
### **Capability: Hyper-Targeting with Custom Business Attributes**
* **Functional Explanation**: The Discount Extensibility feature allows custom attributes from B2B Accounts, Customers or Orders to be used as conditions for a discount. After enabling the "Available for Discounts" toggle on a custom attribute, it becomes available in the discount rule builder, allowing for the creation of highly specific and targeted promotions.
* **Business Application Example**:
* **Industry**: B2B Industrial Distributor
* **Scenario**: A distributor wants to offer a special shipping discount to its highest-value clients. They have a custom attribute on their B2B Account object called AccountTier. They create a new shipping discount for "Free Freight Shipping" and add an Attribute Condition: B2B Attribute AccountTier is "Gold". Now, only logged-in users associated with a "Gold" tier account will be eligible for this promotion, automating a key benefit of their partner program and strengthening B2B relationships.
### **Capability: Orchestrating a Themed Sale with Coordinated Content**
* **Functional Explanation**: Using a Campaign, a business can schedule a discount to run concurrently with Site Variations. This capability allows for specific, themed versions of pages (like the homepage or category pages) to be automatically displayed only for the duration of the campaign, creating a fully immersive promotional event.
* **Business Application Example**:
* **Industry**: Direct-to-Consumer (DTC) Brand
* **Scenario**: A DTC coffee brand launches a "Summer Brews" campaign. They create a campaign scheduled for July 1-31. Within this campaign, they attach a "15% off Cold Brew Products" discount and a site variation for the homepage that features summer-themed imagery and messaging. When July 1st arrives, the homepage automatically updates to the summer theme and the discount becomes active simultaneously. This creates a cohesive and professional marketing event that automatically reverts to normal once the campaign ends, improving customer engagement without manual intervention.
## **5. Platform Integration Map**
### **Upstream Dependencies**
Successful promotion configuration relies on several other core platform components being in place first.
* **Catalog & Products:** Discounts are fundamentally tied to a catalog and its constituent products and categories. A product must exist in the catalog with a defined price before it can be targeted by a discount. For variant-specific discounts, the product must be configured with its specific variant options (e.g., size, color).
* **Custom Attributes:** To create targeted promotions using Discount Extensibility, the relevant custom attributes must first be defined on customer, B2B account, location or order records and be made available for discounts.
### **Downstream Impacts**
The application of a promotion has direct consequences for several downstream systems and processes.
* **Cart & Checkout:** This is the primary point of impact, where the promotion engine evaluates cart contents against active discount conditions and calculates the final, discounted prices for the shopper to review before payment.
* **Orders:** Once a purchase is complete, the applied discounts are permanently recorded on the final order object. This data is important for fulfillment, financial reconciliation, and customer service.
* **Quotes (B2B)**: Promotions and coupons can be applied to B2B quotes during the negotiation process. The platform treats the application of a promotion not as a final, immutable event, but as a dynamic state. The system is designed to re-price the quote and re-evaluate all applicable discounts whenever a change is made—such as an item quantity adjustment or a shipping address change. This means the promotion engine remains active throughout the B2B negotiation lifecycle, ensuring pricing accuracy as the quote evolves
### **Synergistic Features**
Promotions achieve their greatest strategic value when used in combination with other complementary platform features.
* **Promotions + Price Lists**: This combination is the core of any sophisticated, segmented pricing strategy. A business can use Price Lists to set the unique base price for a B2B account, then layer targeted, stackable promotions on top for special offers, ensuring the additional discount applies only when explicitly intended.
##
## **6. Related Conceptual Guides**
To fully leverage the capabilities described in this guide, a comprehensive understanding of related platform concepts is recommended.
### **For foundational knowledge, refer to:**
* **[Catalog](/concept-guides/catalog)**: Promotions are targeted at products and categories; a firm grasp of catalog structure is a prerequisite for building effective discount rules.
* **[Pricing](/concept-guides/pricing)**: This guide is a prerequisite for comprehending how Kibo Commerce handles complex B2B and segmented pricing, and how discounts must be configured to interact with these custom price overrides
### **To understand downstream impacts, refer to:**
* **[Fulfillment](/concept-guides/fulfillment)**: This guide explains how applied discounts are stored and represented on a finalized order record, which is important for reporting and analysis.
* **[Cart & Checkout](/concept-guides/cart-and-checkout):** This guide details the B2B quoting lifecycle and explains how promotions are applied and dynamically re-evaluated during the negotiation process
### **For complementary strategies, refer to:**
* **[Catalog](/concept-guides/catalog)**: This guide details how to create promotions that target specific product variants (e.g., a specific color or size) rather than just the base product.
* **[Location Admin](/developer-guides/location-admin)** and **[Location Groups](/developer-guides/location-group)**: These guides provide the context for creating the custom data fields (including location attributes) that can be used for advanced promotion targeting via the Discount Extensibility feature.
# Returns & Reverse Logistics
Source: https://docs.kibocommerce.com/concept-guides/returns-and-reverse-logistics
Manage product returns from initiation through physical movement and financial resolution
# **Kibo Commerce Platform Conceptual Guide: Returns & Reverse Logistics**
Learn how to build and manage reverse logistics strategies and scenarios
### **1. Strategic Overview**
**Concept Definition:** Returns and reverse logistics is the comprehensive process that manages the initiation, physical movement, and financial resolution of products being returned from a customer back to a business.
**Business Context:** In enterprise e-commerce, the return process is an important extension of the customer journey, not merely a transactional reversal. A flexible and efficient returns capability is essential for building customer trust, ensuring operational agility, and maintaining financial integrity across omnichannel operations.
**Value Drivers:**
* **Enhanced Customer Loyalty:** A clear and flexible returns process builds trust and provides a frictionless post-purchase experience, encouraging repeat business.
* **Improved Operational Efficiency:** Automation and intelligent routing within the returns process reduce manual overhead, optimize resource allocation, and accelerate the restocking or disposition of returned goods.
* **Strengthened Financial Control:** Accurate and transparent refund calculations, combined with optimized product disposition, help businesses protect profit margins and recover value from returned inventory.
**Scope Statement:** This guide explains the core functional components and business applications of the Kibo Commerce platform's return and reverse logistics capabilities. It covers the end-to-end return process flow, return rule configuration, product disposition logic, refund calculations, and the various options for return resolution. This guide does not cover the technical implementation details, APIs, or specific integration requirements with third-party logistics (3PL) providers.
***
### **2. Core Concepts Explained**
**What is Returns and Reverse Logistics?**
Return and reverse logistics, within the Kibo Commerce platform, is a comprehensive suite of tools that enables businesses to manage the entire lifecycle of a product return. It begins with the customer's request and follows the item through physical transit, warehouse processing, condition assessment, intelligent disposition routing, and final financial resolution. This system integrates with other platform components, such as order management, inventory, fulfillment, and order routing, to ensure a cohesive and automated workflow that maximizes value recovery
**Why does Return and Reverse Logistics matter?**
A well-defined returns process is important for several reasons. Operationally, it reduces the complexity of handling returned goods, minimizing the time and effort required from customer service and warehouse staff through automated status management and intelligent routing. Financially, it allows businesses to recover maximum value from returned products by facilitating their re-entry into sellable inventory or by guiding them toward the most profitable disposition path based on condition assessment, thereby protecting the bottom line. From a customer experience perspective, a seamless and transparent returns process with real-time status tracking reduces friction, addresses post-purchase concerns, and serves as a significant factor in driving customer retention and loyalty.
**Business Triggers:** Businesses typically implement and optimize returns management capabilities when they experience scaling challenges in return volume, need to standardize return policies across multiple sales channels, or want to automate manual return processes that are consuming customer service resources. Advanced return capabilities become essential when businesses operate across multiple fulfillment locations and need sophisticated disposition workflows to maximize value recovery
The lifecycle of a return in the Kibo Commerce platform follows a sequential flow, ensuring all steps are tracked and resolved efficiently.
1. **Initiation:** A customer initiates a return request, typically through a self-service portal or by contacting customer support. The system validates the request against pre-configured business rules, including return eligibility, return window compliance, product-specific restrictions, and customer segment policies.
2. **Authorization:** Once validated, the system creates a return record and transitions it to authorized status.
3. **Physical Return:** The customer ships the product back to a designated return location. This step involves the physical movement of the item, which is tracked until it is received by the business.
4. **Inspection and Processing:** Upon arrival, the product undergoes inspection where warehouse staff verifies item condition, quantity, and completeness against the original return request. The system supports condition categorization (Good, Bad, Refurbished) for intelligent disposition routing.
5. **Disposition:** Based on the inspection, the system or staff updates the product's status and determines its final disposition. The item can be restocked to inventory, designated for refurbishment, or flagged for liquidation or disposal.
6. **Financial Resolution:** The final step involves a financial action. A full or partial refund is issued to the customer, or a replacement order is created. The system automatically processes the refund based on the original order and any applied promotions or fees.
***
### **3. Functional Components & Configuration Deep Dive**
**3.1 Component Architecture:**
1. **Return Settings:** This component enables businesses to configure fundamental return behaviors including default return processing fees, return shipping addresses, refund preferences for shipping and handling charges, gift card refund options, and automatic inventory adjustments upon restocking. These settings provide operational flexibility for tailoring the return experience to business requirements and financial policies.
2. **Return Rules Configuration:** A comprehensive component that applies sophisticated business logic to return requests, controlling eligibility based on product criteria, customer segments, return windows, and quantity limits. Rules support expression-based conditions with logical operators and can be ranked for prioritization across multiple scenarios.
3. **Return Status Management:** This component tracks the complete return lifecycle through defined states (Created, Authorized, Received, Closed, Cancelled, Rejected) and provides comprehensive visibility into return progress and completion rates.
4. **Routing Logic:** This component determines optimal destinations for physical returns by analyzing factors like customer geographic location, item condition requirements, and location capabilities to minimize transit time and cost while maximizing processing efficiency. The system determines optimal return destinations and provides disposition capability that routes items to appropriate final destinations based on condition assessment and business rules.
5. **Return Email Configuration:** This component manages automated customer communications throughout the return lifecycle, with configurable email notifications for return creation, authorization, rejection, updates, and closure. This ensures consistent customer communication and reduces manual support overhead.
**3.2 Business Configuration Deep Dive:**
This consolidated table highlights the most important, high-level settings that determine how returns are processed and how the system operationally manages the reverse logistics workflow.
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Return Rules** | Defines the actual return policy rules (e.g., returnable/not returnable, return window, max quantity) using underlying product criteria and customer criteria. | Ensures consistency in return authorization across all channels, controlling the return window and setting maximum quantity limits. | The Retailer sets the return policy to allow returns of electronic items only for Gold-Tier Customers and limits the return quantity to a maximum of 5 units per transaction. |
| **Update On Hand Inventory on Return Restock** | Controls whether the returned item is immediately added to available inventory upon being marked as "received." | Allows the business to control inventory updates on restock. | The setting is disabled, so the item is received, but the quantity is not added to the stock count. |
| **Refund Shipping and Handling** | Configures whether the original shipping and handling charges paid by the customer are included in the return refund amount. | Refunding these fees significantly improves customer satisfaction but increases the total cost of the return to the business. | The Retailer enables this setting, ensuring the customer receives a full refund, including the \$5.99 they paid for the original order's shipping. |
| **Default Return Processing Fee** | Establishes the standard, non-refundable cost deducted from the customer's refund for processing a return. | Serves as a baseline mechanism for recovering processing costs. Its presence may deter discretionary returns. | The Retailer sets the fee to \$5.00, which is deducted from the refund issued, covering basic processing costs |
| **Return Attribute Settings** | Allows the business to configure custom fields to collect information related to return. | Enables strategic data collection that supports processing and provides specialized data for business intelligence reporting on return causes. | The Retailer defines a "Quality Issue Code" (custom field) on the return to directly inform the product team about specific defect trends. |
| **Email Notification Configuration** | Controls customer communications throughout the return lifecycle. | Communications reduce customer service inquiries and improve transparency but must be carefully configured to avoid overwhelming customers. | A retailer enables email notifications for return creation and closure to keep customers informed of key milestones. |
***
### **4. Key Capabilities and Business Applications**
**Capability: Refund vs. Replace Options:**
**Functional Explanation:** The system supports line-item level flexibility, allowing you to apply different resolution types to specific items within the same return. Replace functionality enables shipping replacement products to the shopper, where a new order for the replacement item is created in a paid state, then routed and fulfilled. Refund functionality enables issuing full or partial payment refunds at the line-item level.
Note that replacements are only supported for eCommerce implementations or Order Management-Only implementations that include a catalog. If your OMS-Only implementation does not have a catalog, you will not be able to offer replacements.
**Business Application Example:**
* A contractor orders a complete tool set containing a drill, saw, and measuring tape for a construction project. Upon delivery, the drill arrives damaged, and the saw is the wrong model. Using the flexible resolution options, the customer service representative selects "replace" for the damaged drill to ensure quick project continuity, and chooses "refund" for the wrong saw. This line-item level flexibility allows the retailer to provide optimal resolution for each item within a single return, maintaining customer satisfaction while managing inventory efficiently.
**Capability: Advanced Return Rules**
**Functional Explanation:** This capability enables businesses to create sophisticated, expression-based return policies that automatically enforce complex business logic. Rules can be built using product criteria (type, code, variant, category), customer criteria (segments, customer account) .The system supports rule ranking for prioritization, testing functionality for validation, and override capabilities for customer service representatives when business circumstances warrant exceptions.
**Business Application Example:**
* A consumer electronics retailer sells a limited edition smartwatch. To protect the exclusivity of this product, they create a return rule specifying that the smartwatch is non-returnable once purchased. The rule applies to all units of the limited edition smartwatch, ensuring that customers cannot return the item.
* A Direct-to-Consumer (DTC) brand is launching a new line of electronic headphones. To drive initial adoption and reward their most loyal customers, they create a special return rule. This rule applies to the specific product (the new headphones) and is only active for customers within the "VIP" customer segment. For this group, they extend the return window to 90 days.
**Capability: Intelligent Return Location Assignment:**
**Functional Explanation:** The platform determines the most suitable location for returned items through intelligent analysis of multiple factors including customer geographic location, item characteristics and location capabilities. Return locations represent physical destinations such as central warehouses, regional distribution centers, or retail stores where returned items are received. This optimization reduces shipping costs, accelerates return handling, and ensures items reach facilities best equipped for their specific requirements.
**Business Application Example:**
* **Industry:** Fashion & Apparel Retailer (Omnichannel)
* **Scenario:** A customer in Los Angeles initiates a return for designer shoes purchased online. The retailer operates fulfillment centers in California and New Jersey, plus retail stores capable of handling returns. When Reverse Logistics is enabled, the system's intelligent routing evaluates multiple that meet the individual business needs like: customer proximity, and item handling requirements. It determines that the California fulfillment center provides optimal logistics efficiency, automatically generating return instructions that direct the customer to ship items to that specific location.
**Capability: Receiving Returns Package**
**Functional Explanation:** This capability manages the physical receipt and condition assessment of returned items at fulfillment locations. The system supports both standard receiving workflows for detailed item-by-item processing and quick receiving options for efficient bulk handling. During receipt, warehouse staff can assess item conditions, determine restocking eligibility, and trigger appropriate disposition workflows based on the item's assessed state.
**Business Application Example:**
A retailer receives a package containing multiple returned fitness equipment items. Using the standard receiving process, warehouse staff individually verify each item against the return request: confirming a resistance band quantity of 1, exercise weights quantity of 2, and a yoga mat quantity of 1.
**Capability: Intelligent Disposition Location Assignment**
**Functional Explanation:** This capability enables businesses to design and automate condition-based disposition workflows that optimize value recovery from returned items. The system supports multiple conditions (Good, Bad, Refurbished) and automatically routes products to appropriate destinations: immediate restocking for sellable items, refurbishment facilities for repairable goods, liquidation channels for discounted sales, or disposal for unsellable items. This automation reduces manual handling, and maximizes financial recovery.
**Business Application Example:**
* **Industry:** Direct-to-Consumer (DTC) Brand
* **Scenario:** A DTC home goods brand receives a returned blender. The warehouse staff inspects the product and notes that the box is slightly damaged, but the blender itself is in perfect condition. According to the brand's pre-configured disposition workflow, items with damaged packaging but perfect internal condition are automatically routed to a "secondary sales" or "liquidation" inventory location. This ensures the product does not get restocked as new, preventing customer dissatisfaction with a damaged box, while also recovering value through a secondary sales channel, which helps to minimize waste and maximize the value recovered from returned goods.
### **Capability: Return Label Generation**
**Functional Explanation:** This capability automatically generates return labels that include all necessary shipping information, return location details, and tracking capabilities that integrate with carrier systems for seamless return logistics management and customer convenience.
**Business Application Example:**
* A customer initiates a return for a kitchen appliance through the retailer's website. The system automatically generates a return label directing the return to the appropriate fulfillment center based on the customer's location and the location's capacity to handle large items. The customer receives the prepaid label via email with clear return instructions, enabling a straightforward return experience.
### **Capability: Comprehensive Return Status Management**
**Functional Explanation:** This capability provides complete visibility into return lifecycle progression through standardized status tracking. The system manages return states including Created , Authorized, Closed , Rejected and Cancelled. The system also provides refund status tracking (fully/partially refunded) for comprehensive operational visibility.
**Business Application Example:**
* A customer returns a defective tennis racket that was purchased as part of a promotional bundle. The return moves through status progression: Created when initiated by customer service, Authorized after validation, Received when the warehouse confirms receipt, and finally Closed when the refund is processed. The refund status shows "Fully Refunded" once the complete amount is credited back to the customer's original payment method, providing clear operational visibility for customer service inquiries.
**Capability: Return Attributes for Custom Data**
**Functional Explanation:** Allows the business to define custom fields to collect information related to return.
**Business Application Example:**
* A retailer needs to link returns to internal loyalty programs and customer risk factors. They define a custom field to track the "Customer Loyalty Tier" and another to track a "Fraud Risk Score." This specialized data is then used in automation rules to quickly process returns for loyal customers while flagging high-risk returns for detailed manual review.
**Capability: Return Email Configuration**
**Functional Explanation:** This capability enables businesses to configure automated email communications throughout the return lifecycle, ensuring customers receive timely updates about their return status. The system supports configurable email notifications for key milestones including return creation, authorization, rejection, updates, and closure. This automated communication reduces customer service overhead while maintaining transparency and customer satisfaction throughout the return process.
**Business Application Example:**
* A customer initiates a return for a defective tablet. The email configuration triggers a series of communications: a "Created" email confirming receipt of the request, an "Authorized" email when the return is approved, an "Updated" email when any changes occur to the return, and finally a "Closed" email when the refund is processed. This communication sequence keeps the customer informed at every step and reduces customer service inquiries about return status.
**Capability: Flexible Refund Management**
**Functional Explanation:** The platform provides flexibility in handling refunds through both manual and automated processes. For manual refunds, administrators can use a comprehensive refund calculator within the UI to determine the exact refund amount. This accounts for various factors, such as the quantity of returned items, return processing fees, shipping and handling charges, and the payment source for issuing the refund, giving administrators full control to ensure the correct amount is refunded to the appropriate payment method. For automated return refunds, the system calculates the refund based on the original transaction details, ensuring consistency and accuracy while reducing the risk of errors and improving operational efficiency.
**Business Application Example:**
* A customer purchased three units of a high-end Bluetooth speaker during a promotional sale. One of the speakers was damaged during shipping and the customer wants to return only that unit.Using the manual refund option\*\*,\*\* the system calculates the refund amount, taking into account the quantity of the returned item, the applicable shipping and handling fees, return processing charges, and any duties or taxes paid. The administrator can then adjust the calculated refund amount if needed and choose the appropriate payment method to ensure the refund is issued to the correct source (credit card, store credit, etc.). Once the refund is processed, the customer receives a detailed breakdown, ensuring transparency on how the refund was calculated and the exact amount returned.This process minimizes errors and allows the retailer to maintain control over each step of the refund process, making it both accurate and efficient.
**Capability: Credits and Refunds Without Returns**
**Functional Explanation:** You don't always have to open a return case to fix accounting issues. Credit and refund actions are available on the order after payment has been captured. The key distinction between credits and refunds is that credits affect the order balance, whereas refunds do not.
* Use [credits](/pages/payment-actions#credit-a-payment) to fix accounting issues by returning money to the customer and reducing the order balance.
* Use refunds to provide appeasements by giving money to the customer without changing the accounting and order balance.
If you choose to provide a refund without creating a return, you can perform it via a [manual refund](/pages/payment-actions#issue-a-refund) through the payment actions of the Order Admin UI, where you specify the exact amount of money you want to refund.
Both manual and automatic refunds can be refunded to a gift card. When performing an automatic refund through a return, the system will always generate a new gift card and email the card information to the customer instead of refunding back to the original gift card. However, a manual refund can either refund back to the existing gift card used for the order payment or to a new gift card depending on which behavior is selected [in the payment settings](/pages/gateway-gift-cards#enable-gift-cards-as-a-payment-method).
**Business Application Example:**
* A customer contacts support about a minor issue with their order but does not want to return the product. The customer service representative uses the manual refund option to issue an appeasement refund directly from the order without creating a return case, providing a quick resolution that maintains customer satisfaction while avoiding unnecessary logistics overhead.
***
### **5. Platform Integration Map**
**Upstream Dependencies:**
* **Order Data:** The return process relies on original order details, such as line items, pricing, discounts, taxes, and shipping information, to validate the return request and calculate the refund accurately.
* **Product Data:** Product-level information helps apply business rules, determine return eligibility, and manage product disposition.
* **Customer Data:** Customer data like customer segmentation help apply personalized return policies.
**Downstream Impacts:**
* **Inventory Management:** Returns directly affect inventory. Restocked items are added back to inventory, while liquidated or non-sellable items are separated.
* **Warehouse & Logistics Operations:** Return location logic, disposition workflows, and inventory tracking systems guide efficient handling of returned products in fulfillment centers or warehouses.
**Synergistic Features:**
* **Customer Accounts:** By connecting with customer accounts, the returns process allows customers to independently initiate returns, track their status, and access their return history. This empowers customers to manage their returns without needing support, improving efficiency..
* **Order Management:** The returns process integrates with order management, enabling seamless transitions between order creation, fulfillment, return authorization, and resolution. This ensures a unified view of all order and return-related activities across systems.
* **Routing:** Integration with routing intelligence optimizes return destination selection, disposition location routing, and replacement order fulfillment, ensuring efficient logistics operations and cost optimization across the reverse supply chain.
***
### **6. Related Guides**
* **For foundational knowledge, refer to:**
* **[Location Admin](/developer-guides/location-admin)** and **[Location Groups](/developer-guides/location-group):** These guides cover the physical location framework that underpins return routing, location selection, and disposition workflows, providing essential context for understanding return logistics operations.
* **[Return Rules](/pages/return-rules):** Configure custom return policies that enforce whether items are returnable, return quantity limits based on product or customer criteria, and the eligible return window.
* **To understand downstream impacts, refer to:**
* **[Order Routing](/concept-guides/order-routing):** This guide outlines how returns are integrated into the broader order management and routing workflows, ensuring returns are efficiently routed and processed.
* **For complementary strategies, refer to:**
* **[Payments](/concept-guides/payments):** This guide covers how refunds and replacements interact with the payment system, ensuring consistency in transaction reconciliation.
* **For operational guides, refer to:**
* **[Fulfiller UI Returns](/pages/fulfiller-ui-overview):** Learn how to manage returns in the Fulfiller UI.
* **[Refund a Return](/pages/refund-a-return):** Step-by-step guide for initiating return refunds where the system automatically calculates the appropriate amount.
# Search and Merchandizing
Source: https://docs.kibocommerce.com/concept-guides/search-and-merchandizing
Control product discovery, relevancy ranking, and strategic product presentation
# **Conceptual Guide: Search and Merchandizing**
## **1. Strategic Overview**
### **Concept Definition**
Search and Merchandizing is the unified Kibo Commerce capability for controlling product discovery, relevancy ranking, and the strategic presentation of products to shoppers.
### **Business Context**
This capability serves as the core engine that transforms a static product catalog into a dynamic, responsive, and curated shopping experience. It governs how shoppers find, filter, and interact with products, directly influencing the effectiveness of the conversion funnel and the overall success of the customer journey.
### **Value Drivers**
* **Enhanced Product Discoverability**: A precisely configured search schema, relevant ranking model, and intuitive filtering capabilities fundamentally reduce the friction shoppers experience when looking for products. By enabling shoppers to find what they want quickly and accurately, the platform is designed to improve engagement and session duration.
* **Strategic Merchandizing Control**: The platform provides business users with direct, manage product lifecycle visibility, and align search results with strategic goals. This includes the ability to boost high-margin products, feature new arrivals, or curate category-specific experiences without requiring developer intervention.
* **Improved Shopper Experience and Intent Matching**: The system includes features designed to create a more forgiving and intelligent search experience. Capabilities such as search synonyms, spell correction, and redirects help capture user intent even with imperfect queries, preventing the negative experience of a zero-results page and guiding users toward relevant products and content.
### **Scope Statement**
* **In Scope**: This guide provides a comprehensive conceptual overview of the Search Schema, Search Configurations, and Merchandizing Rules. It details every functional component, explains the relevancy model, and illustrates capabilities through business-focused examples.
* **Explicitly Excluded**: This guide does not cover API endpoints, JSON structures, administrative UI walkthroughs, pricing and promotion logic
## **2. Core Concepts Explained**
### **What is Search and Merchandizing?**
In Kibo Commerce, Search and Merchandizing is not a single feature but a system of interconnected components that work in concert to govern product visibility. The system operates on a logical flow: data from the **Product Catalog** is indexed according to a defined **Search Schema**. This indexed data is then governed by platform-wide **Search Configurations**, which establish the baseline relevancy and ranking model. Finally, for specific business scenarios, this baseline behavior can be tactically overridden by **Merchandizing Rules**. This layered approach provides a powerful combination of automated relevance and manual, strategic control.
### **Why does Search and Merchandizing matter?**
The strategic management of search and merchandizing capabilities delivers significant operational, financial, and customer experience benefits.
* **Operational Benefits**: The system is designed to empower merchandizing teams by abstracting complex search logic into accessible business controls. The ability to schedule rules for future campaigns, preview their impact before publishing, and apply logic based on existing product attributes allows for efficient, predictable, and scalable campaign execution.This reduces reliance on technical teams for day-to-day merchandizing activities.
* **Financial Benefits**: The platform provides direct levers to influence profitability. Merchandisers can implement strategies to boost products with higher margins, de-emphasize low-margin or low-performing items, and increase the visibility of strategic SKUs or new arrivals to accelerate revenue from key product lines.
* **Customer Experience Benefits**: A highly relevant and intuitive search experience builds shopper trust and confidence. When search results consistently align with expectations, it encourages deeper engagement with the product catalog, reduces bounce rates, and supports a seamless path to purchase. Features that intelligently handle typos or alternative product terms contribute to a positive brand perception.
### **When to deploy Search and Merchandizing?**
While foundational search capabilities should be configured from the outset of any Kibo Commerce implementation, the deployment of advanced merchandizing strategies is often triggered by specific business events and increasing operational maturity. Key triggers include the launch of a new product line, expansion into a new market requiring localized search terminology, the execution of a major seasonal promotion, or the need to respond to competitor strategies with more aggressive product positioning. Advanced merchandizing becomes essential as the product catalog grows in size and complexity, when a business begins managing multiple sites or catalogs.
##
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture: A Multi-Layered System of Control**
The Kibo Commerce platform provides a hierarchical model for influencing search results. This architecture allows for both broad, systemic tuning at the foundational level and precise, tactical overrides at the control layer. This structure ensures that sitewide relevancy rules can coexist with specific, time-sensitive merchandizing campaigns.
### **Layer 1: The Foundation - Search Schema**
The Search Schema is the blueprint that defines *what* product data is indexed and made available to the search engine. It is the foundational step that makes all subsequent configuration and merchandizing possible. An attribute cannot be used in a search query, facet, or merchandizing rule unless it is first defined in the schema.
This creates a symbiotic relationship between the product catalog and the search engine: the richness of the search experience is directly dependent on the granularity of the data defined in the catalog. A comprehensive search and merchandizing strategy must therefore begin with a comprehensive catalog and attribute strategy.
* **Core Fields**: These are the standard, out-of-the-box product fields that form the basis of the search index.
* **Custom Attributes**: These are business-defined product attributes (e.g., color, brand, material, season) that are explicitly added to the schema to become searchable, filterable, and available as conditions in merchandizing rules. For an attribute to be available for faceting and sorting, the "Available as Filter & Sort" setting must be enabled on its definition in the catalog.
* **Analyzers**: Also known as "field types," analyzers are rules for processing text during indexing. They determine how search terms are matched, handling tasks like ignoring case, stemming words to their root (e.g., "running" becomes "run"), and processing synonyms. The choice of analyzer (e.g., lenient for broad matching, exact\_match for precise matching) depends on the data type and the desired search behavior.
### **Layer 2: The Engine - Search Configurations**
Search Configurations establish the site-wide, default relevancy and ranking model. These settings act as the global "rules of the road" that govern all searches before any specific merchandizing rules are applied. These configurations are managed per catalog and site combination, allowing for different search behaviors across different storefronts.
The platform deliberately separates search into four distinct types, allowing for nuanced tuning of the user experience based on the shopper's context and intent. This architectural choice recognizes that a direct search query has different requirements than a type-ahead suggestion or a category listing page.
* **Site Search**: Governs the behavior of the main search bar when a user submits a query. It has the most comprehensive set of configuration options, including relevancy tuning, spell correction, and match criteria, as it handles direct, intentional user queries.
* **Category Suggestion**: Manages the category names suggested to a user as they type in the search bar. Configurations are focused on field weights and the data fields returned to ensure speed and relevance.
* **Product Suggestion**: Manages the specific products suggested to a user as they type. It supports relevancy weighting, product slicing, and boost/bury conditions to ensure the most appropriate products are surfaced in real-time.
* **Listing**: Governs the default display and sorting of products on category listing pages. Its configurations focus on personalization and boost/bury capabilities to create curated browsing experiences.
### **Configuration-Level Deep Dive: Search Schema**
The Search Schema is the blueprint that tells the search engine how to understand and index the product catalog. It is the key link between raw product data and searchability.
#### **Field Type Analyzers Explained**
An analyzer, or "field type," is a set of rules that governs how the text within an indexed field is processed. The choice of analyzer is an important decision that determines the search engine's behavior, impacting how forgiving and accurate the search feels to the end-user. For example, a lenient analyzer will treat "shoe" and "shoes" as the same word (a process called stemming), while an exact\_match analyzer will not. This allows administrators to apply different text processing logic to different types of data; a product code field might require exact matching, while a product description field would benefit from more lenient, flexible matching.
The table below translates the technical function of key analyzers into their primary business use cases.
**Table 1: Key Field Type Analyzers and Their Business Impact**
| Analyzer Name | Functional Description | Key Behaviors | Primary Business Use Case Example |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| exact\_match | Matches only when the query term is an exact, case-insensitive match to the text in the field. | No stemming, no synonyms, considers term order. | Best for fields with a fixed set of values like brand or color, ensuring a search for "Red" doesn't accidentally match "Reddish". |
| lenient | A flexible analyzer that allows for more matches by using stemming and synonym expansion. | Applies stemming (e.g., run/running), expands synonyms, ignores term order. | A general-purpose analyzer ideal for freeform text fields like Product.FullDescription to find relevant products even if the query uses slightly different wording. |
| lenient\_phrases | A supplemental analyzer used with lenient that prioritizes matches where search terms appear in the same order as in the query. | Considers term order, relies on lenient for stemming and synonyms. | Used to ensure a search for "down jacket" more strongly matches products named "Down Jacket" than products with "jacket" in the name and "down" in the description. |
| code\_exact | A specialized analyzer for product codes that looks for case-insensitive exact matches. | Case-insensitive, requires exact character match. | Ideal for Product.Code or UPC fields to allow customers and B2B users to find a product by its exact part number. |
| code\_lenient | A more forgiving code analyzer that matches even if punctuation like spaces or dashes are different. | Case-insensitive, ignores spaces and punctuation. | Allows a search for "part123" to successfully match a product code stored as "PART-123", improving search forgiveness for technical SKUs. |
| ...\_type\_ahead | A suffix that can be added to other analyzers (e.g., lenient\_type\_ahead) to enable partial matching for search-as-you-type suggestions. | Matches partial words from the beginning (e.g., "sho" matches "shoe"). | Powers the type-ahead search box, providing instant product and category suggestions as the user types their query. |
###
#### **Configuration-Level Deep Dive: Search Configuration Settings**
The following table details the core attributes available within Search Configurations. These settings provide the primary levers for tuning the baseline search algorithm, translating technical parameters into direct business decisions.
| Attribute Name | Business Purpose | Available Options/Data Type | Impact and Trade-offs | Concrete Example |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| **Field Weights** | To control the baseline importance of different product attributes in determining search result ranking. | Integer (1-20) for weight and phraseWeight. | Higher weights on attributes like 'Brand' will prioritize brand matches over other attributes. The trade-off is balancing multiple attributes to match common user intent. | Giving productName a weight of 10 and description a weight of 3 ensures product name matches are ranked significantly higher. |
| **MinMatch** | To define the minimum percentage of words in a search query that must match a product for it to appear in results. | Percentage (0-100%). Kibo recommends 100%, 75%, 50%. | A high MinMatch (100%) yields highly relevant but fewer results. A lower value increases the result count but may reduce relevance. | Setting MinMatch to 75% for a 4-word query means products matching at least 3 of the words will be returned. |
| **Phrase Slop** | To control how close words in a search phrase must be to each other within a product's data to be considered a match. | Integer (0 or greater). Kibo recommends 1 or 2. | A slop of 0 requires an exact phrase match. A higher slop allows for more flexible matching but can introduce less relevant results. | A slop of 1 allows "red running shoe" to match "red lightweight running shoe". |
| **Auto Correct** | To automatically correct a misspelled query and show results for the corrected term when the original query yields no results. | Boolean (Enable/Disable). | Prevents a zero-results page, improving user experience. The trade-off is that the system makes an assumption about user intent which could be incorrect. | A user searching for "runnig shoos" is automatically shown results for "running shoes". |
| **Did You Mean** | To suggest an alternative, corrected search term when the original query has few or no results. | Boolean (Enable/Disable). | A less intrusive way to guide users than Auto Correct, giving them control. It requires an extra click from the user. | A user searching for "shiirt" sees a "Did you mean: shirt?" link above the (empty) results. |
| **Product Slicing** | To determine if product variations (e.g., different colors of a shirt) appear as single, distinct items in search results. | Boolean (Enable/Disable). | Enabling slicing increases the number of results and is useful for visual merchandizing. Disabling it groups variants into one result, simplifying the view. | With slicing enabled, a search for "shirt" returns separate results for the red shirt, blue shirt, and green shirt. |
###
### **Layer 3: The Control Layer - Merchandizing Rules**
Merchandizing Rules are the tactical layer of the system. They allow business users to manually override the default search algorithm for specific, targeted business purposes, often within a defined timeframe. These rules provide the agility needed to react to market trends, execute promotions, and curate the shopping experience.
The platform provides two distinct scopes for rules, which represents a strategic choice about what to target: shopper *intent* (a specific search query) or shopper *location* (a specific category page).
* **Site Search Rules**: These rules are triggered by specific **Search Terms** entered by the shopper. This scope is ideal for campaigns tied to keywords, brands, or product types that users are actively searching for.
* **Category Rules**: These rules are triggered when a shopper navigates to a specific **Category** page. This scope is used to curate the browsing experience within a particular section of the site, regardless of how the shopper arrived there.
#### **Configuration-Level Deep Dive: Merchandizing Rule Settings**
The following table details the attributes for configuring a Merchandizing Rule. This toolkit enables merchandisers to precisely define the trigger, duration, and impact of their strategic overrides.
| Attribute Name | Business Purpose | Available Options/Data Type | Impact and Trade-offs | Concrete Example |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------- |
| **Schedule** | To define the active period for a rule, enabling automated start and end for campaigns. | Start Date/Time (required), End Date/Time (optional). | Enables "set it and forget it" campaigns. If no end date is set, the rule runs indefinitely, which requires manual management. | A "Black Friday" rule is scheduled to start at midnight on Friday and end at 11:59 PM on Sunday. |
| **Criteria (Search Terms)** | To trigger a rule based on specific keywords or phrases a shopper enters in the site search. | Text input, case-insensitive. | Allows for precise targeting of user intent. Requires anticipating all relevant search terms for a campaign. | A rule for "winter coats" boosts down jackets and buries raincoats. |
| **Criteria (Categories)** | To trigger a rule when a shopper is browsing specific product categories. | Selection from available catalog categories. | Curates the browsing experience for key categories. Does not affect site-wide search results for products in that category. | A rule for the "New Arrivals" category pins the top 5 featured items to the first five positions. |
| **Boost/Bury Condition** | To dynamically alter the ranking of products based on their attributes. | Field/Attribute, Operator, Value, Boost/Bury Value (-10 to 10). | A powerful, scalable way to promote or demote groups of products without manual pinning. More efficient for large product sets. | For the query "laptops", a condition boosts any product where brand equals "Apple" by +10. |
| **Blocked Products** | To completely remove specific products from the results for a given rule's criteria. | Search and select products by Name, Code, or Product Type. | Ensures unwanted or irrelevant products do not appear for a specific query or in a specific category. | For the query "vegan snacks", any products containing dairy are added to the Blocked Products list. |
| **Manual Ranking** | To manually set the exact position of a product in the results, locking all products above it. | Drag-and-drop or enter a rank number in the preview pane. | Provides absolute control over the top results. Less flexible than boosting, as it locks positions. | A merchandiser drags the "Hero Product" to rank #1 for a campaign query. |
| **Pinning** | To lock a specific product into a set position without affecting the ranking of other products around it. | Click the pin icon in the preview pane. | Guarantees a product's position. Recommended for a small number of items. | Pinning a specific accessory to position #3 ensures it always appears there, even if other products are boosted. |
| **Add Products** | To inject products into a result set that would not normally appear. | Search and select products to add to the result set. | Useful for cross-selling or promoting related items that don't match the search criteria. | For a search of "running shorts", a merchandiser uses "Add Products" to also show a best-selling water bottle. |
##
## **4. Key Capabilities and Business Applications**
The functional components of the Search and Merchandizing system enable a wide range of powerful business strategies. The following examples illustrate how these capabilities can be applied in real-world scenarios across different industries.
### **Capability: Strategic Relevancy Tuning**
* **Functional Explanation**: This capability involves using **Field Weights** in Search Configurations to establish a baseline search relevance model that aligns with business priorities. It provides a global answer to the question: "For any given search, which product attributes are most important?" This allows the core search algorithm to be tuned to match the primary ways customers search for products.
* **Business Application Example**:
* **Industry**: B2B Industrial Distributor
* **Scenario**: The distributor knows its professional clients search by precise part numbers (SKUs) and manufacturer brands far more often than by descriptive keywords. To optimize for this behavior, the search administrator configures the site's Field Weights to give the productCode attribute the highest weight (e.g., 20), the brand attribute the second highest (e.g., 15), and the productShortDescription attribute a much lower weight (e.g., 5). This configuration ensures that an exact part number match always appears at the top of the results, resulting in a faster, more accurate ordering process for their buyers and reducing the risk of incorrect parts being ordered.
### **Capability: Dynamic and Automated Merchandizing**
* **Functional Explanation**: This capability leverages **Boost/Bury Conditions** within a Merchandizing Rule to automate the promotion or demotion of entire groups of products based on their attributes, eliminating the need to manage each product individually. This is the most scalable and efficient method for merchandizing large catalogs, as a single condition can affect thousands of SKUs.
* **Business Application Example**:
* **Industry**: Fashion & Apparel Retailer
* **Scenario**: To prepare for an upcoming season, the merchandizing team wants to promote all "New Arrival" items and de-emphasize last season's clearance stock. They create a Categories rule that applies to the "Dresses" category. Within the rule, they add a condition to boost any product where the custom attribute season equals "Fall 2024" by a value of +10. They add a second condition to bury any product where the on\_clearance attribute is true by a value of -10. This automatically pushes new inventory to the top and old inventory to the bottom across the entire category, resulting in higher visibility for full-price items and a more efficient sell-through of new stock.
### **Capability: Search Intent Correction and Guidance**
* **Functional Explanation**: This capability combines several tools—**Synonyms**, **Search Term Redirects**, and **Stop Words**—to interpret, guide, and correct user search queries. Synonyms broaden search results to include related terms. Redirects guide users from a search query directly to a curated landing page. Stop words are common words (e.g., "the", "and") that can be ignored in queries to focus on the most significant terms.
* **Business Application Example**:
* **Industry**: Direct-to-Consumer (DTC) Home Goods Brand
* **Scenario**: The brand sells "sofas," but analytics show many users search for "couches." The merchandizing team creates a two-way **Synonym** set for to ensure all these searches return the same relevant products. Additionally, they are launching a major campaign around their new "Outdoor Living" collection. They create a **Search Term Redirect** for the query "patio furniture" that sends users directly to the /outdoor-living content page instead of a standard search results page. This provides a more curated brand experience and improves conversion for the high-priority campaign.
## **5. Platform Integration Map**
The Search and Merchandizing system is deeply integrated with other core areas of the Kibo Commerce platform. Its effectiveness is dependent on upstream data sources and has significant downstream impacts on the customer experience and other platform capabilities.
### **Upstream Dependencies**
* **Catalog and Product Attributes**: This is the most important dependency. The richness, accuracy, and structure of the Master Catalog directly determine the potential of the search and merchandizing engine. Attributes must be created with their end use in mind—for example, an attribute intended for use in a merchandizing rule must be defined in the catalog, assigned to products, and then added to the Search Schema to be available for selection.
### **Downstream Impacts**
* **Storefront Experience**: All search and merchandizing configurations directly manifest on the customer-facing site. They influence category navigation, the relevance of search results, and the overall ease of product discovery, which are key factors in determining conversion rates.
* **Facets and Filtering**: Product attributes that are indexed in the Search Schema and marked as "Available as Filter & Sort" can be configured as facets. Facets are the primary tool shoppers use to refine search results and category listings, making the Search Schema a direct prerequisite for a functional faceted navigation experience.
### **Synergistic Features**
* **Personalization (Monetate Integration)**: This is the most powerful synergy available on the platform. The system is designed to combine the algorithmic relevance score from Kibo Commerce with a personalization score from the integrated Monetate engine. The final ranking a user sees is a hybrid score. Kibo's Search Configuration sets the baseline product and attribute relevance, while Monetate adds a user-specific behavioral boost on top. This allows a business to ensure that even personalized results still adhere to core merchandizing strategies. For example, a high-margin item can be given a baseline boost in Kibo, making it more likely to be selected and further promoted by the personalization engine for a specific user. This provides a strategic safety net and control over the personalization algorithm.
* **Product Slicing**: When the Product Slicing feature is enabled, it interacts directly with the search and listing engine. Instead of displaying a single configurable product (e.g., a T-Shirt) with selectable options (e.g., Red, Blue, Green), slicing instructs the search results to display each variation as a distinct, individual product in the grid. This can increase the visual surface area for popular products with many variations, potentially improving engagement and click-through rates.
## **6. Related Conceptual Guides**
To fully leverage the Search and Merchandizing capabilities, a comprehensive understanding of related platform concepts is essential.
### **For foundational knowledge, refer to:**
* **[Catalog](/concept-guides/catalog)**: This guide explains how to structure master catalogs, catalogs, categories, and product attributes. This knowledge is a prerequisite for building an effective Search Schema, creating category-scoped merchandizing rules, and fueling faceting, filtering, and attribute-based merchandizing rules
### **To understand downstream impacts, refer to:**
* **[Cart & Checkout](/concept-guides/cart-and-checkout):** This guide explains the process shoppers follow after discovering products. A successful search and merchandizing strategy directly impacts this process by ensuring shoppers can find and add the right products to their cart.
### **For complementary strategies, refer to:**
* **[Promotions](/concept-guides/promotions)**: Merchandizing strategies are often executed in direct support of specific promotional campaigns. While the logic for applying promotion is separate, a merchandiser will typically create rules to boost the visibility of the products that are part of an active promotion.
# Ship to Home (STH)
Source: https://docs.kibocommerce.com/concept-guides/sth
Ship products directly from fulfillment locations to customer delivery addresses
# **Ship to Home (STH) Conceptual Guide**
Learn how package consolidation combines ship-to-home shipments to reduce shipping costs
***
## **1. Strategic Overview**
**Concept Definition:** Ship to Home (STH), also known as Direct Ship, is a core **fulfillment method type** where ordered products are shipped directly from a designated fulfillment location (such as a warehouse, distribution center, or retail store) to the customer's specified delivery address.
**Business Context:** STH is the foundational and most widely used fulfillment process within the Kibo Commerce platform, enabling retailers to meet the fundamental promise of e-commerce delivery. It is integral to inventory allocation and order routing.
**Value Drivers:**
* **Expanded Inventory Reach:** By enabling any location with inventory to act as a fulfillment point, STH allows retailers to leverage their entire network—including stores—to fulfill customer demand, thereby maximizing sell-through and reducing stockouts.
* **Customer Convenience and Choice:** It offers the most traditional and expected shipment option, catering to the vast majority of online transactions and providing the shipment directly to the customer's preferred location.
* **Operational Streamlining:** The well-defined STH workflow integrates seamlessly with carrier services and tracking systems, which standardizes the package preparation and hand-off process across all fulfillment locations.
**Scope Statement:** This guide covers the functional process, components, and optional transfer/consolidation capabilities of the Ship to Home fulfillment method. It explicitly excludes implementation details such as API specifications, specific integration code, or detailed configuration setup steps in the Administrative console.
***
## **2. Core Concepts Explained**
### **What is Ship to Home (STH)?**
STH is a defined fulfillment process within the Kibo Commerce unified commerce platform. It is functionally characterized by the movement of goods from an internal inventory holding location to the external, customer-provided shipping address via a commercial carrier. It forms a distinct, state-driven workflow that dictates the steps a shipment must follow from initial order acceptance to final carrier handoff and fulfillment completion.
### **Why Does Ship to Home (STH) Matter?**
STH fulfillment is the mechanism that translates a committed order into a physical shipment, impacting several key areas of the retail operation:
* **Operational Benefit:** The standardized workflow ensures that all fulfillment points—whether a centralized distribution center or a retail store—adhere to a consistent process for picking, packing, and labeling. This consistency reduces errors, minimizes the need for varied training, and speeds up the time from order placement to shipment, a key factor in customer satisfaction.
* **Financial Benefit:** By enabling distributed inventory sources (like stores) to perform STH, the retailer reduces the financial burden of markdowns on aging or excess stock while simultaneously utilizing the most optimal shipping location to minimize transit costs and delivery times.
* **Customer Experience Benefit:** STH allows the customer to receive their products directly at their home or preferred location. The structured process is designed to provide timely updates, including tracking information upon shipment completion, thereby setting accurate expectations and building trust in the brand's delivery commitment.
### **Storefront Usage of STH**
In the storefront experience, the Ship to Home method is most evident in the **shipping selection phase of the checkout process**.
1. **Shipping Address Collection:** The customer provides a ship to address, which is the foundational data point for an STH shipment.
2. **Fulfillment Option Presentation:** Based on the customer's address and the items in their cart, the system presents one or more STH-compatible shipping services (e.g., standard, express, next-day), each associated with a different cost and estimated delivery timeframe.
3. **Shipment Creation:** Once the customer selects a shipping option and places the order, the system allocates the items to a fulfillment location via **Order Routing**. The resulting shipment is assigned the **Ship to Home** fulfillment type. The storefront itself facilitates the initial customer request that the fulfillment system then processes.
***
## **3. Functional Components & Configuration Deep Dive**
### **Component Architecture**
The STH process involves a coordination of the following key components:
* **Order:** The high-level transaction object containing the line items, customer, and payment information.
* **Shipment (STH Type):** A subset of the order items, assigned to a single fulfillment location and designated for the STH workflow.
* **Fulfillment Location:** The physical site (warehouse, store) assigned to fulfill the shipment, which utilizes the **Fulfiller UI** or associated system integrations to process the steps.
* **Order Routing Engine:** Determines the optimal fulfillment location for the shipment based on rules considering, among others, inventory, proximity to the customer, and cost.
* **Carrier Integration:** External system used to generate shipping labels, tracking numbers, and manage carrier handoff.
### **Configuration-Level Deep Dive**
| Configuration Name | Business Purpose | Impact and Trade-offs | Example |
| :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| **Fulfillment Method Type (Location)** | Specifies that a particular location is eligible to process Ship to Home orders. | **Impact:** Enables the location to receive and fulfill STH shipments. **Trade-off:** Requires staff training and dedicated packing/shipping logistics at that site. | A Distribution Center's profile must have **Ship to Home** selected to be considered for STH orders. |
| **STH Consolidation Setting (Location)** | Qualifies the Location to be the receiving location for transfers. Determines whether STH shipments with items from multiple source locations should consolidate at a centralized point before being shipped to the customer. | **Impact:** Reduces the number of packages the customer receives (improved CX) and can lower overall shipping costs. **Trade-off:** Adds an intermediate transfer step and time to the fulfillment cycle. | An **Omnichannel Retailer** enables this to prevent a customer from receiving two separate boxes for a single online order. |
***
## **4. Key Capabilities and Business Applications**
### **Capability: Default Ship to Home Fulfillment Workflow**
**Functional Explanation:** The default STH workflow is a series of defined shipment states in the Fulfiller UI that guides the fulfillment location associate through the entire process. The steps include: **Accept Shipment**, **Validate Items in Stock**, **Print Packing Slip**, and **Prepare for Shipment** (which culminates in shipment completion and carrier handoff). Each step ensures all required operational tasks are complete before moving to the next state.
**Business Application Example:**
* **Industry:** Fashion & Apparel Retailer
* **Scenario:** A customer places an order for three blouses and a scarf. Order Routing assigns the entire order as one STH shipment to a regional Distribution Center (DC). The DC associate sees the shipment in the **Accept Shipment** queue, acknowledges it, and then moves to **Validate Items in Stock**, using a scanner to confirm all four items are physically picked from the bin location. After printing the packing slip, they enter the box dimensions and weight in the **Prepare for Shipment** step, which automatically generates a shipping label. Upon clicking **Yes, Complete Shipment**, the DC is finished with the order, and the shipment moves to a **Fulfilled** state, resulting in faster order processing and reliable customer expectation setting for delivery.
### **Capability: Shipment Splitting upon Partial Stock**
**Functional Explanation:** If, during the **Validate Items in Stock** step, a fulfillment location determines it has a quantity less than what the shipment requires, and **STH Consolidation** is **not** enabled, the system automatically splits the original shipment. The available items remain in the current shipment, which proceeds to be fulfilled. The unavailable items are immediately reassigned to a new shipment, which is then re-routed to a different, eligible location with the required inventory.
**Business Application Example:**
* **Industry:** Enterprise Electronics Retailer
* **Scenario:** An order for a laptop and a specialized accessory is assigned to a store for STH fulfillment. During stock validation, the store associate confirms they have the laptop but are out of the accessory. Because consolidation is off, the system splits the order. The original shipment with the laptop proceeds to be packed and shipped from the store. A new shipment for the accessory is instantaneously created and assigned to the nearest warehouse that *does* have stock. The business outcome is a **faster fulfillment cycle** for the readily available items and a **reduced risk of customer cancellation** for the order's entirety, as both components are in motion promptly.
### **Capability: Transfer Shipments with STH Consolidation**
**Functional Explanation:** When the optional **STH Consolidation** feature is enabled, a partial-stock scenario during **Validate Items in Stock** does **not** split the original shipment. Instead, the shipment enters the **Waiting for Transfer** state, and a separate **Transfer Shipment** is created. This child shipment moves the missing inventory from a different location to the original (consolidation) location. The parent STH shipment can only proceed to **Print Packing Slip** once the transfer shipment has been received and validated at the consolidation location.
**Business Application Example:**
* **Industry:** B2B Industrial Distributor
* **Scenario:** A client places a bulk order for various equipment parts that gets assigned to the main warehouse (the consolidation location). The warehouse only has 8 of the 10 required safety gloves. The system creates a Transfer Shipment for the 2 missing gloves from a nearby branch location. The main warehouse's STH shipment is paused in **Waiting for Transfer**. Once the branch ships the gloves, and the main warehouse confirms receipt of the transfer, the original STH shipment is updated to full stock and proceeds. This ensures the B2B customer receives the large order in a **single, consolidated delivery**, which simplifies their receiving process and reduces their internal logistical overhead.
### **Capability: Automated Shipping Label Generation**
**Functional Explanation:** As part of the **Prepare for Shipment** state, the Fulfiller UI integrates with configured carrier services. By entering required package details (carrier, box dimensions, and weight), the system automatically calls the carrier's API to generate a shipping label and tracking number. This can also be manually overridden by entering a pre-acquired tracking number. The completion of this step, marked by clicking **Yes, Complete Shipment**, transitions the shipment to the **Fulfilled** state.
**Business Application Example:**
* **Industry:** Marketplace Operator
* **Scenario:** A third-party vendor operating on the marketplace platform receives an STH order assigned by Kibo's routing logic. The vendor’s fulfillment team completes the package preparation, enters the custom box weight, and clicks the button to print the label. The system communicates with the vendor's preferred carrier (e.g., FedEx) to print the label directly. This automation standardizes the carrier integration across all marketplace vendors, resulting in **accurate and timely tracking information for the end customer**, which is important for maintaining marketplace compliance and service level agreements.
### **Confirmation of Shipment**
The system handles the confirmation of shipment in the following manner:
1. **Preparation and Carrier Hand-off:** During the **Prepare for Shipment** state, the fulfiller finalizes the package and obtains the tracking number (either automatically generated or manually entered).
2. **Completion of Fulfillment:** When the fulfiller clicks **Yes, Complete Shipment**, the shipment state officially transitions to **Fulfilled**. This action is the formal, in-system confirmation that the items have been packed and handed over to the carrier for the final delivery.
3. **Customer Notification:** The transition to the **Fulfilled** state triggers customer-facing notifications, which include the tracking number and link to the carrier's tracking page. This is the mechanism by which the customer is informed that their order is on its way.
***
## **5. Platform Integration Map**
### **Upstream Dependencies**
| Dependency | Prerequisite Data/State |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
| **Inventory Availability** | Accurate, real-time quantity on hand at the assigned fulfillment location. |
| **Locations** | Requires Locations be configured for Direct Ship Fulfilment |
| **Order Routing Rules** | Must be configured to identify and assign shipments to locations with the **Ship to Home** fulfillment type enabled. |
| **Product Shipping Attributes** | Products must be configured as shippable goods, not digital products. |
| **Payment Authorization** | The order must have an accepted or paid payment status to move the shipment into a fulfillable state. |
### **Downstream Impacts**
| Impact | Enabled Capabilities/Process Changes |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| **Invoicing and Payment Capture** | The customer is typically charged or the payment is captured upon the completion of the STH fulfillment (moving to the **Fulfilled** state). |
| **Customer Service** | Enables customer service agents to view carrier tracking information and fulfillment notes for assistance. |
| **Returns Processing** | The shipment's **Fulfilled** status is a prerequisite for initiating a standard customer return process. |
| **Reporting and Analytics** | Fulfillment metrics, such as time-to-ship and carrier performance, are recorded and available for analysis. |
### **Synergistic Features**
| Complementary Capability | Combined Value Proposition |
| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Order Routing Engine** | Combining STH with robust routing ensures the shipment is assigned to the most strategically optimal location, minimizing cost and transit time, resulting in both financial and customer experience benefits. |
| **Fulfillment Process Manager (BPM)** | The BPM allows for customization of the default STH workflow with unique steps or logic, enabling complex business requirements like integrated quality checks or specific carrier hand-off protocols. |
| **Product Attributes** | Using required item identifier attributes (e.g., serial numbers) during the STH process ensures high-value or regulated products are tracked accurately from fulfillment to the customer, minimizing inventory discrepancies and liability. |
***
## **6. Related Conceptual Guides**
**For foundational knowledge, refer to:**
* **[Order Routing](/concept-guides/order-routing):** This is a prerequisite because Order Routing is the mechanism that determines *which* location is assigned an STH shipment based on available inventory and business rules.
**To understand downstream impacts, refer to:**
* **[Returns and Reverse Logistics](/concept-guides/returns-and-reverse-logistics):** The completion of the STH process (moving to the **Fulfilled** state) is the necessary trigger for the standard returns window and process to become active for the customer.
# Product Subscriptions Overview
Source: https://docs.kibocommerce.com/concept-guides/subscriptions
Enable automated recurring purchases and manage the complete subscription lifecycle
When subscriptions are enabled for a product, customers are able to set up a recurring automatic purchase during checkout such as a shipment of body wash every month. This allows customers more flexibility with setting up future "continuity" orders in advance, drives more regular sales, and allows product inventory to be replenished at a cadence. This feature also lets them test out the product for a trial period in advance of their full subscription.
See the Subscription API documentation for programmatic access
Learn how to configure subscription attributes and create offline subscription orders
See how to configure subscription settings at the site level
Subscriptions are offered as part of a eCommerce+OMS implementation, as well as a standalone product that does not include Kibo's eCommerce storefront or Order Management. The standalone Subscriptions implementation still requires customer and catalog data such as discounts and products to be configured.
For schemas of API calls associated with Subscriptions, see [the API documentation](/api-overviews/openapi_subscription_overview). For information about the reporting that is available for subscription data, see [the Reporting documentation](/pages/explores-overview#subscription-explore).
Looking for webhook configurations? See [Event Subscription](/pages/event-subscription) for information about subscribing applications to Kibo platform events.
## **1. Strategic Overview**
**Concept Definition:** Subscriptions enable automated recurring purchases through recurring orders, transforming one-time transactions into predictable, long-term customer relationships.
**Business Context:** Kibo Commerce subscriptions serve as a foundational revenue optimization capability within the unified commerce platform. It is designed to manage the complete subscription lifecycle, from initial creation through ongoing payment processing and customer communications, by providing a dual management approach. Firstly, it offers comprehensive automation for recurring orders, payments, and standard communications, driving predictable revenue and operational efficiency. Secondly, the platform provides flexible direct management capabilities that allow users to intervene, modify, and manage subscriptions for necessary operational adjustments, personalized service and resolution of complex customer scenarios.
**Value Drivers:**
1. **Predictable Revenue Streams:** Automated recurring orders create consistent, forecastable income that supports strategic planning and improves financial stability through recurring customer commitments, enabling more confident business investments and enhanced cash flow predictability.
2. **Operational Automation Excellence:** Comprehensive automation of order generation, payment processing, inventory allocation, and customer communications eliminates manual intervention while reducing operational costs and human error across the entire subscription lifecycle.
3. **Enhanced Customer Lifetime Value:** Long-term recurring relationships foster deeper customer engagement, provide extensive behavioral data for personalization, and create multiple touchpoints for additional value delivery and strategic cross-selling opportunities.
**Scope Statement:** This guide covers subscription business value, core concepts, comprehensive business configuration strategies, lifecycle management, advanced operations, pricing capabilities, discount capabilities, payment handling, system-wide configuration strategy. It focuses on functional understanding and business applications without covering specific technical implementations, detailed configuration procedures, or API specifications.
***
## **2. Core Concepts Explained**
### **What is Subscription?**
Subscriptions in Kibo Commerce represent a comprehensive recurring commerce solution that automates repeat purchases—transactions generated at predefined intervals based on customer-selected frequencies and configured business rules.The system transforms traditional one-time purchases into ongoing customer relationships by handling the complete subscription lifecycle: from initial setup and trial periods through recurring order generation, payment processing, fulfillment coordination, and lifecycle management.
### **Why does Subscriptions matter?**
Subscriptions are the core functional mechanism through which Kibo Commerce enables predictable revenue streams and operational automation. The platform’s comprehensive capabilities automates the transition from single purchases to long-term customer relationships. Kibo Commerce enables this through unified capabilities, including sophisticated payment recycling and installment options, providing customers with flexibility to choose between one-time purchases and recurring commitments, and flexible management features, ensuring scalability and fine-grained operational control over every recurring revenue stream.
### **When to deploy Subscriptions?**
**Business Triggers:** Deploy subscriptions for products with regular consumption patterns, curated collections requiring periodic delivery, services with ongoing access requirements, or high-value items benefiting from installment payment options. The system supports both B2C consumable replenishment and B2B bulk ordering scenarios, enabling diverse business models under unified subscription management while accommodating international expansion and complex operational requirements.
**Maturity Requirements:** Subscription deployment requires established product catalogs, configured payment gateways supporting recurring transactions, defined customer account structures.
**Timeline to Value:** The strategic decision to deploy is justified by a dual-phased value realization. Immediate Value begins upon the first subscription creation, as automated recurring orders instantly generate forecastable recurring revenue from the first billing cycle. Long-Term Value is realized through the adoption and configuration of advanced platform features, such as payment recycling and installment plans, which systematically enhance customer retention, reduce involuntary churn, and improve operational efficiency over time. This phased value realization supports both quick ROI and sustained growth across the entire customer base.
***
## **3. Functional Components & Configuration Deep Dive**
### **3.1 Component Architecture**
The subscription system operates through a structured hierarchy of interconnected business components:
### **Subscription Component**
**Functionality:** Handles recurring order creation based on customer-selected frequencies, business rules, and operational timing controls
**Business Purpose:** Enables predictable revenue streams and reduces manual order processing overhead while supporting complex scheduling requirements
### **Product Configuration Component**
**Functionality:** Defines subscription eligibility, frequency options, trial capabilities, and bundle configurations at product portfolio levels
**Business Purpose:** Enables scalable subscription rollouts and consistent customer experience across product lines while supporting diverse business models
###
### **Subscription Lifecycle Management**
**Functionality:** Provides pause, skip, modification, and cancellation capabilities for both customers and service representatives with configurable automation policies
**Business Purpose:** Reduces churn through flexibility while maintaining customer relationships during changing needs and circumstances
**Subscription Status Definitions:** The subscription lifecycle is managed through distinct status states that control system behavior and enable appropriate customer service and reporting capabilities:
* **Pending**: Subscriptions that have been created but not yet activated
* **Active**: Subscriptions that are active and generating recurring orders according to their configured frequency and business rules
* **Paused**: Subscriptions temporarily suspended by customer or administrative action, with automatic or manual reactivation capabilities
* **Errored**: Subscriptions where a problem occurred during processing, typically related to payment issues preventing the subscription from functioning normally. Resolution requires addressing the underlying issue to restore subscription operation
* **Failed**: Subscriptions where the system attempted multiple times to generate recurring orders but was unsuccessful, causing automatic order creation to stop. Manual intervention or successful order placement can restore normal subscription functionality
* **Cancelled**: Subscriptions permanently terminated by customer or administrative action, with no further recurring orders generated
These status definitions are fundamental for CSR teams managing customer relationships and for reporting systems tracking subscription performance and lifecycle analytics.
### **Subscription Pricing System**
**Functionality:** Manages subscription-specific pricing, price locking mechanisms, promotional pricing structures, and installment payment options
**Business Purpose:** Enables competitive subscription value propositions while protecting customer trust through price consistency and payment flexibility
### **Trial and Conversion System**
**Functionality:** Handles trial product substitution, duration management, automated conversion to full subscriptions, and conversion optimization tracking
**Business Purpose:** Reduces customer acquisition barriers and enables product demonstration before commitment while optimizing conversion rates
### **Communication and Notification System**
**Functionality:** Manages proactive customer communications for status changes, upcoming orders, and required actions.
**Business Purpose:** Reduces support burden while improving customer satisfaction through transparent communication and automated workflow integration
***
## **3.2 Business Configuration Deep Dive**
This consolidated table highlights the most important, high-level settings that determine what subscription is offered and how the system operationally manages the recurring revenue stream.
| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscription Mode** | Defines the fundamental purchasing commitment (one-time, mixed, or subscription-only). | Directly impacts customer acquisition strategy; balances maximum recurring revenue potential against offering customer flexibility. | A premium roaster sets artisanal blends to Subscription-Only to secure consistent monthly revenue. |
| **Subscription Frequency** | Aligns automated delivery schedules with customer consumption patterns by offering pre-configured and custom frequencies. | Balances customer satisfaction (offering variety) against operational complexity (inventory and fulfillment planning). | A pet company offers Monthly and Bi-Monthly frequencies to match consumption rates for different dog sizes. |
| **Trial Days** | Reduces commitment barriers by enabling a limited-time product experience before full commitment. | Longer trials may delay revenue but increase acquisition potential; requires clear communication on the transition date. | A meal kit service offers a 7-day trial to demonstrate quality before transitioning to the full subscription. |
| **Trial Product Code / Variation Code** | Effective trial products must demonstrate value while remaining cost-effective for customer acquisition and competitive with market alternatives. | Enables a precise, cost-effective trial experience optimized for value demonstration and high conversion potential. | A skincare brand uses sample-sized starter kits to control fulfillment costs. |
| **Order Scheduling Controls** | Governs the timing of order creation (Create Continuity Order X Days Before Next Order Date), order date reset rules (Order Now Resets Next Order Date), and the limit for manually delaying the next order (Update Next Order Date Up to X Days) | Important for controlling fulfillment lead times, improving inventory allocation, and governing customer/admin control over the delivery schedule. | The system creates the order 7 days early for fulfillment planning. Ordering early via the Order Now action automatically resets the subsequent delivery schedule. |
| **Skip / Pause Controls** | Limits the number of consecutive orders a customer can skip and the total duration a subscription can remain paused before auto-reactivation. These are controlled by settings like Skip Subscription X Times and Pause Subscription Duration Limits. | Balances providing customer flexibility during temporary needs changes against the strategic goal of long-term revenue retention. | A customer can skip 2 orders. A paused subscription will auto-reactivate after three missed orders. |
| **On-Demand Ordering Controls** | Sets a restriction period (Allow Order All or Partial Items Now Once Every X Days) after an on-demand "Order All/Partial Items Now" action is performed. | Ensures appropriate timing between urgent fulfillment requests, maintaining overall subscription schedule integrity. | On-demand ordering is restricted for 30 days after a partial order is placed early. |
| **Communication & Notification Strategy** | Manages timing, frequency, and triggers for all automated customer emails (reminders, status, modifications, reactivations). | Enables proactive customer relationship management by providing important advance notice before the recurring order is created, setting expectations during lifecycle changes, and informing customers of account status and modifications | An email is sent 3 days before an order processes, and a separate notification confirms the Subscription Status Change. |
| **Subscription Attribute Scope Settings** | Defines if custom data fields apply only to the subscription relationship, or to both the subscription and individual recurring orders. | Enables the capture of unique data (e.g., compliance or project codes) that supports operational reporting, downstream fulfillment requirements, and financial reconciliation across the subscription lifecycle. | A B2B client captures the "Department Budget Code" attribute, scoped to persist across all recurring orders |
***
## **4. Key Capabilities and Business Applications**
### **Capability: Automated Recurring Customer Relationships**
**Functional Explanation:** Recurring orders serve as the foundation for transforming one-time transactions into ongoing customer relationships through automated order generation. The system automatically creates recurring orders based on customer-selected frequencies and configured business rules, handling payment processing, inventory allocation, and fulfillment coordination without manual intervention. This capability enables businesses to build predictable revenue streams while providing customers with seamless automated convenience for regularly consumed products and services.
**Business Application Example:**
**Industry:** B2B Industrial Distributor
**Scenario:** A large manufacturing facility requires monthly shipments of industrial cleaning supplies for their production floors. The facility manager sets up a subscription for essential cleaning chemicals, safety equipment, and maintenance supplies with automated monthly delivery. When the subscription is active, the system automatically generates orders on the predetermined schedule, processes payments against the company's stored payment method, and coordinates fulfillment with the distributor's warehouse. This automation ensures the facility never runs out of essential supplies while eliminating manual reordering overhead for both the buyer and supplier, resulting in improved operational efficiency, reduced procurement costs, and stronger business relationships through reliable service delivery.
### **Capability: Strategic Subscription Offerings**
**Functional Explanation:** The platform enables businesses to configure products with different subscription approaches based on strategic objectives and market positioning. Products can be offered exclusively through subscriptions to maximize recurring revenue, or businesses can provide customer choice between one-time purchases and subscription commitments. This flexibility allows companies to tailor their subscription strategy to different product categories, customer segments, and business goals while maintaining unified management across their subscription portfolio.
**Business Application Example:**
**Industry:** Fashion & Apparel Retailer
**Scenario:** A premium athleisure brand wants to build recurring revenue while accommodating different customer preferences and market segments. They configure their core workout essentials like athletic tops and leggings as subscription-eligible with both one-time and subscription purchase options, offering a 15% discount for subscription commitments. However, their limited-edition seasonal collections are kept as one-time purchases only to maintain exclusivity and urgency. Meanwhile, their basic athletic socks and accessories are offered exclusively through subscription to ensure consistent replenishment revenue. This strategic model segmentation results in optimized revenue streams that balance customer acquisition flexibility with recurring revenue growth while maintaining product positioning integrity and brand differentiation.
### **Capability: Trial-to-Subscription Conversion Programs**
**Functional Explanation:** Trial periods serve as powerful customer acquisition tools that reduce commitment barriers by allowing customers to experience products before committing to full subscriptions. The system automatically substitutes trial products during the evaluation period, then seamlessly transitions to full subscription fulfillment while maintaining all customer preferences including frequency, payment methods, and shipping information. This capability enables businesses to prove product value and optimize conversion rates through strategic trial design and targeted conversion communications.
**Business Application Example:**
**Industry:** Direct-to-Consumer Brand
**Scenario:** A DTC beauty brand launching a monthly skincare subscription faces customer hesitation about committing to unknown products and recurring charges. They implement a 7-day trial program where new customers receive a sample-sized starter kit for the cost of shipping alone. During the trial period, customers experience the products while receiving personalized skincare tips and education emails designed to demonstrate value and build confidence. The system automatically transitions successful trials to full-sized monthly subscriptions at the standard pricing, while providing easy cancellation options for unsatisfied customers. This approach significantly increases customer acquisition by reducing perceived risk, resulting in higher conversion rates, more confident long-term subscribers who have already experienced product quality, and reduced customer service inquiries about product suitability.
### **Capability: Subscription-Specific Pricing Strategies**
**Functional Explanation:** The platform provides sophisticated pricing mechanisms that enable businesses to offer different pricing for subscription versus one-time purchases, creating clear value propositions for recurring commitments. Price locking mechanisms protect subscribers from future increases while providing businesses with committed revenue at known margins. This capability allows companies to implement competitive "subscribe and save" programs while maintaining pricing integrity and customer trust through transparent pricing protection policies.
**Business Application Example:**
**Industry:** Enterprise Office Furniture Retailer
**Scenario:** A large office furniture retailer offers enterprise office furniture solutions through both one-time purchases and annual subscriptions. For their executive office furniture suite, they price one-time purchases at \$1,200 annually but offer subscription pricing at \$95 per month with price protection guarantees for the subscription duration. Enterprise customers who choose subscriptions receive locked pricing for their subscription lifetime, protecting them from the typical annual price increases seen in office furniture markets. This pricing strategy attracts price-sensitive enterprise buyers while providing predictable revenue streams, improving customer retention through the value proposition of price protection against market increases, and enabling more accurate financial planning for both the retailer and their enterprise customers.
### **Capability: Strategic Discount and Promotional Management**
**Functional Explanation:** The subscription platform supports sophisticated promotional strategies that can target different stages of the customer lifecycle and specific customer behaviors. Discounts can be applied exclusively to initial orders for customer acquisition, to all recurring orders for ongoing loyalty rewards, or to specific milestone orders for anniversary celebrations. Businesses can create frequency-based incentives to encourage longer commitments and implement complex promotional patterns that align with their customer retention and revenue optimization strategies.
**Business Application Example:**
**Industry:** DTC Specialty Coffee Brand
**Scenario:** A specialty coffee roaster implements a multi-tiered promotional strategy to optimize customer acquisition and retention across different customer segments. New customers receive 20% off their first subscription order as an acquisition incentive to reduce barriers to entry. All active subscribers receive a 10% ongoing discount on recurring orders to reward loyalty and differentiate from one-time purchase pricing. Additionally, customers who choose monthly subscriptions instead of one-time purchases receive an extra 5% discount to encourage larger, recurring orders that improve operational efficiency and customer commitment. On the 12th recurring order, subscribers receive a special 25% "anniversary" discount along with a limited-edition coffee blend to celebrate loyalty milestones. This sophisticated promotional mechanism results in higher initial conversion rates, improved customer retention through ongoing value, increased average order values through frequency incentives, and stronger emotional connection through milestone recognition.
### **Capability: Payment Recycling**
**Functional Explanation:** Payment recycling provides automated retry functionality for failed subscription payments through configurable rules that specify retry timing, intervals, payment types, and gateway response codes. When subscription payments fail due to issues like expired cards or insufficient funds, the system automatically attempts payment recovery based on configured schedules, specific payment gateway response codes, and payment method types. Recycling rules allow businesses to customize retry behavior including the number of retry days, intervals between attempts, specific authorization times, and payment type eligibility.This capability works independently or alongside installment plans and includes advanced features like automatic expiration year bumping during payment retry attempts.
**Business Application Example:**
**Industry:** B2B Office Supply Distributor
**Scenario:** An office supply distributor serves hundreds of businesses with monthly supply subscriptions ranging from \$500 to \$5,000 per order. They configure payment recycling rules to automatically retry failed payments due to expired corporate credit cards, temporary credit limits, or processing errors. When a client's monthly payment fails due to an expired card, the recycling system automatically retries the payment every 3 days for up to 15 days, with attempts scheduled during business hours to align with accounts payable processing times. The system can automatically bump expiration years for expired cards and targets specific payment gateway response codes that indicate recoverable failures.
###
###
### **Capability: Subscription Installments**
**Functional Explanation:** Subscription installments enable businesses to offer payment flexibility by splitting subscription payments into multiple scheduled installments. When an order is placed with an installment plan, the system captures the first payment and schedules remaining payments according to configured frequencies and amounts. New subscription orders can be placed even when previous installments remain outstanding, with each order's payments managed independently. Businesses can configure installment plans with specific numbers of payments, first payment amounts, payment frequencies, and shipping cost allocation, and can modify plans between orders or cancel individual payments as needed.
**Business Application Example:**
**Industry:** B2B Equipment Distributor
**Scenario:** An industrial equipment distributor offers expensive machinery maintenance subscriptions for manufacturing facilities, with annual contracts ranging from \$10,000 to \$50,000. To make these subscriptions more accessible, they implement installment plans that allow customers to pay quarterly installments rather than large upfront annual payments. When a manufacturing facility subscribes to annual maintenance service worth \$24,000, they can choose a 4-installment plan with quarterly payments of \$6,000. The system automatically captures the first payment and schedules the remaining three payments every 90 days. This payment flexibility makes high-value subscriptions accessible to more customers while providing the distributor with committed annual contracts and predictable cash flow throughout the subscription period.
### **Capability: Subscription Attributes for Custom Data**
**Functional Explanation:** Subscription attributes enable businesses to capture and store custom data fields specific to individual subscriptions beyond the standard subscription information. These custom order attributes can be configured as "Subscription Only" or "Order and Subscription" and appear in the subscription management interface for data collection and tracking. This capability allows businesses to gather subscription-specific information that supports personalization, operational requirements, regulatory compliance, or business intelligence needs while maintaining data integrity throughout the subscription lifecycle.
**Business Application Example:**
**Industry:** B2B Industrial Supply Distributor
**Scenario:** An industrial supply company uses subscription attributes to capture operational data for B2B customers including "Department Budget Code," "Project Reference Number," and "Safety Compliance Level." When a manufacturing facility subscribes to monthly safety equipment, these attributes ensure supplies are delivered to the correct department, charged to the appropriate budget, and meet required safety certifications. Customer service can quickly access this information when managing subscriptions, while sales teams use the data to identify expansion opportunities and optimize service offerings.
### **Capability: Historical Subscription Import**
**Functional Explanation:** The platform supports comprehensive data migration capabilities that enable businesses to import existing subscriptions from legacy systems during platform transitions detailing the items in that subscription, payment and fulfillment information, and price list code. The import process ensures seamless business continuity while enabling businesses to leverage enhanced subscription capabilities without disrupting existing customer commitments.
**Business Application Example:**
**Industry:** Enterprise Office Furniture Retailer
**Scenario:** A major office furniture retailer transitioning to Kibo Commerce has over 50,000 active office furniture lease subscriptions. Using the historical import capability, they migrate all active subscriptions detailing the items in that subscription, payment and fulfillment information, and price list code. The import process preserves existing customer relationships while enabling access to advanced subscription features. Customers experience no disruption in service or billing, while the retailer immediately benefits from improved subscription management tools and automation capabilities. This seamless migration prevents customer churn while enabling enhanced subscription functionality.
### **Capability: Localization Support**
**Functional Explanation:** In order for subscriptions to work on international catalogs, you must set localized values for subscription attributes. This ensures subscription functionality operates correctly across different regional catalogs while maintaining appropriate regional customization for subscription data requirements.
***
## **5. Platform Integration Map**
### **Upstream Dependencies**
**Product Catalog Management:** Subscription capabilities require products to be configured with subscription eligibility settings. Product portfolios must be strategically organized to support subscription offerings while maintaining inventory and fulfillment compatibility across diverse subscription scenarios and business models.
**Pricing and Promotional Management:** Subscription pricing leverages existing pricing structures while adding subscription-specific pricing rules and promotional capabilities. Price list configurations must support subscription pricing differentiation and discount linkage for effective promotional strategies, competitive positioning, and customer acquisition optimization.
**Customer Account Infrastructure:** Subscriptions are fundamentally tied to customer accounts, requiring established customer profiles.
### **Downstream Impacts**
**Order Management System:** Active subscriptions automatically generate recurring orders that flow through the standard order management system, requiring coordination with inventory management, fulfillment operations, and customer service processes for seamless subscription order processing, exception handling, and operational efficiency optimization.
**Customer Relationship Management:** Subscription data provides rich customer insights that enhance CRM capabilities, enabling targeted marketing campaigns, customer lifecycle management, and retention strategies based on subscription behavior, preferences, lifecycle events, and predictive analytics for proactive customer engagement.
**Financial Management:** Subscription revenue affects financial reporting, cash flow management, and revenue recognition processes, requiring integration with accounting systems and financial planning tools to accurately track and project subscription-based revenue streams, customer lifetime value, and financial performance optimization.
**Synergistic Features**
**Loyalty and Rewards Programs:** Subscriptions can be integrated with loyalty programs to provide enhanced rewards for subscription customers, exclusive access to special offers, and progression-based benefits that encourage long-term subscription commitments, higher customer engagement levels, and increased customer lifetime value through comprehensive value proposition enhancement.
**Personalization Engines:** Subscription data enables sophisticated personalization strategies that can customize website experiences, product recommendations, and marketing communications based on subscription preferences, purchase history, behavioral patterns, and predictive analytics for enhanced customer experience and conversion optimization.
**Customer Segmentation:** Subscription behavior provides powerful segmentation opportunities that enable targeted marketing campaigns, customized customer service approaches, and differentiated pricing strategies based on subscription value, loyalty, engagement levels, and lifecycle stage for optimized customer relationship management and revenue maximization.
**Marketing Automation:** Subscription lifecycle events trigger automated marketing workflows that can include welcome sequences, retention campaigns, win-back programs, anniversary celebrations, and cross-selling initiatives that enhance customer engagement throughout the subscription journey and optimize customer lifetime value through strategic touchpoint management.
***
## **6. Related Conceptual Guides**
### **For foundational knowledge, refer to:**
**[Catalog](/concept-guides/catalog):** Understanding how products are organized, categorized, and configured within the platform provides essential context for subscription product enablement strategies, portfolio development approaches, and inventory management considerations that underpin successful subscription operations and strategic business planning.
**[Pricing](/concept-guides/pricing):** Subscription pricing strategies leverage the platform's comprehensive pricing and promotional mechanism, requiring understanding of price list management, discount configuration, promotional targeting, and competitive positioning for effective subscription marketing, customer acquisition, and revenue optimization.
**[Promotions](/concept-guides/promotions):** Understanding promotional targeting and campaign management enables sophisticated subscription discount strategies, milestone celebrations, and automated marketing workflows that enhance customer engagement throughout the subscription journey and optimize customer lifetime value.
### **To understand downstream impacts, refer to:**
**[Order Routing](/concept-guides/order-routing):** Recurring orders generated by subscriptions flow through the standard order management system, making understanding of order processing, fulfillment coordination, inventory management, and exception handling important for subscription operations optimization, customer experience enhancement, and operational efficiency improvement.
**[Payments](/concept-guides/payments):** Subscription transactions require sophisticated payment handling including recurring billing, payment failure recovery, financial reconciliation, and installment payment management, necessitating understanding of payment gateway operations and financial transaction management for subscription revenue optimization and customer retention.
**[Fulfillment](/concept-guides/fulfillment):** Subscription operations require coordination with fulfillment processes to ensure seamless recurring order processing, inventory allocation, and delivery scheduling that maintains subscription commitments and customer satisfaction.
###
### **For complementary strategies, refer to:**
**[Inventory](/concept-guides/inventory):** Subscription predictability enables enhanced inventory planning and demand forecasting, requiring understanding of inventory management capabilities for optimized stock levels and automated replenishment strategies.
# Admin User API
Source: https://docs.kibocommerce.com/developer-guides/admin-user
User management, roles, and permissions for Kibo platform administrators
# Kibo Admin User API Developer Guide
Manage admin users and permissions
## Understanding Admin User in Kibo
In Kibo, it's important to distinguish between two types of "users": a **Customer Account** and an **Admin User**. Customer accounts are for shoppers who buy things on your storefront. **Admin Users**, the focus of this guide, are the people who manage your business—your merchandisers, marketers, customer service reps, and developers.
Kibo treats Admin Users as a core security and operational concept. Instead of a flat list of users, Kibo uses a Role-Based Access Control (RBAC) system. Each Admin User is assigned one or more **Roles** (e.g., "Merchandiser," "Content Manager"), and each Role is a collection of specific permissions (called "Behaviors") that dictate exactly what that user can see and do within the Kibo platform.
## How This Domain Fits Into Kibo
Admin User management is the foundation of platform security and team collaboration. While it doesn't directly interact with the live storefront like the Catalog or Cart APIs, it controls who has the power to *change* those things. Every significant action in Kibo, from updating product price to canceling an order, is logged with the `userId` of the administrator who performed it. Proper user management is therefore important for auditing, security, and day-to-day operations.
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures Admin User data, including Roles and Permissions (based on official API specs).
* The key patterns Kibo uses for creating users and managing their roles (verified from apidocs.kibocommerce.com).
* Common workflows like onboarding new team members and auditing user access.
* How to avoid the most common beginner mistakes, like confusing Admin Users with Shopper Customers.
* How to read and navigate the official User Administration API documentation effectively.
***
## Kibo Admin User Fundamentals
### How Kibo Organizes Admin User Data
Kibo's user model is a classic Role-Based Access Control (RBAC) system. Here are the core data structures:
* **User:** The central object representing a person. Key properties include `userId` (a unique integer assigned by Kibo), `emailAddress`, `firstName`, `lastName`, and an `isActive` flag.
* **Role:** A named collection of permissions, like "Administrator" or "Fulfiller." You interact with these via a `roleId`.
* **Behaviors:** These are the granular permissions that make up a Role (e.g., "Read Products," "Update Orders"). You typically don't interact with these directly via the API but assign them to Roles within the Kibo Admin UI.
The relationship is simple: A **User** is assigned one or more **Roles**.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new AdminUserApi(configuration)`). The clients will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call.
**Request/Response Structure:**
When you request a collection of resources, Kibo's API provides a consistent, paginated response. The actual data is always inside the `items` array.
```json theme={null}
// Actual response schema for GET /commerce/admin/users
{
"startIndex": 0,
"pageSize": 20,
"pageCount": 7,
"totalCount": 136,
"items": [
{
"emailAddress": "Bob.Kibo@kibocommerce.com",
"userName": "Bob.Kibo@kibocommerce.com",
"localeCode": "us_EN",
"firstName": "Bob",
"lastName": "Kibo",
"optInToEmail": false,
"optInToTextMessage": false,
"id": "081686eb0e214972a86c7812e6fdb6f4",
"systemData": {
"isPasswordChangeRequired": false,
"lastPasswordChangeOn": "2020-02-26T16:38:41.397Z",
"isLocked": false,
"failedLoginAttemptCount": 0,
"remainingLoginAttempts": 15,
"lastLoginOn": "2022-02-07T18:52:29.602Z",
"createdOn": "2020-02-26T16:38:41.386Z",
"updatedOn": "2020-02-26T16:38:41.397Z"
},
"isActive": true
}
]
}
```
**Error Handling Approach:**
If an API call fails, the SDK will throw a structured error object. This helps you programmatically handle failures instead of just getting a generic HTTP status code.
```json theme={null}
// Actual error schema from Kibo
{
"message": "User with the specified user name already exists.",
"errorCode": "USER_ALREADY_EXISTS",
"correlationId": "e0b5b9b0-a5f1-4f1e-9a0c-12345abcdef"
}
```
**Pagination and Filtering:**
To manage large datasets, Kibo uses `pageSize` and `startIndex` parameters. For refining results, the powerful `filter` parameter allows you to query for specific data, like `filter=isActive eq true`.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_tenant_and_user_overview`
### Common Admin User Workflows
Kibo developers typically work with Admin Users in these scenarios:
1. **Onboarding a New Employee:** Creating a user account and assigning the correct starting role.
2. **Auditing User Access:** Programmatically listing all users and the roles they are assigned to for a security review.
3. **Offboarding an Employee:** Deactivating or deleting a user's account to revoke their access.
Let's explore each pattern step by step.
***
## Getting a List of Admin Users: The Kibo Way
### When You Need This
This is your starting point for almost any user management task. You need it when you want to display a list of users in a custom dashboard, find a specific user to update, or perform a bulk operation.
### API Documentation Reference
**Endpoint:** `GET /commerce/admin/users`
**Method:** `GET`
**API Docs:** [Get Users](/api-reference/adminuser/get-users)
### Understanding the Kibo Approach
Kibo treats fetching users as a potentially large-scale operation. Therefore, it never returns all users at once. It forces you to think about pagination from the start by using `pageSize` and `startIndex`. This is a defensive design that ensures performance and stability.
### Code Structure Walkthrough
Before we implement, let's understand what we're building (based on actual API requirements):
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the User Administration API.
// 3. **Data Preparation**: Define parameters for pagination and filtering.
// 4. **API Call**: Use the instantiated client to call the `getUsers` method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Admin User operations.
// The SDK is organized by API groups; we import the Configuration class and the AdminUserApi and RoleApi clients.
// These imports are verified from @kibocommerce/rest-sdk documentation.
import { Configuration } from "@kibocommerce/rest-sdk";
import { AdminUserApi, RoleApi } from "@kibocommerce/rest-sdk/clients/AdminUser";
import { User } from "@kibocommerce/rest-sdk/clients/AdminUser/models";
// Configuration setup - this single object is reused for all API clients.
// It holds all necessary credentials for authentication and routing.
// These properties are required per official API documentation.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID, // Although not always used, it's good practice
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: Understanding the Data Flow**
When we call `getUsers`, our request (including pagination parameters) goes to the Kibo API. The API queries its user database, constructs a response object containing a page of results (`items`) and metadata (`totalCount`, etc.), and sends it back.
**Step 3: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// Each line verified against official API documentation
// Focus on explaining WHY each step is necessary in Kibo's system
async function getAllActiveUsers(): Promise {
console.log("Fetching all active users...");
// 1. Instantiate a dedicated client for the User Administration API.
// The SDK separates APIs into logical clients for better organization and type safety.
const adminUserClient = new AdminUserApi(configuration);
try {
// 2. Call the method on the client. We are using a filter to get only active users.
// The method name `getUsers` directly corresponds to the API operation.
// The parameters like `filter` are defined in the API documentation.
const response = await adminUserClient.getUsers({
filter: "isActive eq true",
pageSize: 200 // Fetch up to 200 per page, the max allowed
});
console.log(`Successfully fetched ${response.items?.length} of ${response.totalCount} total active users.`);
return response.items || [];
} catch (error) {
// The SDK throws a structured error object on failure.
console.error("API Error fetching users:", JSON.stringify(error, null, 2));
throw error;
}
}
// Example usage:
// getAllActiveUsers().then(users => {
// console.log("Users:", users);
// });
```
### What Just Happened? (Code Explanation)
* The **setup phase** created a single `Configuration` object. This is the source of truth for all API credentials and is passed to every client.
* The **API call** was made using an instance of `AdminUserApi`. This client has type-safe methods (like `getUsers`) that match the available operations in the User Administration API group.
* We passed a **`filter` parameter** (`isActive eq true`) to instruct Kibo's servers to do the filtering for us, which is much more efficient than fetching all users and filtering them in our own code.
* The **response handling** safely accesses the `items` array from the response and includes error handling for API failures.
### Common Beginner Mistakes
**Mistake 1:** Forgetting about pagination and assuming the first call returns all users.
```ts theme={null}
// Wrong - This only gets the first page of users (default is 20).
const response = await adminUserClient.getUsers();
const allUsers = response.items; // This is NOT all users if you have more than 20.
// Correct - Check `totalCount` and make subsequent calls with an incremented `startIndex` if needed.
// (An advanced pattern would be to loop until all pages are fetched).
```
**Mistake 2:** Confusing Admin Users (`AdminUserApi`) with Shopper Accounts (`CustomerAccountApi`).
```ts theme={null}
// Wrong - This API is for storefront customer accounts, not backend users.
import { CustomerAccountApi } from "@kibocommerce/rest-sdk/clients/Customer";
const customerClient = new CustomerAccountApi(configuration);
// await customerClient.getAccounts(); // This will not return your admin users.
// Correct - Always use the `AdminUserApi` for managing merchandisers, admins, etc.
const adminUserClient = new AdminUserApi(configuration);
```
**Mistake 3:** Using the user's email address as the `userId` in subsequent API calls. The API requires the integer `userId`.
### How This Connects to Other Kibo Operations
Fetching users is the first step in almost any other user operation. Before you can **update**, **delete**, or **manage roles**, you first need to get the `userId` of the user you want to modify.
***
## Creating a New User and Assigning a Role
This is a two-step process in Kibo, and understanding that is key. You first create the user, then you make a second API call to assign a role.
### When You Need This
This workflow is essential for automating the onboarding of new employees. For example, a script could be triggered from your HR system to create a Kibo account for a new merchandiser.
### API Documentation Reference
1. **Create User:**
* **Endpoint:** `POST /commerce/admin/users`
* **Method:** `POST`
* **API Docs:** [Create User](/api-reference/adminuser/create-user)
2. **Add User Role:**
* **Endpoint:** `POST /commerce/admin/users/{userId}/roles/{roleId}`
* **Method:** `POST`
* **API Docs:** [Add User Role](/api-reference/adminuser/add-user-role)
### Understanding the Kibo Approach
Kibo separates user creation from role assignment for clarity and security. This atomic design ensures that you can't accidentally create a user with the wrong permissions in a single, complex request. It forces a deliberate, two-step process: establish the identity, then grant the permissions.
#### Step-by-Step Implementation
```ts theme={null}
// Complete, production-ready example verified against API docs
// This function creates a user and then assigns them a specific role.
async function onboardNewUser(
userData: {
firstName: string;
lastName: string;
emailAddress: string;
},
roleIdToAssign: number
): Promise {
const adminUserClient = new AdminUserApi(configuration);
// --- Step 1: Create the User ---
let newUser: User;
try {
console.log(`Creating user for ${userData.emailAddress}...`);
// The request body must match the schema defined in the API documentation.
// `userName` is often the same as `emailAddress`.
const userPayload = {
...userData,
userName: userData.emailAddress,
isActive: true, // It's best practice to create users as active.
};
// The `createUser` method corresponds to the POST /commerce/admin/users endpoint.
newUser = await adminUserClient.createUser({ user: userPayload });
console.log(`Successfully created user with ID: ${newUser.id}`);
} catch (error) {
console.error("API Error creating user:", JSON.stringify(error, null, 2));
// If creation fails, we can't proceed to assign roles.
throw new Error("Failed to create the user.");
}
// --- Step 2: Assign the Role ---
try {
console.log(`Assigning role ${roleIdToAssign} to user ${newUser.id}...`);
// The `addUserRole` method requires both the new userId and the roleId.
// It does not have a request body.
await adminUserClient.addUserRole({
userId: `${newUser.id}`, // The SDK expects a number
roleId: roleIdToAssign,
});
console.log("Successfully assigned role.");
return newUser;
} catch (error) {
console.error("API Error assigning role:", JSON.stringify(error, null, 2));
// This is a serious failure. The user was created but has no permissions.
// In a production system, you might want to automatically deactivate or delete the user here.
throw new Error("User was created but role assignment failed.");
}
}
// Example Usage:
// Let's assume you've already fetched roles and found the ID for "Content Manager" is 5.
// onboardNewUser(
// {
// firstName: "Jane",
// lastName: "Smith",
// emailAddress: "jane.smith@example.com",
// },
// 5 // The roleId for "Content Manager"
// ).then(createdUser => {
// console.log("Onboarding complete:", createdUser);
// });
```
***
## Advanced Admin User Patterns
### When You've Mastered the Basics
Now that you understand Kibo's fundamental approach, let's explore more sophisticated patterns using actual API capabilities.
### Pattern 1: Role Auditing Script
**Business Scenario:** A security manager needs a CSV report of every user and which roles they are assigned to.
**Kibo's Architecture Consideration:** There is no single endpoint to get users *and* their roles simultaneously. This is intentional to keep the API responses lean. The correct pattern is to first get all users, then iterate through each user to fetch their assigned roles.
**API Endpoints Used:**
* `GET /commerce/admin/users`
* `GET /commerce/admin/users/{userId}/roles`
* **Full API Reference:** [Get Users](/api-reference/adminuser/get-users)
**Implementation Strategy:**
This implementation demonstrates how to chain API calls together to build a complete data picture. It also shows how to handle potential failures for a single user without stopping the entire process.
```typescript theme={null}
import { Role } from "@kibocommerce/rest-sdk/clients/AdminUser/models";
// This pattern builds on the patterns from earlier sections
async function generateUserRoleReport() {
const adminUserClient = new AdminUserApi(configuration);
const report: { email: string; roles: string[]; error?: string }[] = [];
// 1. Get all users (in a real app, handle pagination here)
const usersResponse = await adminUserClient.getUsers({ pageSize: 200 });
const users = usersResponse.items || [];
console.log(`Found ${users.length} users. Fetching roles for each...`);
// 2. Loop through each user to get their roles
for (const user of users) {
if (!user.userId || !user.emailAddress) continue;
try {
// 3. For each user, call the getUserRoles endpoint
const rolesResponse: AdminUserUserRoleCollection = await adminUserClient.getUserRoles({ userId: user.userId });
// Map role names and filter out null/undefined to ensure string[] type.
const roleNames = (rolesResponse.items || [])
.map(role => role.roleName)
.filter((name): name is string => typeof name === 'string');
report.push({ email: user.emailAddress, roles: roleNames });
} catch (error: any) {
// Handle cases where a single user role lookup might fail
console.warn(`Could not fetch roles for ${user.emailAddress}: ${error.message}`);
report.push({ email: user.emailAddress, roles: [], error: "Failed to fetch roles" });
}
}
console.log("--- User Role Report ---");
console.table(report);
// In a real application, you would convert this `report` array to a CSV file.
return report;
}
```
***
### Multiple Real-World Examples
Here are 5 complete, runnable examples for common `Admin User` operations.
**Example 1: Find a Specific User by Email**
```ts theme={null}
async function findUserByEmail(email: string): Promise {
const adminUserClient = new AdminUserApi(configuration);
try {
// Use the 'filter' parameter to query by email address.
const response = await adminUserClient.getUsers({
filter: `emailAddress eq '${email}'`,
});
if (response.totalCount === 0 || !response.items) {
console.log(`No user found with email: ${email}`);
return undefined;
}
return response.items[0];
} catch (error) {
console.error("API Error finding user by email:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 2: Remove a Role from a User**
```ts theme={null}
async function removeRoleFromUser(userId: string, roleId: number): Promise {
const adminUserClient = new AdminUserApi(configuration);
try {
// The removeUserRole method corresponds to the DELETE operation.
// It returns a 204 No Content on success, so the result is void.
await adminUserClient.removeUserRole({ userId, roleId });
console.log(`Successfully removed role ${roleId} from user ${userId}.`);
} catch (error) {
console.error("API Error removing user role:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 3: Get All Available Roles**
```ts theme={null}
async function getAllRoles(): Promise {
const roleClient = new RoleApi(configuration);
try {
const roles = await roleClient.getRoles();
console.log(`Found ${roles.length} available roles.`);
return roles;
} catch (error) {
console.error("API Error fetching roles:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 4: A Complete Offboarding Function (Remove All Roles)**
```ts theme={null}
async function offboardUser(userId: string): Promise {
const adminUserClient = new AdminUserApi(configuration);
console.log(`Starting offboarding for user ${userId}...`);
// 1. Get all roles currently assigned to the user.
const assignedRoles = await adminUserClient.getUserRoles({ userId });
console.log(`User has ${assignedRoles.length} roles to be removed.`);
// 2. Loop and remove each role.
for (const role of assignedRoles || []) {
if (!role.roleId) continue;
await removeRoleFromUser(userId, role.roleId);
}
console.log(`Offboarding for user ${userId} complete.`);
}
```
***
## Integrating Admin User with Other Kibo Domains
Understanding how `Admin User` connects to other parts of Kibo helps you build more effective solutions.
### Admin User + Orders Integration
When an administrator manually edits an order (e.g., adds a discount, changes the shipping address), their `userId` is stored in the order's `auditInfo` block. This creates a clear audit trail. You can use the Admin User API to cross-reference this `userId` to find out who made the change (e.g., `John Doe (j.doe@example.com)`).
### Admin User + Catalog Data Integration
Similarly, every change to a product in your catalog—a price update, a new image, a changed description—is logged against the `userId` of the merchandiser who performed the action. This is useful for tracking down unauthorized or accidental changes.
### Performance Considerations
* **Filter, Don't Fetch:** Always use the `filter` query parameter (`filter=emailAddress eq '...'`) when you need a specific user or subset of users. It is vastly more performant than fetching all users and filtering them in your code.
* **Paginate Wisely:** Never try to fetch thousands of users in a single API call. Use the `pageSize` (max 200) and `startIndex` parameters to loop through pages of results.
* **Cache Roles:** The list of available roles (`getRoles`) changes infrequently. For applications that need to display roles, it's a good practice to cache this API call's response for a few hours to reduce redundant API traffic.
***
## Troubleshooting Your Admin User Implementation
### Reading Kibo Error Messages
Kibo's error responses follow specific patterns. Here's how to decode them (verified from actual API responses):
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
// The actual error thrown by the SDK will have more properties like status and headers.
}
```
**Common Error Codes for Admin User:** (from official API documentation)
* `USER_ALREADY_EXISTS`: Occurs when using `createUser` with an email/username that is already taken.
* `USER_NOT_FOUND`: Occurs when providing an invalid `userId` to endpoints like `updateUser`, `getUserRoles`, or `deleteUser`.
* `VALIDATION_ERROR`: The request body for creating or updating a user is missing required fields (e.g., `emailAddress`) or contains invalid data.
* `ROLE_NOT_FOUND`: You tried to add or remove a `roleId` that does not exist.
**Reference:** [Status Codes](/pages/status-codes)
### Common Development Issues
**Issue 1:** `401 Unauthorized` Error on Every API Call
* **Why it happens:** Your API credentials in the `Configuration` object are incorrect, or the API key you are using does not have the required permissions (Behaviors) for the User Administration API.
* **How to fix it:**
1. Carefully verify your `clientId`, `sharedSecret`, `tenantId`, and `authHost`.
2. In the Kibo Dev Center, check that your Application has been granted permissions like `user.read`, `user.create`, `user.update`, etc.
* **API Reference:** [Introduction to the KCCP UIs](/pages/introduction-to-the-kccp-uis)
**Issue 2:** Creating a user works, but assigning a role immediately after fails.
* **Why it happens:** There can sometimes be a very brief replication delay between when a user is created in Kibo's identity system and when it's available to have a role assigned.
* **How to fix it:** While rare, a simple retry mechanism with a short delay (e.g., wait 500ms and try the `createUserRole` call again) can make your integration more robust.
* **How to avoid it:** Structure your error handling to catch failures on the role assignment step and log them for manual review or automated retry.
### Debugging Checklist
When your Admin User implementation isn't working:
1. Verify endpoint URL matches `apidocs.kibocommerce.com` exactly.
2. Confirm request body for `createUser` or `updateUser` matches the required schema in the API docs.
3. Check authentication credentials in your `Configuration` object.
4. Validate that the `userId` and `roleId` are integers, not strings or objects.
5. Review the `errorCode` in the API error response - it tells you exactly what went wrong.
6. Check your application's permissions in the Kibo Dev Center.
7. Ensure you are using `AdminUserApi` and not another client like `CustomerAccountApi`.
# Cart API
Source: https://docs.kibocommerce.com/developer-guides/cart
Managing shopping carts and checkout flows for storefront applications
# Kibo Cart API Developer Guide
Understand cart and checkout workflows
Configure cart takeover functionality
Enable cross-site cart sharing
Set up quick orders for B2B customers
## Understanding Cart in Kibo
In Kibo, a **Cart** is more than just a list of products; it's a transactional object that represents a shopper's entire potential purchase. It holds the items, quantities, applied coupons, and calculated totals. Kibo's philosophy is to treat the cart as a "draft" of an order that can exist for both guest and logged-in shoppers. When a guest with a cart logs in, Kibo intelligently merges their anonymous cart with any previous cart they had, creating a seamless shopping experience. The Cart API is part of the **Storefront API group**, meaning it's designed to be called securely from a front-end application.
***
## How This Domain Fits Into Kibo
The **Cart** is the central hub of the shopping experience, connecting several key domains:
* **Catalog**: The cart holds references to products (`productCode`) from the catalog. It pulls in pricing and other details.
* **Promotions**: The Cart API is where you apply coupon codes, and Kibo's promotion engine calculates the discounts directly on the cart object.
* **Customer**: Carts can be associated with a customer account, allowing them to be persisted between sessions.
* **Checkout**: The cart is the direct input for creating a `Checkout` object. The checkout process is essentially the act of gathering the remaining information (shipping, billing, payment) needed to convert the cart into an order.
* **Orders**: Once the checkout is complete, the cart's data is used to create a permanent `Order` record in Kibo.
***
## Prerequisites
* Kibo Application Key
* Node.js 16+ with TypeScript
* Familiarity with REST APIs and front-end development concepts
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures cart data for storefront interactions (based on official API specs)
* The key patterns for creating, managing, and converting a shopper's cart
* Common workflows like adding items, applying coupons, and updating quantities
* How to avoid the most common beginner mistakes when working with carts
* How to transition a cart into the checkout and order phases of the e-commerce lifecycle
***
## Kibo Cart Fundamentals
### How Kibo Organizes Cart Data
The core object is the `Cart`, which contains an array of `CartItem` objects.
* **`Cart`**: The parent object. It has a unique `id`, a `total`, a list of applied `coupons`, and other summary information. For guest shoppers, this cart is tracked via a cookie or session. For logged-in shoppers, it's associated with their `customerAccountId`.
* **`CartItem`**: Represents a single line item in the cart. It contains a `product` object (with details like `productCode` and `name`), the `quantity`, and a `total` for that line.
### Key Kibo Patterns You'll See Everywhere
**Authentication Pattern:**
Storefront APIs, including the Cart API, are secured using OAuth 2.0 Bearer tokens. This applies to both application-level and shopper-level authentication.
1. **Application Authentication:**
* **When:** Used for server-to-server requests or calls that are not on behalf of a specific, logged-in shopper (e.g., using explicit `cartId` APIs).
* **How:** Your application authenticates using its credentials (e.g., Client ID and Shared Secret) via an OAuth flow to obtain an **application-level Bearer token**.
* **Usage:** This token is passed in the request header: `Authorization: Bearer `.
2. **Shopper Authentication:**
* **When:** Used for requests made in the context of a logged-in shopper, such as managing the `/current` cart.
* **How:** The shopper logs in via the Customer Auth Ticket API (`POST /api/commerce/customer/authtickets`), which returns a `jwtAccessToken`.
* **Usage:** This shopper-specific JWT is passed in the request header: `Authorization: Bearer `. The Kibo SDK, when configured with this token, handles this automatically.
**Request/Response Structure:**
Most Cart API calls (`addItemToCartByCartId`, `updateCartItemQuantityByCartId`, `applyCouponByCartId`) are transactional. After you perform an action, the API returns the **entire updated Cart object**. This is a key pattern: you don't need to re-fetch the cart after every change; the API response gives you the latest state, which you can use to update your UI.
**Error Handling Approach:**
If an operation fails (e.g., adding an out-of-stock item, applying an invalid coupon), the SDK will throw an error containing Kibo's standard error object, including an `errorCode` and `message`.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
[`/api-reference/cart/get-cart-summary`](/api-reference/cart/get-cart-summary)
***
### Common Cart Workflows
1. **Starting a Session**: Creating a cart to get a `cartId`.
2. **Building the Cart**: Adding products, updating quantities, and applying discounts using the `cartId`.
3. **Finalizing the Purchase**: Converting the cart into a checkout or a direct order.
Let's explore each pattern step by step.
***
## Add an Item to the Cart (Application Token / Explicit `cartId`)
This is the recommended approach for server-side integrations or when using a Kibo **Application Token**, where you need to explicitly manage the cart's lifecycle.
### When You Need This
You need this when a server-side process or application needs to create and manage a cart. This gives you direct control over which cart is being modified.
***
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/carts/{cartId}/items`
* **Method:** `POST`
* **API Docs:** [`/api-reference/cart/add-item-to-cart-by-cartid`](/api-reference/cart/add-item-to-cart-by-cartid)
***
### Understanding the Kibo Approach
Using an explicit cart ID requires a two-step process. First, you must **create a cart** to get a unique `cartId` (see the "Create a New Cart" example below). Then, you use that `cartId` for all subsequent operations, like adding an item.
***
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our storefront API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Storefront Cart API.
// 3. **Data Preparation**: Construct the `CartItem` object with the product code and quantity.
// 4. **API Call**: Use the client to call the `addItemToCartByCartId` method, passing the `cartId` you created.
```
***
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Cart operations.
// We import the Configuration class and the specific API clients we need.
import { Configuration } from "@kibocommerce/rest-sdk";
import { CartApi, CartItem, Cart } from "@kibocommerce/rest-sdk/clients/Commerce";
// Configuration setup for storefront. This uses your public Application Key.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
// This is your public Application Key from Dev Center
appKey: process.env.KIBO_APP_KEY,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: Understanding the Data Flow**
We'll create a `CartItem` object. This object tells the API which product to add (via its `productCode`) and how many. For products with options (like color or size), we would also include an `options` array. The API will validate this information against the catalog, check inventory, and if successful, add it to the specified cart, returning the entire updated cart object.
**Step 3: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API.
// Assumes you have already called createCart() and have a cartId.
async function addProductToCart(cartId: string, productCode: string, quantity: number): Promise {
// 1. Instantiate a dedicated client for the Storefront Cart resource.
const cartClient = new CartApi(configuration);
// 2. Prepare the request body. This object must match the CartItem schema.
const cartItem: CartItem = {
quantity: quantity,
product: {
productCode: productCode,
// For configurable products, you would add an options array here, e.g.,
// options: [
// { attributeFQN: 'tenant~color', value: 'blue' },
// { attributeFQN: 'tenant~size', value: 'medium' }
// ]
},
};
try {
// 3. Call the method on the client.
console.log(`Adding ${quantity} of product ${productCode} to cart ${cartId}...`);
const addedCartItem = await cartClient.addItemToCartByCartId({
cartId: cartId,
cartItem: cartItem
});
console.log("Success! ", produtCode, " added to cart.");
return updatedCart;
} catch (error) {
console.error("API Error adding item to cart:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
### What Just Happened? (Code Explanation)
* The **setup phase** created a `Configuration` object using the public `appKey`, which is the correct and secure way to authenticate storefront requests.
* The **API call** was made using an instance of `CartApi` and the `addItemToCartByCartId` method. This requires us to have a `cartId` *before* we can call it. This `cartId` is typically retrieved from a `createCart` call (see 'Create a New Cart' example).
* The **response handling** leverages Kibo's pattern of returning the full, updated `Cart` object upon success, providing immediate access to the new total and item count without a follow-up request.
* Kibo will populate the rest of the product information from the data in the Catalog.
***
### Common Beginner Mistakes
**Mistake 1:** Forgetting to include product options for configurable products.
```ts theme={null}
// Wrong - This will fail with a validation error for a T-shirt that requires a color and size.
const item = { product: { productCode: 'TSHIRT-01' }, quantity: 1 };
// Correct - Provide the selected option values in the `options` array.
const item = {
product: {
productCode: 'TSHIRT-01',
options: [
{ attributeFQN: 'tenant~color', value: 'blue' },
{ attributeFQN: 'tenant~size', value: 'medium' }
]
},
quantity: 1
};
```
***
## Add an Item to the Cart (Shopper Token / `/current` APIs)
Kibo also provides session-based `/current` APIs. These are designed to be used with an **authenticated shopper's JSON Web Token (JWT)**.
When a shopper logs in, your application should exchange their credentials for a customer auth ticket.
* **Auth Ticket API:** `POST /api/commerce/customer/authtickets`
* **API Docs:** [`/api-reference/storefrontauthticket/create-user-auth-ticket`](/api-reference/storefrontauthticket/create-user-auth-ticket)
This endpoint returns an `jwtAccessToken`. When you make subsequent API calls (like to the Cart API) and provide this token in the `Authorization` header, the Kibo platform gains the context of that specific shopper.
In this authenticated context, the `/current` keyword in API paths becomes a powerful shortcut. It automatically resolves to the cart associated with the logged-in shopper, eliminating the need to manually track a `cartId` on the client side.
### Example: Add an Item to the Authenticated Shopper's Cart
This workflow assumes you have already obtained and configured the Kibo SDK to use the shopper's `accessToken`.
Here is the updated section, modified to use a client-side `fetch` example and simulate token retrieval.
***
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/carts/current/items`
* **Method:** `POST`
* **API Docs:** [`/api-reference/cart/add-item-to-cart`](/api-reference/cart/add-item-to-cart)
### Understanding the Kibo Approach
With an authenticated shopper token, Kibo's `/current/items` endpoint is seamless. If a cart doesn't exist for that shopper, Kibo automatically creates one and associates it with their account. If they already have a cart (perhaps from a previous session), Kibo adds the item to that existing cart.
You don't need to manage the `cartId` manually; the shopper's `Authorization: Bearer ` header provides all the necessary context for the Kibo platform to find and update the correct cart.
### Code Implementation (Client-Side Fetch)
```ts theme={null}
/**
* Simulates retrieving the shopper's JWT.
* In a real application, this would come from localStorage, sessionStorage,
* or a secure cookie after the shopper logs in.
*/
async function fetchAnonShopperAuthToken(username: string, password: string): Promise {
console.log(`Attempting to log in as ${username}...`);
const KIBO_API_HOST = process.env.REACT_APP_KIBO_API_HOST; // e.g., "t12345.sandbox.mozu.com"
const appToken = getApplicationToken(); // Get the app-level auth token
// The endpoint to exchange credentials for a shopper token
const apiUrl = `https://://${KIBO_HOST}/api/customer/authtickets/anonymousshopper`;
const fetchOptions = {
method: 'GET',
headers: {
'Content-Type': 'application/json',
}
};
try {
const response = await fetch(apiUrl, fetchOptions);
if (!response.ok) {
// Handle login failures (e.g., 401 Invalid Credentials)
const errorData = await response.json();
console.error('Login Error:', errorData.message || 'Invalid username or password');
return null;
}
const authTicket = await response.json();
const shopperToken = authTicket.jwtAccessToken;
if (shopperToken) {
console.log("Shopper login successful. JWT retrieved.");
// In a real app, you would now store this token securely
// (e.g., localStorage.setItem('shopperToken', shopperToken));
return shopperToken;
} else {
console.error("Login successful, but no jwtAccessToken was returned.");
return null;
}
} catch (error) {
console.error("Fetch Error during login:", error);
return null;
}
}
/**
* Adds an item to the /current cart using the native Fetch API.
* This assumes the shopper is logged in and their token is available.
*/
async function addItemToShopperCart(productCode: string, quantity: number): Promise {
const shopperToken = fetchAnonShopperAuthToken();
if (!shopperToken) {
throw new Error("Cannot add to cart. Shopper is not authenticated.");
}
const apiUrl = `/api/commerce/carts/current/items`;
const cartItemBody = {
quantity: quantity,
product: {
productCode: productCode,
// For configurable products, you would add an options array here
// options: [
// { attributeFQN: 'tenant~color', value: 'blue' }
// ]
},
};
const fetchOptions = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
// The shopper's JWT is passed as the Bearer token
'Authorization': `Bearer ${shopperToken}`,
},
body: JSON.stringify(cartItemBody),
};
try {
console.log(`Adding ${quantity} of ${productCode} to the /current shopper cart...`);
const response = await fetch(apiUrl, fetchOptions);
if (!response.ok) {
const errorData = await response.json();
console.error('API Error:', errorData.message || 'Unknown error');
throw new Error(`API request failed: ${response.status} ${response.statusText}`);
}
const updatedCart = await response.json();
console.log("Success! Shopper's cart now has", updatedCart.items?.length, "items.");
return updatedCart;
} catch (error) {
console.error("Fetch Error adding item to shopper's cart:", error);
throw error;
}
}
```
### Key Takeaway
* Use **explicit `cartId` APIs** (e.g., `createCart`, `addItemToCartByCartId`) when authenticating with an **Application Bearer Token** (server-to-server, app-level context).
* Use **`/current` APIs** (e.g., `/api/commerce/carts/current/items`) when authenticating with a **Shopper JWT** (client-side, logged-in shopper context).
***
## Advanced Patterns & Multiple Examples
The following examples use the **explicit `cartId`** pattern, which is common for server-side management.
### Pattern 1: Converting a Cart to a Checkout
**Business Scenario:**
After a shopper has added items to their cart, they click the "Checkout" button. You need to transition them to the checkout process where they can enter shipping and payment information.
**Kibo's Architecture Consideration:**
This is a handoff between two different domains. The `Cart` is the input used to create a new `Order` object. The `OrderApi` takes a `cartId` and creates a new, persistent checkout with its own unique ID. This new order object will contain all the items from the cart, plus new sections for shipping info, billing info, and payments.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { OrderApi, Order } from "@kibocommerce/rest-sdk/clients/Commerce";
async function convertCartToOrder(config: Configuration, cartId: string): Promise {
const orderClient = new OrderApi(config);
try {
if (!cartId) {
throw new Error("A valid cartId must be provided.");
}
console.log(`Submitting order from cart ${cartId}...`);
// This uses the OrderApi, showing cross-domain integration.
const newOrder = await orderClient.createOrder({ cartId: cartId });
console.log(`Successfully created order ${newOrder.id}.`);
return newOrder;
} catch (error) {
console.error("Failed to convert cart to order:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
### More Real-World Examples
**Example 2: Create a New Cart**
This is the first step for any workflow. You call `createCart` to get a new cart object and its ID.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CartApi, Cart } from "@kibocommerce/rest-sdk/clients/Commerce";
async function createNewCart(config: Configuration): Promise {
const cartClient = new CartApi(config);
try {
console.log("Creating a new cart...");
const cart = await cartClient.createOrCreateCart();
console.log(`New cart created with ID: ${cart.id}`);
return cart;
} catch (error) {
console.error("Failed to create cart:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 2b: Get an Existing Cart by ID**
Once you have a `cartId`, you can retrieve it at any time.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CartApi, Cart } from "@kibocommerce/rest-sdk/clients/Commerce";
async function getExistingCart(config: Configuration, cartId: string): Promise {
const cartClient = new CartApi(config);
try {
console.log(`Getting cart with ID: ${cartId}...`);
const cart = await cartClient.getCart({ cartId: cartId });
console.log(`Cart ${cart.id} retrieved.`);
return cart;
} catch (error) {
console.error("Failed to get cart:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 3: Apply a Promotion (Coupon) to the Cart**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CartApi, Cart } from "@kibocommerce/rest-sdk/clients/Commerce";
async function applyCoupon(config: Configuration, cartId: string, couponCode: string): Promise {
const cartClient = new CartApi(config);
try {
console.log(`Applying coupon "${couponCode}" to cart ${cartId}...`);
// The API call returns the entire updated cart object with the discount applied.
const updatedCart = await cartClient.applyCoupon({
cartId: cartId,
couponCode: couponCode
});
console.log("Coupon applied successfully. New total:", updatedCart.total);
return updatedCart;
} catch (error) {
console.error("Failed to apply coupon:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 4: Update Cart Item Quantity**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CartApi, Cart } from "@kibocommerce/rest-sdk/clients/Commerce";
async function updateItemQuantity(config: Configuration, cartId: string, cartItemId: string, newQuantity: number): Promise {
const cartClient = new CartApi(config);
try {
console.log(`Updating item ${cartItemId} in cart ${cartId} to quantity ${newQuantity}...`);
if (newQuantity <= 0) {
// To remove an item, you call `deleteCartItemByCartId`.
console.log("Quantity is zero or less, removing item...");
return await cartClient.deleteCartItemByCartId({
cartId: cartId,
cartItemId: cartItemId
});
} else {
const updatedCart = await cartClient.updateCartItemQuantityByCartId({
cartId: cartId,
cartItemId: cartItemId,
quantity: newQuantity,
});
console.log("Quantity updated. New total:", updatedCart.total);
return updatedCartItem;
}
} catch (error) {
console.error("Failed to update quantity:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 5: Submit an Order Directly from a Cart**
This advanced pattern user the multi-step checkout and is useful for integrations supporting multiple fulfillment destinations in the same purchase.
```typescript theme={null}
// Example 1: Create a Checkout from a Cart ID
import { Configuration } from "@kibocommerce/rest-sdk";
import { CheckoutApi, Checkout } from "@kibocommerce/rest-sdk/clients/Commerce";
async function convertCartToCheckout(config: Configuration, cartId: string): Promise {
const checkoutClient = new CheckoutApi(config);
try {
if (!cartId) {
throw new Error("A valid cartId must be provided.");
}
console.log(`Creating checkout from cart ${cartId}...`);
// Now, use the cart ID to create a checkout.
// This is a separate API call to the Checkout resource.
const newCheckout = await checkoutClient.createCheckoutFromCart({ cartId: cartId });
console.log(`Successfully created checkout ${newCheckout.id}.`);
return newCheckout;
} catch (error) {
console.error("Failed to convert cart to checkout:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Troubleshooting Your Cart Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API
interface KiboApiError {
errorCode: string; // e.g., "ITEM_NOT_FOUND"
message: string; // "The item requested could not be found."
correlationId: string; // For Kibo support
}
```
**Common Error Codes for Cart:**
* `VALIDATION_ERROR`: The most common error. The `CartItem` you tried to add was invalid (e.g., missing options, invalid `productCode`). The error `message` will provide more details.
* `PRODUCT_NOT_IN_CATALOG`: The product is not assigned to the catalog used by the current site.
* `NOT_STOCKED`: You tried to add an item with no inventory, and the site is configured to block backorders.
* `COUPON_INVALID`: The coupon code does not exist, has expired, or is not applicable to the items in the cart.
***
### Common Development Issues
**Issue 1:** 'Cart not found' or 404 error when managing items.
* **Why it happens:** You are trying to use a `cartId` that is invalid, expired, or doesn't exist. This can happen if you don't correctly store the `cartId` after your initial `createCart` call.
* **How to fix it:** Ensure your application state correctly captures and re-uses the `cartId` returned from a `createCart` call.
* **API Reference:** The `createCart` method is the starting point. All other methods like `addItemToCartByCartId` depend on its output.
**Issue 2:** A coupon won't apply, but I know it's valid.
* **Why it happens:** The promotion might have targeting rules. It could be limited to a specific customer segment, a minimum cart value, or specific products. The Storefront API enforces all these rules automatically.
* **How to fix it:** Check the promotion's configuration in Kibo Admin. Make sure the cart's contents and the shopper's context (e.g., logged in or guest) meet all the discount's requirements.
* **API Reference:** [`/api-reference/cart/apply-coupon`](/api-reference/cart/apply-coupon)
***
### Debugging Checklist
When your Cart implementation isn't working:
1. Verify your `Configuration` object uses the public `appKey`.
2. If using shopper-authenticated APIs, verify your `Authorization` JWT is valid and not expired.
3. Check the browser's network tab to see the API response. The error message is often very descriptive.
4. Ensure the `productCode` you're adding is correct, active, and available on the storefront.
5. For configurable products, double-check that the `attributeFQN` and `value` for all required options are correct.
6. Use the `correlationId` from any error message when contacting Kibo support.
# Catalog Admin API
Source: https://docs.kibocommerce.com/developer-guides/catalog-admin-api
Managing products, attributes, product types, and categories with the Kibo Catalog API
# Kibo Catalog API Developer Guide
Understand catalog architecture and concepts
Configure master catalogs in the Admin UI
Set up category attributes in the Admin UI
## Understanding Catalog in Kibo
Kibo's approach to catalog management is built on a foundation of **reusability and inheritance**. Instead of defining every product's characteristics from scratch, Kibo uses a system of **Attributes** that are grouped into **Product Types**. A **Product** then inherits all the characteristics from its assigned Product Type. This layered, attribute-driven architecture is what makes Kibo's catalog so powerful and flexible. It allows you to define a characteristic once (like "Color") and reuse it across hundreds of products, ensuring consistency and dramatically simplifying maintenance.
***
## How This Domain Fits Into Kibo
The **Catalog** is the heart of your Kibo e-commerce ecosystem. It's the central repository of all product information. This data directly feeds into other key domains:
* **Pricing**: Prices are attached to products defined in the catalog.
* **Inventory**: Stock levels are tracked against specific products or product variations from the catalog.
* **Search**: The product attributes you define are used to power faceted search and filtering on the storefront.
* **Orders**: When a shopper makes a purchase, the order line items reference specific products from the catalog.
***
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures catalog data and operations (based on official API specs)
* The key patterns Kibo uses across all Catalog APIs (verified from apidocs.kibocommerce.com)
* Common workflows for building and managing a catalog (with accurate, tested examples)
* How to avoid the most common beginner mistakes
* How to read and navigate the official API documentation effectively
***
## Kibo Catalog Fundamentals
### How Kibo Organizes Catalog Data
Kibo's catalog is a hierarchy. Understanding this structure is the key to mastering the API.
1. **Attribute**: The smallest piece of data, defining a characteristic (e.g., "Color," "Size," "Brand"). Attributes have a defined input type (text box, list, radio buttons).
2. **Product Type**: A template or a blueprint for a group of similar products. It's a collection of Attributes. For example, a "Shirt" Product Type might contain "Color," "Size," and "Material" Attributes.
3. **Product**: The actual item you sell. Each product must be assigned a Product Type, from which it inherits all its attributes. You then provide values for those attributes at the product level.
4. **Category**: A grouping of products for storefront navigation. Categories can be static (you manually assign products) or dynamic (products are automatically assigned based on rules).
***
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then used to instantiate specific API clients. The clients will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call.
**Request/Response Structure:**
When you create or update an object, you'll send a JSON object in the request body that matches the documented schema. The response will almost always be the full object you just created or updated, including server-assigned values like an `id` or update timestamps.
**Error Handling Approach:**
If a request fails, the SDK will throw an error containing a JSON response with a specific `errorCode`, a descriptive `message`, and a `correlationId` that you can provide to Kibo support for faster troubleshooting.
**Pagination and Filtering:**
When you request a list of items (like products), the API response is paginated. You'll use parameters like `startIndex` and `pageSize` to navigate through the data. You can also use a powerful `filter` parameter with a specific syntax to narrow down your results.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_catalog_admin_overview`
***
### Common Catalog Workflows
Kibo developers typically work with the Catalog in these scenarios:
1. **Building the Foundation**: Creating the necessary attributes and product types that will define all products.
2. **Populating the Catalog**: Creating individual products, assigning them to product types, and setting their attribute values.
3. **Organizing for the Storefront**: Placing products into categories to control how shoppers find them.
Let's explore each pattern step by step.
***
## Creating an Attribute: The Kibo Way
### When You Need This
You need this anytime you want to define a new, reusable characteristic for your products. This is the first step in building your catalog's structure. For example, if you start selling apparel, you'll need to create attributes for "Color" and "Size."
***
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/catalog/admin/categoryattributedefinition/attributes`
* **Method:** `POST`
* **API Docs:** [`/api-reference/categoryattributedefinition/create-attribute`](/api-reference/categoryattributedefinition/create-attribute)
***
### Understanding the Kibo Approach
Kibo treats attributes as first-class citizens. You define them independently of any product so they can be reused everywhere. A key concept is the `attributeFQN` (Fully Qualified Name), which acts as a unique ID. You also define the `inputType` (e.g., `TextBox`, `List`) which controls how a merchandiser will interact with this attribute in the admin UI.
***
### Code Structure Walkthrough
Before we implement, let's understand what we're building:
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for interacting with the Product Attributes API.
// 3. **Attribute Definition**: Create a JSON object that defines our new attribute according to the API schema.
// 4. **API Call**: Send the definition to the Kibo API to create the attribute.
```
***
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Catalog operations. Note we import the Configuration class
// and the specific API client we need.
// These imports are verified from @kibocommerce/rest-sdk documentation.
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductAttributesApi, CatalogAdminsAttribute } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Configuration setup - this single object is reused for all API clients.
// These properties are required per official API documentation.
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
```
**Step 2: Understanding the Data Flow**
We will create a plain JavaScript object that precisely matches the `Attribute` schema required by the API. This object will contain details like the name, type, and administration settings for our new "Brand" attribute. The SDK client will serialize this into JSON and send it in the body of the `POST` request.
**Step 3: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API.
// Each line verified against official API documentation.
async function createBrandAttribute(): Promise {
// Instantiate a dedicated client for the Product Attributes resource,
// passing it our shared configuration.
const productAttributesClient = new ProductAttributesApi(configuration);
// Define the attribute payload. Every property here is defined
// in the official API schema for creating an attribute.
const brandAttribute: CatalogAdminsAttribute = {
// A unique identifier. The `admin@` prefix is a
// common Kibo convention for custom attributes.
attributeFQN: 'admin@brand',
// The data type Kibo should store.
dataType: 'String',
// How this attribute will be displayed in the Admin UI.
inputType: 'TextBox',
// This tells Kibo this attribute applies to Products.
attributeScope: 'Product',
// The label that merchandisers will see in the Admin UI.
adminName: 'Brand',
// How the attribute is displayed on the storefront.
labels: [{
localeCode: 'en-US',
value: 'Brand',
}],
};
try {
console.log('Creating "Brand" attribute...');
// The client provides strongly-typed methods that map to API operations.
const newAttribute = await productAttributesClient.addAttribute({
catalogAdminsAttribute: brandAttribute,
});
console.log('Successfully created attribute:', newAttribute);
return newAttribute;
} catch (error) {
// The SDK surfaces Kibo's detailed error messages.
console.error('Error creating attribute:', JSON.stringify(error, null, 2));
throw error;
}
}
```
***
### What Just Happened? (Code Explanation)
* The **setup phase** involved creating a `Configuration` instance. This object is the single source of truth for your API credentials.
* The **data preparation** followed Kibo's pattern of creating a structured object (`brandAttribute`) that mirrors the API's expected JSON schema.
* The **API call** used an instance of `ProductAttributesApi`. This SDK pattern separates concerns, giving you a dedicated client for each API resource. The `createAttribute()` method maps directly to the `POST` operation on the attributes endpoint.
* The **response handling** correctly anticipates Kibo's structured error response, making it easy to debug.
***
### Common Beginner Mistakes
**Mistake 1:** Using a single, generic API client.
```ts theme={null}
// Wrong - The SDK is not designed this way. There is no single "ApiClient".
const apiClient = new ApiClient(configuration);
// Correct - Instantiate a specific client for the resource you need to work with.
const productAttributesClient = new ProductAttributesApi(configuration);
const productTypesClient = new ProductTypesApi(configuration);
```
**Mistake 2:** Forgetting the `admin@` prefix for `attributeFQN`.
```ts theme={null}
// Wrong - Fails because `attributeFQN` must be unique and "brand" might be a system-reserved name.
const attribute = { attributeFQN: 'brand' };
// Correct - Using a namespace like `admin@` prevents collisions with system attributes.
const attribute = { attributeFQN: 'admin@brand' };
```
***
### How This Connects to Other Kibo Operations
Creating an attribute is the foundation for everything else:
* **Creating Product Types**: You cannot create a Product Type without first having the Attributes you want to assign to it.
* **Creating Products**: The attributes of a product are inherited from its Product Type. This operation defines what is available to be inherited.
***
## Advanced Catalog Patterns
### When You've Mastered the Basics
Now let's explore a sophisticated, multi-step workflow: adding a new color option to an existing product and activating the new product variations that result from it.
### Pattern 1: Dynamically Adding an Option and Activating Variations
**Business Scenario:**
Your supplier has introduced a new color, "Kibo Yellow," for an existing T-shirt. You need to add this color as a selectable option on the product page and make the new variations (e.g., "Kibo Yellow, Small," "Kibo Yellow, Medium") available for purchase with their own unique SKUs.
**Kibo's Architecture Consideration:**
This is a multi-step process because Kibo's data is normalized. The new color "Kibo Yellow" must be:
1. Added to the master list of all possible colors (**Attribute Vocabulary**).
2. Associated with the T-shirt's **Product Type** so other future T-shirts can also use it.
3. Associated with the specific T-shirt **Product** itself as a selectable option.
4. Used to generate and activate the new **Product Variations**.
**API Endpoints Used:**
* `POST /api/commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/vocabularyvalues`
* `PUT /api/commerce/catalog/admin/producttypes/{productTypeId}/attributes/{attributeFQN}`
* `PUT /api/commerce/catalog/admin/products/{productCode}/options/{attributeFQN}`
* `PUT /api/commerce/catalog/admin/products/{productCode}/variations`
**Implementation Strategy:**
```typescript theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductAttributesApi, ProductTypesApi, ProductOptionsApi, ProductVariationsApi, CatalogAdminsAttributeVocabularyValue, AttributeInProductType, ProductOption, ProductVariationPagedCollection } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Use the same configuration object from the previous example
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
async function addNewColorOption(colorName: string, attributeFQN: string, productTypeId: number, productCode: string) {
// 1. Instantiate all the necessary API clients
const productAttributesClient = new ProductAttributesApi(configuration);
const productTypesClient = new ProductTypesApi(configuration);
const productOptionsClient = new ProductOptionsApi(configuration);
const productVariationClient = new ProductVariationsApi(configuration);
// 2. Define the new color value in the required format
const vocabularyValue: CatalogAdminsAttributeVocabularyValue = {
value: colorName.replace(/\s/g, '-').toLowerCase(),
content: {
localeCode: 'en-US',
stringValue: colorName
}
};
try {
// STEP A: Add the new color to the master attribute list
const newVocabValue = await productAttributesClient.addAttributeVocabularyValue({ attributeFQN, attributeVocabularyValue: vocabularyValue });
console.log(`Added attribute value: ${colorName}`);
// STEP B: Update the Product Type to include this new color as a possibility
const productTypeAttr = await productTypesClient.getProductType({ productTypeId });
productTypeAttr.options?.find(opt => opt.attributeFQN === attributeFQN)?.vocabularyValues?.push(newVocabValue);
await productTypesClient.updateProductType({ productTypeId, productType: productTypeAttr });
console.log(`Updated product type ${productTypeId} with new color`);
// STEP C: Update the specific Product to include this new color as a selectable option
const productOption = await productOptionsClient.getOption({ productCode, attributeFQN });
productOption.values?.push(newVocabValue);
await productOptionsClient.updateOption({ productCode, attributeFQN, catalogAdminsProductOption: productOption });
console.log(`Added new color option to product ${productCode}`);
// STEP D: Find and activate the newly created (but inactive) variations
const existingVariations = await productVariationClient.getProductVariations({ productCode });
const colorMatchValue = colorName.replace(/\s/g, '-').toLowerCase();
if (existingVariations.items) {
for (const variation of existingVariations.items) {
const hasMatchingOption = variation.options?.some(o => o.attributeFQN === attributeFQN && o.value === colorMatchValue);
// Activate only if it's new and matches our color
if (hasMatchingOption && !variation.isActive) {
variation.isActive = true;
variation.variationExists = true; // Mark it as real
// Generate a unique SKU for the new variation
variation.variationProductCode = `${productCode}-${colorMatchValue}-${variation.options?.find(o=>o.attributeFQN?.includes('size'))?.value || 'sz'}`;
}
}
}
await productVariationClient.updateProductVariations({ productCode, productVariationPagedCollection: existingVariations });
console.log(`Activated new variations for color ${colorName} on product ${productCode}`);
} catch (e) {
console.error("Failed to add new color option:", JSON.stringify(e, null, 2));
}
}
// Example usage:
// addNewColorOption("Kibo Yellow", "tenant~color", 6, "HikeJack_001");
```
***
### Multiple Real-World Examples
**Example 1: Create a Product Type**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductTypesApi, ProductType } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Use the same configuration object from the previous example
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
async function createClothingProductType(config: Configuration) {
const productTypesClient = new ProductTypesApi(config);
const clothingType: ProductType = {
name: 'Apparel',
attributes: [
{ attributeFQN: 'admin@brand' }, // Assumes these attributes already exist
{ attributeFQN: 'tenant~color' },
{ attributeFQN: 'tenant~size' },
],
};
try {
console.log('Creating "Apparel" product type...');
const newProductType = await productTypesClient.addProductType({ productType: clothingType });
console.log('Successfully created product type:', newProductType);
return newProductType;
} catch (error) {
console.error('Error creating product type:', JSON.stringify(error, null, 2));
}
}
```
**Example 2: Create a Base Product for Variations**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductsApi, catalogAdminsProduct } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Use the same configuration object from the previous example
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
async function createBaseTshirt(config: Configuration, productTypeId: number) {
const productsClient = new ProductsApi(config);
const tshirt: CatalogAdminsProduct = {
productCode: 'TSHIRT-01',
productTypeId: productTypeId, // The ID of the "Apparel" type
productUsage: 'Configurable', // This product is a container, not directly purchasable
content: {
productName: 'Basic Crewneck T-Shirt',
productFullDescription: 'A comfortable and stylish t-shirt.',
},
// Price and other details will be set on the variations
};
try {
const newProduct = await productsClient.addProduct({ catalogAdminsProduct: tshirt });
console.log('Successfully created base product:', newProduct);
return newProduct;
} catch (error) {
console.error('Error creating product:', JSON.stringify(error, null, 2));
}
}
```
**Example 3: Create a Product Bundle**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductsApi, CatalogAdminsProduct } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Use the same configuration object from the previous example
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
async function createStarterKitBundle(config: Configuration) {
const productsClient = new ProductsApi(config);
const bundle: CatalogAdminsProduct = {
productCode: 'STARTER-KIT',
productUsage: 'Bundle', // The key difference is the product usage type
content: { productName: 'Hiking Starter Kit' },
price: { price: 150.00 }, // Bundles can have their own price
bundledProducts: [ // List of products included in the bundle
{ productCode: 'HikeJack_001', quantity: 1 },
{ productCode: 'HikeBoot_002', quantity: 1 },
{ productCode: 'WaterBottle_003', quantity: 2 },
]
};
try {
const newBundle = await productsClient.addProduct({ catalogAdminsProduct: bundle });
console.log('Successfully created bundle:', newBundle);
return newBundle;
} catch (error) {
console.error('Error creating bundle:', JSON.stringify(error, null, 2));
}
}
```
**Example 4: Add a Product to a Category**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CategoriesApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Use the same configuration object from the previous example
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
async function addProductToCategory(config: Configuration) {
// Note: This operation is on the CategoriesApi in newer SDK versions.
const categoriesClient = new CategoriesApi(config);
const productCodes = ['TSHIRT-01'];
const categoryId = 5;
try {
await categoriesClient.addProductsToCategory({ categoryId, requestBody: productCode });
console.log(`Successfully added product ${productCodes} to category ${categoryId}`);
} catch (error) {
console.error('Error adding product to category:', JSON.stringify(error, null, 2));
}
}
```
**Example 5: Create a Dynamic Category**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CategoriesApi, CatalogAdminsCategory } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Use the same configuration object from the previous example
const configuration = new Configuration({
// Your Tenant ID from Dev Center
tenantId: process.env.KIBO_TENANT_ID,
// Your Site ID from Dev Center
siteId: process.env.KIBO_SITE_ID,
// Your Application Key from Dev Center
clientId: process.env.KIBO_CLIENT_ID,
// Your Application Secret from Dev Center
sharedSecret: process.env.KIBO_SHARED_SECRET,
// The base auth URL for your region
authHost: process.env.KIBO_AUTH_HOST
});
async function createOnSaleCategory(config: Configuration) {
const categoriesClient = new CategoriesApi(config);
const dynamicCategory: CatalogAdminsCategory = {
content: { name: 'On Sale' },
categoryType: 'Dynamic',
dynamicExpression: {
// This Kibo filter expression finds all products where the price is less than 50
text: 'price lt 50'
}
};
try {
const newCategory = await categoriesClient.addCategory({ CatalogAdminsCategory: dynamicCategory });
console.log('Successfully created dynamic category:', newCategory);
return newCategory;
} catch (error) {
console.error('Error creating dynamic category:', JSON.stringify(error, null, 2));
}
}
```
***
## Integrating Catalog with Other Kibo Domains
### Catalog + Orders Integration
When a customer places an order, the `Order.items` array contains product details. The `item.product.productCode` directly links back to the unique identifier of a product or variation in your catalog.
### Catalog + Customer Data Integration
Customer accounts can have wishlists or purchase histories that reference products from the catalog via their `productCode`.
***
## Troubleshooting Your Catalog Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
}
```
**Common Error Codes for Catalog:**
* `ATTRIBUTE_FQN_ALREADY_EXISTS`: You tried to create an attribute with an `attributeFQN` that is already in use.
* `VALIDATION_ERROR`: The request body is missing a required field or contains a value of the wrong data type.
* `PRODUCT_CODE_ALREADY_EXISTS`: You tried to create a product with a `productCode` that already exists.
* `ITEM_NOT_FOUND`: You referenced an item that doesn't exist, such as a non-existent `productTypeId`.
***
### Common Development Issues
**Issue 1:** My new product isn't showing up on the storefront.
* **Why it happens:** A product must be **active**, have a **price**, have **inventory** (if tracked), and be in a **category**.
* **How to fix it:** Verify each of these conditions using the API.
* **API Reference:** [`/api-reference/productsv1/update-product`](/api-reference/productsv1/update-product)
**Issue 2:** My API call to create a product is failing with a `VALIDATION_ERROR`.
* **Why it happens:** Most often, your `productUsage` is incorrect, or you are missing a required field on the `content` object, like `productName`.
* **How to fix it:** Carefully compare every field in your request body to the schema on the API documentation for the `createProduct` endpoint.
* **API Reference:** [`/api-reference/productsv1/add-product`](/api-reference/productsv1/add-product)
***
### Debugging Checklist
When your Catalog implementation isn't working:
1. Verify your `Configuration` object has the correct credentials.
2. Confirm your request body exactly matches the schema in the API docs.
3. Check the `correlationId` in the error response. It's the most useful piece of information for Kibo support.
4. Ensure you are instantiating and using the correct API client (e.g., `ProductTypesApi` for product types).
5. Validate that prerequisite objects exist (e.g., the attribute exists before you add it to a product type).
# Commerce/OMS API
Source: https://docs.kibocommerce.com/developer-guides/commerce
Order imports and OMS integrations for external e-commerce front-ends
# Kibo Commerce API Developer Guide for OMS Implementations
## Understanding Order Imports in Kibo
For businesses using Kibo's Order Management System (OMS) with a separate, external e-commerce front-end, the primary goal is not to process transactions in real-time but to **import** completed orders for fulfillment. In this context, an "Order" is a record of a transaction that has already occurred elsewhere.
Kibo's API is specifically designed for this. Instead of a multi-step cart-to-checkout process, you use a single, powerful API call to create a complete order record. The key is providing all necessary information—customer details, pre-calculated pricing, and pre-authorized payment details—in one request. This is achieved by using the `POST /commerce/orders` endpoint with the required `isImport=true` flag, which tells Kibo to accept the order as a historical record rather than processing it as a new transaction.
***
## How This Domain Fits Into Kibo
The Commerce domain is the entry point for all order data into the Kibo platform. For an OMS-only implementation, this is where your external systems hand off completed sales to Kibo for subsequent management.
* **Fulfillment:** Once an order is imported, it enters the Kibo fulfillment workflow, where it can be routed to the appropriate warehouse or location.
* **Customer Service:** Imported orders are visible to customer service representatives, who can then manage returns, refunds, and cancellations using Kibo's tools.
* **Inventory:** Subsequent actions on an imported order, like fulfillment, will correctly decrement stock levels within Kibo.
***
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs and constructing complex JSON objects
* Access to pre-authorized payment transaction details from your external payment gateway.
* **API Reference:** [/api-overviews/openapi\_overview\_overview](/api-overviews/openapi_overview_overview) (bookmark this - you'll reference it constantly)
***
## What You'll Learn
After completing this guide, you'll understand:
* How to structure a complete JSON payload to import an order into Kibo's OMS.
* The key patterns for providing pre-authorized credit card, PayPal, and other payment details.
* How to correctly structure item-level pricing, taxes, and shipping to avoid validation errors.
* How to include external fraud check results with an imported order.
* How to read and navigate the official Orders API documentation for OMS-specific use cases.
***
## Kibo OMS Import Fundamentals
### How Kibo Organizes Imported Order Data
For an OMS import, you are essentially building the final `Order` object yourself. The core data structures you must provide are:
* **`isImport: true`**: This boolean field is mandatory and signals to Kibo that you are importing a completed order.
* **`items`**: An array of line items. For imported orders, you must provide the final, calculated pricing components for each item, including tax, shipping, and discounts.
* **`payments`**: An array of payment objects. Since the payment was authorized on your external system, you must provide the gateway's transaction details, tokenized card information, and authorization codes.
* **`billingInfo`**: The customer's billing address and contact information. This object must be populated on both the order level and within each payment object.
* **`fulfillmentInfo`**: The customer's shipping address and chosen shipping method.
* **`email`** and **`customerAccountId`**: Identifiers for the customer.
### Key Kibo Patterns You'll See Everywhere
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of the `OrderApi` client, which handles the OAuth 2.0 token exchange for every API call.
**Error Handling Approach:**
Kibo provides structured errors. For OMS imports, the most common error is a `VALIDATION_ERROR`, often with a message like "The order totals do not match the sum of the item totals." This means you must carefully verify your pricing calculations.
```json theme={null}
// Actual error schema for a totals mismatch
{
"message": "The order totals do not match the sum of the item totals.",
"errorCode": "VALIDATION_ERROR",
"correlationId": "a1b2c3d4-e5f6-4a7b-8c9d-12345fedcba"
}
```
**API Documentation Reference:**
The primary endpoint for this guide is `POST /commerce/orders`.\
Find complete specs at: [Create Order](/api-reference/order/create-order)
***
## Importing an Order: The Kibo OMS Way
### When You Need This
This is the core workflow for any OMS-only Kibo client. You use this process to feed orders from your website, mobile app, or other point-of-sale systems into Kibo for centralized fulfillment and management.
### API Documentation Reference
**Endpoint:** `POST /commerce/orders`\
**Method:** `POST`\
**API Docs:** [Create Order](/api-reference/order/create-order)
### Understanding the Kibo Approach
Kibo's import functionality is built on trust. By setting `isImport=true`, you are telling the system: "Trust me. This transaction is complete, the payment is authorized, and the prices are final." Kibo will bypass its internal pricing and payment processing engines and instead record the exact data you provide. This makes the accuracy of your payload important, especially the financial details. The sum of all item-level pricing components **must** precisely match the overall order total.
### Code Structure Walkthrough
> We'll build this step by step:
>
> 1. **Configuration**: Create a central Configuration instance.
> 2. **API Client Instantiation**: Create a dedicated client for the Order API.
> 3. **Data Preparation**: Meticulously construct the entire Order object, including items with broken-down pricing and payments with gateway authorization details.
> 4. **API Call**: Use the `createOrder` method to import the order.
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Commerce operations.
import { Configuration } from "@kibocommerce/rest-sdk";
import { OrderApi } from "@kibocommerce/rest-sdk/clients/Commerce";
import { Order } from "@kibocommerce/rest-sdk/clients/Commerce/models";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
This example shows how to import an order with a pre-authorized Cybersource credit card payment.
```ts theme={null}
// This function constructs and imports a complete order.
async function importCompletedOrder(orderData: any): Promise {
console.log(`Importing order from external system...`);
const orderClient = new OrderApi(configuration);
// 1. Meticulously construct the Order payload. This is the most important step.
const orderToImport: Order = {
// **MANDATORY**: Tell Kibo this is an imported order.
isImport: true,
email: orderData.customerEmail,
customerAccountId: orderData.customerAccountId,
// You can set order type to Online or Offline
type: 'Online',
// 2. Build the Fulfillment Info with shipping address and method
fulfillmentInfo: {
fulfillmentContact: {
firstName: orderData.shippingFirstName || 'John',
middleNameOrInitial: orderData.shippingMiddleName || '',
lastNameOrSurname: orderData.shippingLastName || 'Doe',
phoneNumbers: {
home: orderData.shippingPhone || '555-555-1212',
mobile: orderData.shippingPhone || '555-555-1212',
work: orderData.shippingPhone || '555-555-1212',
},
email: orderData.customerEmail,
address: {
address1: orderData.shippingAddress1 || '123 Main St',
address2: orderData.shippingAddress2 || '',
address3: orderData.shippingAddress3 || '',
address4: orderData.shippingAddress4 || '',
cityOrTown: orderData.shippingCity || 'Anytown',
countryCode: orderData.shippingCountry || 'US',
postalOrZipCode: orderData.shippingPostal || '12345',
stateOrProvince: orderData.shippingState || 'CA',
addressType: 'Residential',
isValidated: true
}
},
// This code must match a configured shipping method in Kibo,
// or you can use a generic code like "KIBO_STANDARD"
shippingMethodCode: 'fedex_FEDEX_2_DAY',
shippingMethodName: 'FedEx 2 Day'
},
// 3. Build the Billing Info
billingInfo: {
billingContact: {
firstName: orderData.billingFirstName || 'John',
middleNameOrInitial: orderData.billingMiddleName || '',
lastNameOrSurname: orderData.billingLastName || 'Doe',
phoneNumbers: {
home: orderData.billingPhone || '555-555-1212',
mobile: orderData.billingPhone || '555-555-1212',
work: orderData.billingPhone || '555-555-1212',
},
email: orderData.customerEmail || 'john.doe@example.com',
address: {
address1: orderData.billingAddress1 || '123 Main St',
address2: orderData.billingAddress2 || '',
address3: orderData.billingAddress3 || '',
address4: orderData.billingAddress4 || '',
cityOrTown: orderData.billingCity || 'Anytown',
countryCode: orderData.billingCountry || 'US',
postalOrZipCode: orderData.billingPostal || '12345',
stateOrProvince: orderData.billingState || 'CA',
addressType: 'Residential',
isValidated: true
}
},
paymentType: 'CreditCard',
},
// 4. Build the Payments array with pre-authorized details.
payments: [{
paymentType: 'CreditCard',
billingInfo: {
paymentType: 'CreditCard',
billingContact: {
email: orderData.customerEmail || 'john.doe@example.com',
firstName: orderData.billingFirstName || 'John',
lastNameOrSurname: orderData.billingLastName || 'Doe',
middleNameOrInitial: orderData.billingMiddleName || '',
address: {
address1: orderData.billingAddress1 || '123 Main St',
address2: orderData.billingAddress2 || '',
address3: orderData.billingAddress3 || '',
address4: orderData.billingAddress4 || '',
cityOrTown: orderData.billingCity || 'Anytown',
countryCode: orderData.billingCountry || 'US',
postalOrZipCode: orderData.billingPostal || '12345',
stateOrProvince: orderData.billingState || 'CA',
addressType: 'Residential',
isValidated: true
}
},
isSameBillingShippingAddress: false,
card: {
// This field holds the tokenized card number from the gateway
cardNumberPartOrMask: orderData.gatewayToken,
isTokenized: true,
paymentOrCardType: 'VISA',
expireMonth: 12,
expireYear: 2025,
}
},
status: 'Authorized',
amountRequested: 192.50,
interactions: [{
interactionType: 'Authorization',
status: 'Authorized',
gatewayTransactionId: orderData.gatewayTransactionId,
gatewayAuthCode: orderData.gatewayAuthCode,
// Include gateway-specific response data needed for capture/credit
gatewayResponseData: [
{ key: "AuthorizationRequestId", value: orderData.cybersourceRequestId },
{ key: "AuthorizationRequestToken", value: orderData.cybersourceRequestToken }
],
amount: 192.50,
}]
}],
// 5. Build the Items array with explicit, pre-calculated pricing.
items: [{
product: {
productCode: 'ITEM-001',
name: 'Cool T-Shirt',
price: {
// This is the pre-discount unit price
price: 25.00
}
},
quantity: 1,
// All of these pricing fields MUST be provided
discountTotal: 5.00, // Item-level discount
itemTaxTotal: 1.65, // Item-level tax
shippingTotal: 10.00, // Shipping cost allocated to this item
shippingTaxTotal: 0.83, // Shipping tax allocated to this item
handlingAmount: 1.00, // Handling fee for this item
// The sum of these values determines the line item total.
total: 33.48 // (25-5) + 1.65 + 10.00 + 0.83 + 1.00
}],
// 6. The order total must match the sum of all item fields.
total: 33.48, // In this one-item example.
// Other totals...
subtotal: 20.00, // quantity * price - discountTotal
shippingTotal: 10.00,
taxTotal: 2.48, // itemTaxTotal + shippingTaxTotal
};
try {
const newOrder = await orderClient.createOrder({ order: orderToImport });
console.log(`Successfully imported order number: ${newOrder.orderNumber}`);
return newOrder;
} catch (error) {
console.error("API Error importing order:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Advanced Import Patterns
### Pattern 1: Importing an Order with a PayPal Payment
**Business Scenario:** Your website uses PayPal Express 2. You need to import the completed order into Kibo, including the necessary PayPal transaction details so you can capture funds later.
**Kibo's Architecture Consideration:** Kibo has a specific structure for PayPal Express 2 payments. You must provide the `payerId`, the `externalTransactionId` (which is the PayPal `EC-` token), and the `gatewayTransactionId` from the authorization.
```typescript theme={null}
// This function builds a payment object specifically for an imported PayPal order.
function buildPayPalPayment(payPalData: any): any {
return {
paymentType: "PayPalExpress2",
paymentWorkflow: "PayPalExpress2",
// The EC- token goes in externalTransactionId
externalTransactionId: payPalData.token, // e.g., "EC-74R44913L24993252"
status: "Authorized",
amountRequested: payPalData.amount,
billingInfo: {
// Payer ID is nested in the billingInfo.data object
data: {
paypal: {
payerId: payPalData.payerId // e.g., "B373JG5S4Y388"
}
},
billingContact: { email: payPalData.email }
},
interactions: [{
interactionType: "Authorization",
status: "Authorized",
// The authorization transaction ID goes here
gatewayTransactionId: payPalData.authorizationId, // e.g., "8AF73994TM546221D"
amount: payPalData.amount,
}]
};
}
```
### Pattern 2: Importing an Order with Fraud Review
**Business Scenario:** Your e-commerce front-end uses a service like Kount for fraud detection. An order is flagged for manual review. You need to import this order into Kibo and ensure it is also placed in a "Pending Review" state.
**Kibo's Architecture Consideration:** You can pass external fraud results directly into the order payload using the `validationResults` object. By setting the `status` within this object to `Review`, Kibo will automatically place the imported order into a `Pending` status, preventing it from being fulfilled until it is manually accepted.
```typescript theme={null}
// This function builds a validationResults object for an order needing review.
function buildFraudReviewPayload(kountData: any): any[] {
return [{
validatorName: "KountValidator",
validatorType: "Fraud",
// Setting status to Review flags the order in Kibo
status: "Review",
messages: kountData.messages // Pass the raw messages from Kount
}];
}
// In your main import function, you would add this to the order object:
// const orderToImport: Order = {
// ...
// validationResults: buildFraudReviewPayload(fraudDataFromFrontend),
// ...
// };
```
***
## Troubleshooting Your OMS Import
### Common Import Issues
> **Issue 1:** The `createOrder` call fails with a `VALIDATION_ERROR` and a "totals do not match" message.
>
> * **Why it happens:** This is the most common import error. The sum of all item-level pricing fields (`discountTotal`, `itemTaxTotal`, `shippingTotal`, `shippingTaxTotal`, `handlingAmount`, etc.) across all items does not exactly equal the top-level `order.total`. This often happens due to floating-point math rounding errors or misinterpreting which fields are additive.
> * **How to fix it:** Before sending the request, programmatically sum all the calculated pricing fields from your `items` array and ensure the result is used to set `order.total`, `order.subtotal`, `order.taxTotal`, etc. Do not assume they will be calculated for you.
> **Issue 2:** The order is imported, but subsequent payment capture fails.
>
> * **Why it happens:** The authorization details provided in the `payment.interactions` object were incorrect or insufficient. For gateways like Cybersource or Authorize.net, specific keys and tokens from the *original* authorization are required to link a future capture or credit action.
> * **How to fix it:** Double-check the required `gatewayResponseData` for your specific payment gateway. Ensure you are storing and passing the correct transaction IDs, request tokens, and auth codes from your e-commerce front-end's payment authorization step. Make sure you are correctly mapping gateway fields, such as `CustomerProfileId` to `cardNumberPartOrMask` for Authorize.net.
# Customer API
Source: https://docs.kibocommerce.com/developer-guides/customer
Customer accounts, addresses, saved payments, and authentication
# Kibo Customer API Developer Guide
Manage customers in the Admin UI dashboard
## Understanding Customer in Kibo
In Kibo, a "Customer" is more than just an email address; it's a comprehensive entity representing a shopper's identity, preferences, and history. Unlike some platforms that treat guests and registered users as entirely separate, Kibo builds a holistic view. A Customer Account (`CustomerAccount`) is the central hub that stores personal details, login credentials, address books (`CustomerContact`), and saved payment methods (`Card`).
This design allows for powerful personalization and streamlined experiences, like converting a guest shopper with an existing cart into a registered user without losing their data. Understanding the distinction between an anonymous shopper and a registered `CustomerAccount` is key to building effective customer-facing applications on the Kibo platform.
***
## How This Domain Fits Into Kibo
The Customer domain is the foundation of the user experience. It directly connects to nearly every other part of the Kibo ecosystem:
* **Orders**: Each order is linked to a `customerAccountId` to track purchase history.
* **Carts & Checkout**: Customer accounts provide saved addresses and payment methods to accelerate the checkout process.
* **Promotions**: Customer data can be used for segmentation to offer targeted discounts and promotions.
* **Returns**: Customer accounts are used to manage and track return merchandise authorizations (RMAs).
* **Privacy & Redaction**: When a customer exercises their right to deletion under GDPR, CCPA, or similar regulations, their PII across orders, payments, shipments, and the account record itself is removed via the [Redaction Services](/developer-guides/redaction-services) two-phase workflow. Note that the `DELETE` account endpoint cannot remove an account that has orders — use redaction for full data subject erasure.
***
## Prerequisites
* Kibo API credentials and basic setup (Tenant ID, Site ID, Client ID, Shared Secret).
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await` in JavaScript/TypeScript.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Customer** data and operations (based on official API specs).
* The key patterns Kibo uses across all **Customer** APIs (verified from apidocs.kibocommerce.com).
* Common workflows like creating accounts, managing addresses, and handling logins (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official API documentation effectively for the Customer domain.
***
***
## Kibo Customer Fundamentals
### How Kibo Organizes Customer Data
Kibo's Customer data is built around a few core objects that are linked together:
* **`CustomerAccount`**: The main object representing a registered user. It contains the user's `id`, `emailAddress`, `firstName`, `lastName`, and login credentials.
* **`CustomerContact`**: Represents an address in the user's address book. An account can have multiple contacts, each with types like 'Shipping' or 'Billing'. This is a separate object from the main account.
* **`Card`**: A saved credit card or other payment method associated with the customer's account. This data is securely stored and tokenized for PCI compliance.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new CustomerAccountApi(configuration)`). The clients will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call.
**Request/Response Structure:**
Kibo API responses are generally consistent. A successful `POST` or `PUT` will return the created or updated object. A `GET` on a collection returns a `paged` object. For example, getting a customer account returns a clear structure:
```json theme={null}
// Actual response schema from Kibo's API documentation
{
"id": 1001,
"emailAddress": "user@example.com",
"userName": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"contacts": [
{
"accountId": 1001,
"address": {
"address1": "123 Kibo Lane",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential"
},
"types": [{ "name": "Shipping", "isPrimary": true }]
}
],
"acceptsMarketing": true,
"isLocked": false
// ... other properties
}
```
**Error Handling Approach:**
When an API call fails, the SDK throws a structured error object. You should always wrap your API calls in a `try...catch` block to handle these. The error contains a specific `errorCode` that you can use for programmatic handling.
**Pagination and Filtering:**
When fetching lists of customers, Kibo uses standard parameters like `startIndex`, `pageSize`, `sortBy`, and `filter`. The `filter` parameter uses a Kibo-specific syntax (e.g., `filter='firstName eq "John"'`).
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_customer_overview`
***
### Common Customer Workflows
Kibo developers typically work with Customers in these scenarios:
1. **Account Registration**: Creating a new customer account during a sign-up process.
2. **Account Management**: Allowing a logged-in user to update their profile, add/edit addresses, or manage saved payments.
3. **Pre-flight Checks**: Checking if an email address already exists before attempting to create a new account.
Let's explore each pattern step by step.
***
***
## Creating a Customer Account: The Kibo Way
### When You Need This
This is the most fundamental customer operation. You'll use it for any "Sign Up" or "Create Account" feature in your storefront or application. The goal is to create a new `CustomerAccount` record in Kibo.
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/customer/accounts/`
* **Method:** `POST`
* **SDK Method:** `addAccount`
* **API Docs:** [Add Account](/api-reference/customeraccount/add-account)
### Understanding the Kibo Approach
Kibo treats account creation as a distinct, atomic operation. The request payload requires a `CustomerAccountAndAuthInfo` object, which includes both the account details (name, email) and the user's new credentials (password). This ensures that an account is never created in an unusable state without a valid way to log in.
### Code Structure Walkthrough
Before we implement, let's understand what we're building (based on actual API requirements):
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the CustomerAccount resource.
// 3. **Data Preparation**: Construct the 'CustomerAccountAndAuthInfo' request body according to the API schema.
// 4. **API Call**: Use the 'CustomerAccountApi' client to call the 'createAccount' method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
First, we set up our configuration and import the necessary client from the Kibo SDK.
```ts theme={null}
// Essential imports for Customer operations.
// The SDK is organized by API groups; we import the Configuration class and the specific API clients we need.
// These imports are verified from @kibocommerce/rest-sdk documentation.
import { Configuration } from "@kibocommerce/rest-sdk";
import { CustomerAccountApi } from "@kibocommerce/rest-sdk/clients/Customer";
import { CustomerAccountAndAuthInfo } from "@kibocommerce/rest-sdk/clients/Customer/models";
// Configuration setup - this single object is reused for all API clients.
// It holds all necessary credentials for authentication and routing.
// These properties are required per official API documentation.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
Now, let's write the function to create the account. Pay close attention to the structure of the `payload` object—it must match what the Kibo API expects.
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// Each line verified against official API documentation
// This function encapsulates the logic for creating a new customer account.
async function createNewCustomerAccount() {
// 1. Instantiate a dedicated client for the Customer Account API resource.
const customerAccountApi = new CustomerAccountApi(configuration);
// 2. Prepare the request body.
// This object must match the 'CustomerCustomerAccountAndAuthInfo' schema defined in the Kibo API documentation.
// It requires both account details and authentication information.
const payload: CustomerAccountAndAuthInfo = {
account: {
emailAddress: "new.customer@example.com",
userName: "new.customer@example.com", // Often the same as email
firstName: "Jane",
lastName: "Doe",
acceptsMarketing: true,
isAnonymous: false,
isLocked: false,
isActive: true,
hasExternalPassword: false
// 'id' is not required for creation; Kibo will assign one.
},
password: "SuperSecretPassword123!", // Must meet site's complexity requirements
isImport: false
};
console.log("Attempting to create customer account...");
// 3. Call the 'createAccount' method on the client.
// Always wrap API calls in a try/catch block to handle structured errors from Kibo.
try {
const newAccount = await customerAccountApi.addAccountAndLogin({
customerAccountAndAuthInfo: payload
});
console.log("Success: New account created with ID:", newAccount.userId);
return newAccount;
} catch (error: any) {
// The Kibo SDK throws a detailed error object.
console.error("API Error:", JSON.stringify(error, null, 2));
// Example of handling a specific, documented error code
if (error.body?.errorCode === 'DUPLICATE_EMAIL') {
console.error("This email address is already in use.");
}
}
}
createNewCustomerAccount();
```
### What Just Happened? (Code Explanation)
* The **setup phase** created a single `Configuration` object. This is the source of truth for all API credentials and is passed to every client.
* The **API call** was made using an instance of `CustomerAccountApi`. The Kibo SDK provides this specialized client with type-safe methods like `addAccountAndLogin` that match the API operations.
* The **payload** was a `CustomerAccountAndAuthInfo` object. We explicitly separated the `account` details from the `password`, just as the API requires.
* The **response handling** uses a `try...catch` block. On success, Kibo returns the newly created `CustomerAccount` object. On failure, we log the structured error, which includes a helpful `errorCode`.
### Common Beginner Mistakes
**Mistake 1:** Sending only account details without the password wrapper.
```ts theme={null}
// Wrong - The API expects a 'CustomerAccountAndAuthInfo' object, not just the account info.
const wrongPayload = {
emailAddress: "user@example.com",
firstName: "Test",
// ... missing the parent 'account' and 'password' properties
};
// This will result in a VALIDATION_ERROR from the API.
// Correct - The payload must match the documented schema.
const correctPayload = {
account: {
emailAddress: "new.customer@example.com",
userName: "new.customer@example.com", // Often the same as email
firstName: "Jane",
lastName: "Doe",
acceptsMarketing: true,
isAnonymous: false,
isLocked: false,
isActive: true,
hasExternalPassword: false
},
password: "..."
};
```
**Mistake 2:** Trying to set the `id` or `userId` during creation.
These fields are read-only and assigned by Kibo upon successful creation. Including them in your request payload will cause a validation error.
***
***
## Multiple Real-World Examples
Here are 5 complete, production-ready examples for common `Customer` operations.
### Example 1: Check if a User Exists (Get Login State)
Before showing a registration form, it's good practice to check if an email is already in use.
* **API Docs:** [Get Login State By Email Address](/api-reference/customeraccount/get-login-state-by-email-address)
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CustomerAccountApi } from "@kibocommerce/rest-sdk/clients/Customer";
// (Use the same 'configuration' object as defined previously)
async function checkEmailExists(email: string) {
const customerAccountApi = new CustomerAccountApi(configuration);
console.log(`Checking login state for: ${email}`);
try {
const loginState = await customerAccountApi.getLoginStateByEmailAddress({ emailAddress: email });
console.log("Success: Login state retrieved:", loginState);
if (loginState.isLocked) {
console.log("Account exists but is locked.");
} else if (loginState.createdOn) {
console.log(`Account exists with email ID: ${email}`);
} else {
console.log("Account does not exist. Safe to register.");
}
return loginState;
} catch (error: any) {
// A 404 is not thrown for non-existent emails; the response body indicates existence.
// This catch block is for other errors like authentication or malformed requests.
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// checkEmailExists("existing.user@example.com");
// checkEmailExists("new.user@example.com");
```
### Example 2: Update a Customer's Profile
This allows a user to change their first name, last name, or marketing preferences.
* **API Docs:** [Update Account](/api-reference/customeraccount/update-account)
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CustomerAccountApi} from "@kibocommerce/rest-sdk/clients/Customer"
import { CustomerAccount } from "@kibocommerce/rest-sdk/clients/Customer/models";
// (Use the same 'configuration' object as defined previously)
async function updateUserProfile(accountId: number, updatedInfo: Partial) {
const customerAccountApi = new CustomerAccountApi(configuration);
console.log(`Updating profile for account ID: ${accountId}`);
try {
// The payload only needs the fields you want to change.
const updatedAccount = await customerAccountApi.updateAccount({
accountId: accountId,
customerAccount: updatedInfo
});
console.log(`Success: Updated profile for ${updatedAccount.firstName} ${updatedAccount.lastName}.`);
return updatedAccount;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage: Update the user's first name and opt them out of marketing.
/*
updateUserProfile(1001, {
firstName: "Johnny",
acceptsMarketing: false
});
*/
```
### Example 3: Add a New Address to an Account
This is a key part of "My Account" functionality, allowing users to build an address book.
* **API Docs:** [Update Account Contact](/api-reference/customeraccount/update-account-contact)
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CustomerAccountApi} from "@kibocommerce/rest-sdk/clients/Customer"
import { CustomerAccount } from "@kibocommerce/rest-sdk/clients/Customer/models";
// (Use the same 'configuration' object as defined previously)
async function addAddressToAccount(accountId: number) {
// Note: We use 'CustomerContactApi' for address operations.
const customerAccountApi = new CustomerAccountApi(configuration);
// This payload must match the CustomerContact schema.
const newAddress: CustomerContact = {
accountId: accountId,
address: {
address1: "123 Kibo Lane",
cityOrTown: "Austin",
stateOrProvince: "TX",
postalOrZipCode: "78758",
countryCode: "US",
addressType: "Residential"
},
types: [{ name: "Shipping", isPrimary: true }]
};
console.log(`Adding new address to account ID: ${accountId}`);
try {
const addedContact = await customerAccountApi.addAccountContact({
accountId: accountId,
customerContact: newAddress
});
console.log(`Success: Added new contact with ID: ${addedContact.id}`);
return addedContact;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// addAddressToAccount(1001);
```
### Example 4: Add a Saved Credit Card
Securely save a tokenized payment card to a customer's account for faster checkout.
* **API Docs:** [Add Account Card](/api-reference/customeraccount/add-account-card)
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CustomerAccountApi} from "@kibocommerce/rest-sdk/clients/Customer"
import { CustomerAccount } from "@kibocommerce/rest-sdk/clients/Customer/models";
// (Use the same 'configuration' object as defined previously)
// IMPORTANT: This function assumes you have already obtained a 'paymentServiceCardId' (card token)
// from your payment gateway (e.g., via a client-side SDK like Stripe.js or Braintree.js).
// NEVER send raw credit card numbers to your server or the Kibo API.
async function addSavedCard(accountId: number, cardToken: string, cardholderName: string) {
// Note: We use the 'CustomerAccountApi' for payment card operations.
const customerAccountApi = new CustomerAccountApi(configuration);
const newCard: Card = {
id: cardToken, // The token from the payment gateway
isDefaultPayMethod: true,
nameOnCard: cardholderName,
cardType: "VISA", // Often provided by the gateway
expireMonth: 12,
expireYear: 2028,
// The last 4 digits are often provided by the gateway response
cardNumberPart: "1111"
};
console.log(`Adding saved card to account ID: ${accountId}`);
try {
const addedCard = await customerAccountApi.addAccountCard({
accountId: accountId,
card: newCard
});
console.log(`Success: Added new card with ID: ${addedCard.id}`);
return addedCard;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// addSavedCard(1001, "tok_123abc456def", "Jane Doe");
```
### Example 5: Create Account and Log In Simultaneously
This workflow is perfect for registrations that should immediately start a user session. It creates the account and returns an authentication ticket in one atomic API call.
* **API Docs:** [Create User Auth Ticket](/api-reference/storefrontauthticket/create-user-auth-ticket) - **Note**: The SDK simplifies this into a single `performCustomerAuth` call. The true workflow is creating an account and then creating an auth ticket.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CustomerAccountApi } from "@kibocommerce/rest-sdk/clients/Customer";
import { CustomerUserAuthInfo } from "@kibocommerce/rest-sdk/clients/Customer/models";
import { StorefrontAuthTicketApi} from "@kibocommerce/rest-sdk/clients/Customer"
// (Use the same 'configuration' object as defined previously)
async function registerAndLogin() {
// Step 1: Create the account (reusing our function from the first section)
const newAccount = await createNewCustomerAccount(); // Assumes 'createNewCustomerAccount' is defined
if (!newAccount) {
console.log("Account creation failed, aborting login.");
return;
}
// Step 2: Authenticate to get session tickets
const customerAuthApi = new StorefrontAuthTicketApi(configuration);
const authPayload: CustomerUserAuthInfo = {
username: "new.customer@example.com",
password: "SuperSecretPassword123!"
};
console.log(`Account created in step 3. Now logging in as ${authPayload.username}...`);
try {
const authTicket = await customerAuthApi.createUserAuthTicket({
customerUserAuthInfo: authPayload
});
console.log("Success: Logged in and received auth ticket.");
console.log("Access Token:", authTicket.accessToken); // This is the user's session token
// You would typically store the accessToken and refreshToken in secure client-side storage.
return authTicket;
} catch (error: any) {
console.error("Login failed after registration:", JSON.stringify(error, null, 2));
}
}
// registerAndLogin();
```
***
***
## Integrating Customer with Other Kibo Domains
### Customer + Orders Integration
The `CustomerAccount` is the link to a user's entire purchase history. When you retrieve an `Order` object, it will contain a `customerAccountId` field. You can use this ID to fetch the full customer profile.
**Practical Example:** On an order confirmation page, you could use the `customerAccountId` from the order to retrieve the customer's `firstName` for a personalized "Thank You, John!" message.
### Customer + Carts & Checkout Integration
When a logged-in user adds items to their cart, the cart is associated with their `customerAccountId`. This allows for persistent carts across devices. During checkout, you can use the `accountId` to fetch their address book (`CustomerContact` objects) and saved payment methods (`Card` objects) to pre-fill the checkout form, drastically improving conversion rates.
***
***
## Troubleshooting Your Customer Implementation
### Reading Kibo Error Messages
Kibo's error responses are structured and predictable. The SDK client will throw an error object containing a `body` with these key fields:
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string; // Human-readable description of the error
errorCode: string; // A specific code for programmatic handling
correlationId: string; // Unique ID for this request, useful for support tickets
items?: Array<{ // Present for validation errors
name: string;
errorCode: string;
message: string;
}>
}
}
```
**Common Error Codes for Customer:** (from official API documentation)
* `DUPLICATE_EMAIL`: Occurs when calling `createAccount` with an email address that already exists.
* `VALIDATION_ERROR`: The request body is missing a required field or has an invalid data type. The `items` array in the error will specify which field failed.
* `INVALID_CREDENTIALS`: Occurs during login (`createUserAuthTicket`) when the username or password is incorrect.
* `RESOURCE_NOT_FOUND`: Trying to update or fetch a resource with an ID that doesn't exist (e.g., `updateAccount` with an invalid `accountId`).
### Common Development Issues
**Issue 1:** Password complexity rules causing `VALIDATION_ERROR` on account creation.
* **Why it happens:** Every Kibo site has configurable password policies (minimum length, required characters, etc.). If the password in your `createAccount` payload doesn't meet these rules, the API will reject it.
* **How to fix it:** Ensure the password you send meets the site's requirements. These are visible in the Kibo Admin under **System > Settings > Password Policy**.
* **How to avoid it:** Implement client-side validation on your registration form that matches the Kibo password policy.
* **API Reference:** [Add Account](/api-reference/customeraccount/add-account) (The error response will contain details in the `items` array).
**Issue 2:** Addresses or Cards not appearing after being added.
* **Why it happens:** A common mistake is to add a `CustomerContact` or `Card` and then fetch the main `CustomerAccount` object expecting the new data to be there. The `getAccount` endpoint does not always return a fully hydrated object with all contacts and cards by default.
* **How to fix it:** After adding a contact or card, use the specific `getAccountContact` or `getAccountCard` methods to verify it was created. Alternatively, use the `getAccountContacts` or `getAccountCards` methods to retrieve the full list.
* **API Reference:** [Get Account Contacts](/api-reference/customeraccount/get-account-contacts)
### Debugging Checklist
When your Customer implementation isn't working:
1. **Verify Endpoint:** Does the SDK method you're calling (`createAccount`) correspond to the correct HTTP method and URL (`POST /api/commerce/customer/accounts/`) in the API docs?
2. **Confirm Request Body:** `console.log` your payload object right before you send it. Does its structure (`{ account: { ... }, password: "..." }`) exactly match the schema on apidocs.kibocommerce.com?
3. **Check Authentication:** Are `tenantId`, `siteId`, `clientId`, and `sharedSecret` all correctly configured? An auth error usually results in a 401 Unauthorized status.
4. **Validate IDs:** If you are updating or fetching an entity (`updateAccount`, `addAccountContact`), double-check that the `accountId` you are using is valid and exists in the system.
5. **Review API Response:** In your `catch` block, log the entire error object (`JSON.stringify(error, null, 2)`). The `errorCode` and `message` in the `body` will tell you exactly what went wrong.
6. **Check for Site Policies:** Are there any site settings (like password policies or account lockout rules) that could be affecting your API call?
# Dropship
Source: https://docs.kibocommerce.com/developer-guides/dropship
Generate EDI 850 Purchase Orders and translate shipments into vendor SKU mappings with contracted pricing using the Kibo Dropship API
## Overview
Understand the Dropship model, lifecycle, and two-portal architecture
Review the EDI message set used in Dropship integrations
The Dropship API exposes two read endpoints that turn a Kibo shipment into the representation a drop-ship vendor needs in order to fulfill it:
1. **Retrieve EDI 850 Purchase Order** — converts a shipment into a fully mapped EDI 850 Purchase Order transaction set (returned as JSON), suitable for sending to a vendor over an EDI integration.
2. **Translate Shipment** — converts the same shipment into a lightweight JSON payload containing vendor SKU mappings and contracted pricing, suitable for a vendor portal or a custom API integration.
Both endpoints take a single `shipmentNumber` and resolve everything else — the vendor, the SKU mappings, the contracted prices, and the ship-to address — from the platform. The `shipmentNumber` is the Kibo Admin shipment number, which is the same value surfaced to vendors as the **PO Number** in the Vendor Portal.
These endpoints are the programmatic equivalent of the EDI and API integration modes a vendor selects during onboarding. For the operator- and vendor-facing UI workflows, see the user guides linked at the bottom of this page.
***
## How This Domain Fits Into Kibo
Dropship runs natively on the Kibo platform and reuses the order routing, fulfillment, location, and pricing services rather than a separate system. When the order routing engine assigns part of an order to a vendor's location, it creates a shipment against that fulfillment location. These endpoints operate on that shipment:
| Resolved from the shipment | Source |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Vendor | The vendor whose `locationCode` matches the shipment's `fulfillmentLocationCode` |
| Vendor SKU and contracted price | The vendor's SKU mapping for each item's variation product code (falling back to the base product code) |
| Ship-to address | The shipment destination contact |
| Line items, quantities, weights, and dimensions | The shipment items |
Because both endpoints derive the vendor from the shipment's fulfillment location, a location with no matching vendor mapping cannot be translated or converted to an EDI 850.
***
## Prerequisites
* A Kibo bearer token (JWT). Both endpoints require authorization satisfying the order update or order fulfillment behavior. The Translate Shipment endpoint additionally enforces vendor-scoped authorization.
* The **tenant must be enabled for Drop Ship**. Both endpoints reject the request with a conflict error if it is not.
* A shipment that exists and whose `fulfillmentLocationCode` maps to a configured vendor.
* Vendor SKU mappings configured for the items you expect to receive vendor SKUs and contracted prices for (see [Manage Vendors](/pages/manage-vendors)).
Both endpoints are scoped to the tenant and site context (`/commerce/dropship`).
***
## Retrieve EDI 850 Purchase Order
Converts a shipment into an EDI 850 Purchase Order transaction set, returned as JSON.
**Endpoint:** `GET /commerce/dropship/purchaseorder/{shipmentNumber}` — [API reference](/api-reference/dropship/retrieve-edi-850-purchase-order)
| Parameter | In | Type | Required | Constraints | Description |
| ---------------- | ---- | ----------------- | -------- | ------------------------------------------ | ----------------------------------------------------- |
| `shipmentNumber` | path | integer (`int32`) | Yes | Positive 32-bit integer (max `2147483647`) | The Kibo shipment number to generate the EDI 850 for. |
### What the service does
1. Verifies the tenant is enabled for Drop Ship.
2. Fetches the shipment from the Fulfillment service.
3. Validates the shipment (see [Validation rules](#validation-rules)).
4. Resolves the vendor from the shipment's fulfillment location.
5. Maps the shipment to a complete EDI 850 transaction set and returns it.
### Response: EDI 850 transaction set
The response body is a `TransactionSet`. The service populates the following segments — segments not listed are part of the EDI 850 schema but are not currently emitted:
| EDI segment | JSON property | Mapped from |
| ------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ST — Transaction Set Header | `transactionSetHeader` | Identifier code `850` and a generated control number. |
| BEG — Beginning Segment for Purchase Order | `beginningSegmentForPurchaseOrder` | Purpose code `00` (Original), type code `DS` (Drop Ship), purchase order number = shipment number, order date. |
| CUR — Currency | `currency` | Entity `BT` (Bill-To) and the shipment currency code. Omitted when the shipment has no currency code. |
| REF — Reference Information | `referenceInformation` | Order number, shipment number, customer account, customer email, tenant, site, serialized custom data, and one entry per shipment attribute. |
| PER — Administrative Communications Contact | `administrativeCommunicationsContact` | The resolved vendor's name, phone (`TE`), and email (`EM`). |
| DTM — Date/Time Reference | `dateTimeReference` | Qualifier `002` (Requested Ship) = the shipment's expected delivery date, when present. |
| N1 loop — Party Identification | `n1_loop` | Ship-To party (`ST`) only, with name, address lines, city, state/province, postal code, and country. Bill-To is intentionally omitted for drop-ship. |
| PO1 loop — Line Items | `pO1_loop` | One entry per shipment item: quantity, unit price (the vendor contracted price when a mapping exists, otherwise the item unit price), vendor SKU, product description, shipping method, physical weight/dimensions, and per-item references. |
| CTT loop — Transaction Totals | `ctT_loop` | Number of line items and a hash total of item quantities. |
| SE — Transaction Set Trailer | `transactionSetTrailer` | Included segment count and the matching control number. |
The JSON property names preserve the original EDI loop casing — for example `n1_loop`, `pO1_loop`, and `ctT_loop`. Refer to the [API reference](/api-reference/dropship/retrieve-edi-850-purchase-order) for the complete schema.
Every EDI 850 element is serialized as a string and is **optional** — a segment or element appears only when the corresponding source data exists on the shipment (for example, `currency` is omitted when the shipment has no currency code, and `dateTimeReference` is omitted when there is no expected delivery date). The endpoint does not impose its own length limits; element lengths follow the source data and the X12 850 standard.
#### Example
```bash theme={null}
curl -X GET \
"https://t1000000.sb.usc1.gcp.kibocommerce.com/api/commerce/dropship/purchaseorder/40057" \
-H "Authorization: Bearer {access_token}"
```
A representative (trimmed) response showing the populated segments:
```json theme={null}
{
"transactionSetHeader": [
{ "transactionSetIdentifierCode": "850", "transactionSetControlNumber": "202606171453018842" }
],
"beginningSegmentForPurchaseOrder": [
{ "transactionSetPurposeCode": "00", "purchaseOrderTypeCode": "DS", "purchaseOrderNumber": "40057", "date": "20260617" }
],
"currency": [
{ "entityIdentifierCode": "BT", "currencyCode": "USD" }
],
"referenceInformation": [
{ "referenceIdentificationQualifier": "Order Number", "referenceIdentification": "118" },
{ "referenceIdentificationQualifier": "Shipment Number", "referenceIdentification": "40057" }
],
"n1_loop": [
{
"partyIdentification": [{ "entityIdentifierCode": "ST", "name": "Jane Doe" }],
"partyLocation": [{ "addressInformation": "123 Market St" }],
"geographicLocation": [
{ "cityName": "Austin", "stateOrProvinceCode": "TX", "postalCode": "78701", "countryCode": "US" }
]
}
],
"pO1_loop": [
{
"baselineItemData": [
{
"assignedIdentification": "1",
"quantity": "2",
"unitOrBasisForMeasurementCode": "EA",
"unitPrice": "12.50",
"productServiceIDQualifier": "SK",
"productServiceID": "VEND-SKU-001"
}
]
}
],
"ctT_loop": [
{ "transactionTotals": [{ "numberOfLineItems": "1", "hashTotal": "2" }] }
],
"transactionSetTrailer": [
{ "numberOfIncludedSegments": "9", "transactionSetControlNumber": "202606171453018842" }
]
}
```
### Validation rules
The shipment must satisfy all of the following or the request fails with a validation error:
* The shipment exists.
* The shipment has a shipment number.
* The shipment has an `orderId`.
* The shipment contains at least one item.
* The shipment destination has an address.
A missing customer email or order number does not block generation; the service proceeds and logs a warning.
***
## Translate Shipment
Converts a shipment into a lightweight payload with vendor SKU mappings and contracted pricing per item. Use this when you want the vendor-relevant view of a shipment without the full EDI 850 structure.
**Endpoint:** `GET /commerce/dropship/translate/{shipmentNumber}` — [API reference](/api-reference/dropship/translate-shipment)
| Parameter | In | Type | Required | Constraints | Description |
| ---------------- | ---- | ----------------- | -------- | ------------------------------------------ | -------------------------------------- |
| `shipmentNumber` | path | integer (`int32`) | Yes | Positive 32-bit integer (max `2147483647`) | The Kibo shipment number to translate. |
This endpoint enforces vendor-scoped authorization in addition to the order behaviors, so it is appropriate for vendor-facing integrations.
### What the service does
1. Verifies the tenant is enabled for Drop Ship.
2. Fetches the shipment from the Fulfillment service.
3. Resolves the vendor from the shipment's fulfillment location.
4. For each item, looks up the vendor SKU mapping (by variation product code, falling back to the base product code) and attaches the vendor SKU, contracted price, and per-item subtotal.
5. Computes the shipment subtotal from the items that have a contracted price.
6. Extracts the ship-to address from the shipment destination.
If an item has no vendor SKU mapping, its `vendorSku`, `vendorContractedPrice`, and `subtotal` are returned as `null` rather than failing the request. Those items are also excluded from the shipment-level `subtotal`.
### Response fields
The response imposes no maximum length on string fields; values reflect the underlying shipment, catalog, and vendor data. The **Nullable** column indicates whether the field may be `null` or absent.
| Field | Type | Nullable | Description |
| ----------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `orderId` | string | No | The order the shipment belongs to. |
| `shipmentNumber` | integer (`int32`) | No | The shipment number that was translated. |
| `vendorCode` | string | Yes | The vendor resolved from the fulfillment location. Populated on success; the request fails before returning when no vendor maps to the location. |
| `subtotal` | number (`double`) | No | Sum of `vendorContractedPrice * quantity` across items that have a contracted price. Defaults to `0` when no item has a contracted price. |
| `shippingAddress` | object | Yes | Ship-to details (see below). `null` when the shipment destination has no contact. |
| `items` | array | Yes | Per-item detail (see below). May be an empty array when the shipment has no items. |
`shippingAddress` object — every field is a nullable string (each is omitted from the source data when not set):
| Field | Type | Nullable | Description |
| ----------------------- | ------ | -------- | ---------------------------------- |
| `firstName` | string | Yes | Recipient first name. |
| `lastNameOrSurname` | string | Yes | Recipient last name or surname. |
| `companyOrOrganization` | string | Yes | Recipient company or organization. |
| `email` | string | Yes | Recipient email. |
| `address1` | string | Yes | Street address line 1. |
| `address2` | string | Yes | Street address line 2. |
| `cityOrTown` | string | Yes | City or town. |
| `stateOrProvince` | string | Yes | State or province. |
| `postalOrZipCode` | string | Yes | Postal or ZIP code. |
| `countryCode` | string | Yes | Country code. |
Each entry in `items`:
| Field | Type | Nullable | Description |
| ----------------------- | ----------------- | -------- | ------------------------------------------------------------------------- |
| `lineId` | integer (`int32`) | No | Shipment line identifier. Defaults to `0` when the source line has no ID. |
| `originalOrderItemId` | string | Yes | The originating order item ID. |
| `productCode` | string | Yes | Base product code. |
| `variationProductCode` | string | Yes | Variation product code, when the item is a variation. |
| `sku` | string | Yes | The catalog SKU. |
| `vendorSku` | string | Yes | The vendor's SKU from the mapping, or `null` when unmapped. |
| `unitPrice` | number (`double`) | No | The item unit price on the shipment. |
| `vendorContractedPrice` | number (`double`) | Yes | The contracted price from the vendor mapping, or `null` when unmapped. |
| `subtotal` | number (`double`) | Yes | `vendorContractedPrice * quantity`, or `null` when unmapped. |
| `quantity` | integer (`int32`) | No | Quantity on the shipment. |
| `name` | string | Yes | Product name. |
| `imageUrl` | string | Yes | Product image URL. |
#### Example
```bash theme={null}
curl -X GET \
"https://t1000000.sb.usc1.gcp.kibocommerce.com/api/commerce/dropship/translate/40057" \
-H "Authorization: Bearer {access_token}"
```
```json theme={null}
{
"orderId": "5e9c1a2b3c4d5e6f7a8b9c0d",
"shipmentNumber": 40057,
"vendorCode": "acme-supply",
"subtotal": 25.00,
"shippingAddress": {
"firstName": "Jane",
"lastNameOrSurname": "Doe",
"email": "jane.doe@example.com",
"address1": "123 Market St",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78701",
"countryCode": "US"
},
"items": [
{
"lineId": 1,
"originalOrderItemId": "a1b2c3",
"productCode": "SHIRT-001",
"variationProductCode": "SHIRT-001-BLU-M",
"sku": "SHIRT-001-BLU-M",
"vendorSku": "VEND-SKU-001",
"unitPrice": 19.99,
"vendorContractedPrice": 12.50,
"subtotal": 25.00,
"quantity": 2,
"name": "Classic Tee",
"imageUrl": "https://cdn.example.com/shirt-001-blu.jpg"
}
]
}
```
***
## Error handling
| Condition | Result |
| --------------------------------------------------------- | ----------------------------------------------------------- |
| Tenant is not enabled for Drop Ship | Conflict error — `Tenant is not enabled for Drop Ship.` |
| Shipment does not exist | Not found — `Shipment {shipmentNumber} not found`. |
| No vendor maps to the shipment's fulfillment location | Not found — `Vendor not found for location {locationCode}`. |
| Shipment fails EDI 850 validation (Retrieve EDI 850 only) | Conflict error listing the specific validation failures. |
For the Translate Shipment endpoint, a missing vendor SKU mapping on an individual item is **not** an error — the vendor-specific fields on that item are returned as `null`.
***
## Extending the endpoints
Both endpoints expose before- and after-controller action extension points, so you can inject custom logic (for example, enriching the response or applying additional authorization) without modifying the service. See the API Extensions reference for each action:
| Endpoint | Before action | After action |
| ------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Retrieve EDI 850 Purchase Order | [`http.commerce.dropship.purchaseOrder.before`](/pages/dropship-purchase-order-before) | [`http.commerce.dropship.purchaseOrder.after`](/pages/dropship-purchase-order-after) |
| Translate Shipment | [`http.commerce.dropship.translate.before`](/pages/dropship-translate-before) | [`http.commerce.dropship.translate.after`](/pages/dropship-translate-after) |
# Entities API
Source: https://docs.kibocommerce.com/developer-guides/entities
Custom data storage with entity lists for extensions and integrations
# Kibo Entities API Developer Guide
## Understanding Entities in Kibo
In Kibo, "Entities" are a powerful, flexible way to store custom data that doesn't fit into the standard Kibo objects like Products or Customers. Think of the Entities system as a lightweight, schema-less NoSQL database built directly into the Kibo platform.
What makes it different from other platforms is its simplicity and direct integration. Instead of setting up an external database, you can create an **Entity List** (like a table or collection) and store **Entities** (like JSON documents or rows) within it. This is ideal for managing data for custom applications, such as a store locator, a blog, product lookbooks, or storing configuration data for an extension.
## How This Domain Fits Into Kibo
The Entities domain is a foundational service within the Kibo platform that supports custom development. It doesn't directly interact with core commerce flows like Orders or Carts, but it provides the data backbone for custom features you build on top of them.
* **Kibo Extensions:** An extension might store its settings or metadata in an Entity List.
* **Storefront Applications (API Extension):** A custom React component on your storefront could fetch data from an Entity List to display store hours, blog posts, or promotional content.
* **System Integrations:** You can use Entities as a staging area for data being imported from or exported to external systems.
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs and JSON
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures custom data using Entity Lists and Entities (based on official API specs).
* The key patterns for creating, retrieving, and managing custom data objects (verified from apidocs.kibocommerce.com).
* Common workflows like creating a custom data store and populating it with information.
* How to avoid the most common beginner mistakes, like formatting the `entityListFullName` incorrectly.
* How to read and navigate the official Entity Lists API documentation effectively.
***
## Kibo Entities Fundamentals
### How Kibo Organizes Entities Data
The system is straightforward, with two primary data structures:
* **`EntityList`**: This is the container for your custom data. It's defined by a unique name and a namespace, which together form its `fullName` (e.g., `warrantypricing@my-tenant`). It holds metadata about the data it contains.
* **`Entity`**: This is an individual data record within an `EntityList`. It consists of a unique `id` and a `item` property, which can be **any valid JSON object**. This schema-less nature is what makes Entities so flexible.
The relationship is simple: an **`EntityList`** contains many **`Entities`**.
### Namespace Architecture
Every Entity List uses a composite identifier in the format `name@namespace`:
* **Name:** The specific data type the list holds (e.g., `stores`, `zipcodes`, `vehicleMakes`).
* **Namespace:** The owner or context of the data (e.g., your tenant identifier or application prefix).
This design prevents data collisions between Kibo native applications, third-party extensions, and custom integrations. The `fullName` (e.g., `warrantypricing@12345`) is required for all subsequent data operations once the list is created.
### Context Scope
When creating a list, you set a **contextLevel** that controls data visibility:
* **Tenant:** Data is shared across all sites within the tenant (e.g., global reference data like vehicle make/model lookups).
* **Site:** Data is siloed per site (e.g., site-specific store hours or location-based content).
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new EntityListsApi(configuration)`). The clients will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call.
**Request/Response Structure:**
When you get a list of entities, Kibo returns a paginated object. The actual data is always inside the `items` array.
```json theme={null}
// Actual response schema for GET /platform/entitylists/{entityListFullName}/entities
{
"totalCount": 42,
"pageSize": 20,
"pageCount": 3,
"startIndex": 0,
"items": [
{
"id": "123-abc",
"item": {
"storeName": "Downtown Austin",
"city": "Austin",
"state": "TX"
},
"name": "Austin Store"
}
]
}
```
**Error Handling Approach:**
If an API call fails, the SDK throws a structured error object containing an `errorCode` that tells you exactly what went wrong.
```json theme={null}
// Actual error structure from Kibo
{
"message": "Entity list with full name warrantypricing@my-tenant already exists.",
"errorCode": "ENTITY_LIST_ALREADY_EXISTS",
"correlationId": "a1b2c3d4-e5f6-4a7b-8c9d-12345fedcba"
}
```
**Pagination:**
To manage large datasets, Kibo uses `pageSize` and `startIndex` parameters.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_entities_overview`
### Common Entities Workflows
Kibo developers typically work with Entities in these scenarios:
1. **Setting up a new data store:** Creating a new `EntityList` to hold a specific type of custom data (e.g., a list for "Store Locations").
2. **Populating data:** Adding individual `Entity` objects to an `EntityList` (e.g., adding each store's address and hours).
3. **Reading and displaying data:** Fetching entities from a list to be used in a custom storefront component or an admin UI.
Let's explore each pattern step by step.
### Schema Definition & Indexing
While Entity Lists accept any JSON structure, you must define **Indexes** to enable efficient filtering and sorting.
#### The 5-Index Limit
Each Entity List has exactly **5 custom index slots** (`indexA` through `indexE`), plus the standard `_id` primary key.
| Slot | Purpose | Behavior |
| :------------------ | :------------- | :-------------------------------------------------------------- |
| **\_id** | Primary Key | Always indexed. Unique identifier. |
| **indexA – indexE** | Custom Filters | Optional. Maps a JSON property to a sortable/filterable column. |
**Governance limits:**
* **Data Types:** Indexes support `string`, `integer`, `decimal`, `date`, and `boolean`.
* **Sorting:** You can only sort by fields mapped to an index.
* **Filtering:** Filtering by non-indexed fields triggers a full list scan. Acceptable for small lists (under 2,000 items), but will degrade performance or time out on larger datasets.
#### Optimization: Natural Keys
To save an index slot, use a meaningful "natural key" as the `_id` field instead of a generated GUID.
* **Inefficient:** `_id: "guid-123"`, `email: "user@example.com"` — requires `indexA` to search by email.
* **Efficient:** `_id: "user@example.com"` — allows direct lookup by ID without consuming a custom index slot.
***
## Create an Entity List: The Kibo Way
### When You Need This
This is the very first step for storing any custom data. Before you can add individual records (Entities), you must create the container (the Entity List) that will hold them.
### API Documentation Reference
**Endpoint:** `POST /platform/entitylists`
**Method:** `POST`
**API Docs:** [Add Entitylist](/api-reference/entitylists/add-entitylist)
### Understanding the Kibo Approach
Kibo requires every `EntityList` to have a `name` and a `namespace`, which combine to form a unique `fullName` like `list-name@namespace`. This prevents naming collisions and helps organize data, especially in complex environments with multiple applications and tenants. You create the list once, and then you can add, update, or remove entities from it.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Entity Lists API.
// 3. **Data Preparation**: Construct the request body object for the new Entity List, defining its name and other properties.
// 4. **API Call**: Use the instantiated client to call the `createEntityList` method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Entities operations.
// The SDK is organized by API groups; we import the Configuration class and the EntityListsApi client.
import { Configuration } from "@kibocommerce/rest-sdk";
import { EntityListsApi } from "@kibocommerce/rest-sdk/clients/Entities";
import { EntityList } from "@kibocommerce/rest-sdk/clients/Entites/models";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: Understanding the Data Flow**
Our code will send a JSON object describing the new list to the Kibo API. The API will validate the information (e.g., check if a list with that `fullName` already exists), create the list, and return the complete `EntityList` object, including system-generated properties.
**Step 3: The Core Implementation**
```ts theme={null}
// Complete working example for creating an Entity List for store locations.
async function createEntityList(): Promise {
console.log("Creating 'warrantypricing' entity list...");
// 1. Instantiate a dedicated client for the Entity Lists API.
const entityListsClient = new EntityListsApi(configuration);
// 2. Prepare the request body.
// The name and namespace will be combined to form the unique identifier.
// Here, it will be 'warrantypricing@'.
const listPayload: EntityList = {
"tenantId": 1111, // Replace with your tenant ID
"nameSpace": "ABCD", // Replace with your dev account namespace
"name": "warrantypricing",
"contextLevel": "Tenant",
"useSystemAssignedId": false,
"idProperty": {
"propertyName": "plu",
"dataType": "string"
},
"indexA": {
"propertyName": "plu",
"dataType": "string"
},
"isVisibleInStorefront": false,
"isLocaleSpecific": false,
"isShopperSpecific": false,
"isSandboxDataCloningSupported": true,
"views": [
{
"name": "Default",
"usages": [
"entityManager"
],
"security": "public",
"fields": [
{
"name": "plu",
"type": "developerAccount",
"target": "string"
}
]
}
],
"usages": [
"entityManager"
],
};
// 3. Call the method on the client.
try {
const newList = await entityListsClient.createEntityList({
entityList: listPayload,
});
console.log("Success! Created entity list:", newList.listFullName);
return newList;
} catch (error) {
console.error("API Error creating entity list:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the standard `Configuration` object.
* We used an instance of `EntityListsApi` to interact with the API.
* The **payload** defined the essential properties of our new data container. The `listFullName` (e.g., `warrantypricing@12345`) is the unique key we will use in all future API calls to interact with this list.
* The `createEntityList` method sent this payload to Kibo, which created the empty list.
### Common Beginner Mistakes
**Mistake 1:** Not understanding the `entityListFullName`.
You don't set the `fullName` directly. Kibo constructs it from the `name` and `namespace` you provide. In all subsequent calls (like adding an entity), you must use this full name (e.g., `warrantypricing@12345`).
**Mistake 2:** Creating duplicate lists.
The `createEntityList` call will fail if a list with the same `fullName` already exists. Your code should anticipate this, either by checking first or by handling the `ENTITY_LIST_ALREADY_EXISTS` error.
### Delete an Entity List
**When You Need This:** When a list and all of its data are no longer needed.
**Endpoint:** `DELETE /platform/entitylists/{entityListFullName}`
> **Warning:** This operation is destructive and permanently deletes both the schema definition and all contained data. There is no undo.
***
## Create and Manage Entities
This section covers the core operations for managing the actual data records within a list.
### Add a New Entity
**When You Need This:** After creating a list, you need to populate it with data. Each piece of data is a new entity.
**API Documentation Reference:**
* **Endpoint:** `POST /platform/entitylists/{entityListFullName}/entities`
* **Method:** `POST`
* **API Docs:** [Add Entity](/api-reference/entities/add-entity)
```ts theme={null}
// Example: Add a new store to our 'warrantypricing' list.
async function addEntity(listFullName: string, storeData: any) {
const entityClient = new EntitiesApi(configuration);
try {
// The `item` property can be any valid JSON object. This is where your custom data goes.
const newEntity = await entityClient.insertEntity({
entityListFullName: listFullName,
appDevHttpRequestMessage: {
data: {},
plu: 1111, // This is the required identifier declared when creating the entity list.
} as any,
});
console.log(`Successfully added entity with ID: ${newEntity.id}`);
return newEntity;
} catch (error) {
console.error("API Error adding entity:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### Get Entity from a List
**When You Need This:** When your application needs to read and display the custom data you've stored.
**API Documentation Reference:**
* **Endpoint:** `GET /platform/entitylists/{entityListFullName}/entities`
* **Method:** `GET`
* **API Docs:** [Get Entities](/api-reference/entities/get-entities)
```ts theme={null}
// Example: Get all stores in Texas from our list.
async function getWarrantyPrice(plu: string, listFullName: string) {
const entityClient = new EntitiesApi(configuration);
try {
const response = await entityClient.getEntity({
entityListFullName: listFullName,
id: plu,
});
console.log(`Found warranty price data for ${plu}.`);
return response;
} catch (error) {
console.error("API Error getting entities:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### Update an Entity
**When You Need This:** When an existing entity's data has changed and needs to be replaced.
**API Documentation Reference:**
* **Endpoint:** `PUT /platform/entitylists/{entityListFullName}/entities/{id}`
* **Method:** `PUT`
* **API Docs:** [Update Entity](/api-reference/entities/update-entity)
> **Important:** This is a **full replacement** of the document. Partial updates (PATCH) are not supported. You must read the existing entity, apply your changes, and rewrite the entire object.
```ts theme={null}
async function updateEntity(listFullName: string, id: string, updatedData: any) {
const entityClient = new EntitiesApi(configuration);
try {
const updated = await entityClient.updateEntity({
entityListFullName: listFullName,
id: id,
appDevHttpRequestMessage: updatedData as any,
});
console.log(`Successfully updated entity with ID: ${id}`);
return updated;
} catch (error) {
console.error("API Error updating entity:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### Delete an Entity
**When You Need This:** When a piece of data is no longer relevant and needs to be removed.
**API Documentation Reference:**
* **Endpoint:** `DELETE /platform/entitylists/{entityListFullName}/entities/{id}`
* **Method:** `DELETE`
* **API Docs:** [Delete Entity](/api-reference/entities/delete-entity)
```ts theme={null}
// Example: Delete a store by its unique entity ID.
async function deleteWarrantyEntity(plu: string, listFullName: string) {
const entityClient = new EntitiesApi(configuration);
try {
const response = await entityClient.deleteEntity({
entityListFullName: listFullName,
id: plu,
});
console.log(`Found warranty price data for ${plu}.`);
return response;
} catch (error) {
console.error("API Error getting entities:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Querying & Filtering Entities
**Endpoint:** `GET /platform/entitylists/{entityListFullName}/entities`
Use the `filter` and `sortBy` query parameters to retrieve specific records. Fields used in `filter` or `sortBy` must be mapped to an index (`indexA`–`indexE`, `_id`, `createDate`, or `updateDate`).
### Supported Operators by Data Type
| Data Type | Supported Operators | Notes |
| :-------------------- | :------------------------------------------------ | :---------------------------------------------------------------------------------- |
| **String** | `eq`, `ne`, `sw` (starts with), `cont` (contains) | Comparisons are case-insensitive. |
| **Integer & Decimal** | `eq`, `ne`, `lt`, `le`, `gt`, `ge` | Supports precise matching and range queries. |
| **Date** | `eq`, `ne`, `lt`, `le`, `gt`, `ge` | Works for custom date indexes and system fields like `createDate` and `updateDate`. |
| **Boolean** | `eq`, `ne` | Strict equality matching. |
> **Note:** The `in` (list inclusion) and `near` (geospatial) operators are not currently supported.
### Example Queries
| Scenario | Filter Query |
| :------------------------------ | :--------------------------------------------- |
| Filter by status (string) | `indexA eq 'Published'` |
| Filter by ID prefix (string) | `indexA sw 'PROD-'` |
| Filter by price range (decimal) | `indexB gt 19.99 and indexB lt 50.00` |
| Filter by creation date | `createDate ge 2023-01-01T00:00:00Z` |
| Sort by indexed field | `?filter=indexA eq 'active'&sortBy=indexB asc` |
### Mixed Filtering (Indexed + Non-Indexed)
You can filter on any field within the JSON document, even if it is not explicitly indexed. However, you must include at least one filter on an indexed property to anchor the query. The anchor filter narrows the dataset using the index before the system scans the remaining JSON data.
**Example:** Find items in the "Sales" department (non-indexed) that are also "active" (indexed):
```
filter=indexA eq 'active' and item.department eq 'Sales'
```
***
## Integrating Entities with Other Kibo Domains
### Entities + Storefront (Arc.js) Integration
This is the most common use case. An Arc.js application on your product detail page could make a client-side API call to an Entity List to pull in "Lookbook" data or "Buying Guide" content associated with that product. Because the data is schema-less, you can easily adapt it as your content needs change without requiring a developer to alter a database schema.
### Entities + Extensions Integration
An extension often needs a place to store its configuration. For example, a custom shipping integration might need to store API keys, service URLs, and shipping method mappings. An `EntityList` is the perfect place to store this data. The extension can read its configuration from the list upon startup.
***
## Bulk Import Strategy
Entity Lists do not provide a dedicated server-side bulk insert endpoint. High-volume data loading must be orchestrated client-side.
### Recommended Pattern
1. **Read source data** from your file or external system.
2. **Split into chunks** of 5 records each.
3. **Process each chunk** using parallel async requests (`Promise.all` in JavaScript or `Task.WhenAll` in C#).
4. **Limit concurrency** to 3–5 simultaneous requests to avoid `429 Too Many Requests` errors.
5. **Wrap individual calls** in try/catch blocks so a single failure does not halt the entire batch.
```ts theme={null}
async function bulkImport(listFullName: string, records: any[]) {
const entityClient = new EntitiesApi(configuration);
const chunkSize = 5;
for (let i = 0; i < records.length; i += chunkSize) {
const chunk = records.slice(i, i + chunkSize);
await Promise.all(
chunk.map(record =>
entityClient.insertEntity({
entityListFullName: listFullName,
appDevHttpRequestMessage: record as any,
}).catch(err => console.error(`Failed to insert record ${record.id}:`, err))
)
);
console.log(`Processed ${Math.min(i + chunkSize, records.length)} of ${records.length} records`);
}
}
```
***
## Best Practices
1. **Namespace:** Always use a unique, identifiable namespace to prevent data collisions with other applications or tenants.
2. **Index selectively:** Only index fields required for sorting or filtering. Avoid indexing fields just because they exist.
3. **Keep entities lean:** Avoid storing large JSON blobs. Smaller documents improve read/write performance.
4. **Don't use Entities as a search engine:** Entity Lists are not designed for full-text search. For complex keyword matching, use the Kibo Catalog & Search APIs.
5. **Test schema changes in Sandbox first:** Changing index definitions on live data requires re-processing. Validate your schema before deploying to production.
6. **Plan for the 5,000-record limit:** Modifying indexed properties on lists with over 5,000 records will fail with a `VALIDATION_CONFLICT` error. Design your schema carefully upfront.
***
## Troubleshooting Your Entities Implementation
### Reading Kibo Error Messages
```typescript theme={null}
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
}
```
**Common Error Codes for Entities:**
* `ENTITY_LIST_ALREADY_EXISTS`: You tried to call `createEntityList` with a `name` and `namespace` that are already in use.
* `ENTITY_LIST_NOT_FOUND`: The `entityListFullName` you provided in a request does not exist. Check for typos or incorrect formatting.
* `ENTITY_NOT_FOUND`: The `id` you provided for a specific entity does not exist in the given list.
* `VALIDATION_ERROR`: The request body is malformed, or you are trying to use a filter with invalid syntax.
### Common Development Issues
**Issue 1:** All API calls are failing with `ENTITY_LIST_NOT_FOUND`.
* **Why it happens:** You are probably formatting the `entityListFullName` parameter incorrectly. It is case-sensitive and must be in the format `list-name@namespace`. A common mistake is to only provide the list name.
* **How to fix it:** When you create the list, save the returned `listFullName` property. Use this exact value in all subsequent calls. For example: `warrantypricing@12345`.
* **API Reference:** All endpoints under `/developer-guides/entities` require this parameter.
**Issue 2:** My filter query is not returning any results, even though I know there is matching data.
* **Why it happens:** The filter syntax can be tricky, especially for nested JSON. You must use dot notation to access properties within the `item` object (e.g., `item.address.city`). The filter is also case-sensitive.
* **How to fix it:** Double-check your filter syntax against the Kibo documentation. Start with a simple filter (`item.state eq 'TX'`) and build up to more complex ones. Log the exact data in Kibo to ensure there isn't a case mismatch (e.g., 'tx' vs 'TX').
**Issue 3:** I'm getting a `VALIDATION_CONFLICT` error when trying to update an Entity List definition.
```json theme={null}
{
"items": [],
"errorCode": "VALIDATION_CONFLICT",
"message": "Validation Error: VALIDATION_CONFLICT.additionalErrorDetails.cannotModifyIndexedProperties"
}
```
* **Why it happens:** The Kibo platform prevents modifications to the `id` property or any indexed properties on Entity Lists that contain more than 5,000 records. This safeguard prevents timeouts during schema updates on large datasets.
* **How to fix it:** Choose one of these approaches:
1. **Revert index changes:** Ensure your update request does not modify the `id` or index configurations — keep them identical to the existing definition.
2. **Reduce list size:** Delete items from the list until the count is below 5,000, perform the schema update, then re-populate.
3. **Create a new list:** Create a new Entity List with the desired schema, migrate your data to it, then decommission the old list.
# Events/Webhooks API
Source: https://docs.kibocommerce.com/developer-guides/event
Webhook subscriptions and event notifications for real-time integrations
# Kibo Webhooks API Developer Guide
## Understanding Webhooks (Events) in Kibo
In Kibo, the "Event" system is the implementation of **webhooks**. Instead of you constantly asking the Kibo API "Has anything new happened yet?" (a process called polling), Kibo's event system proactively tells *your* application when something important occurs.
Think of it like subscribing to a notification. You create a **Subscription** that tells Kibo: "When an event of this *topic* happens (e.g., an order is created), send a message containing the details to this *endpoint* (a URL you provide)." This "push" model is incredibly efficient and is the foundation for building real-time integrations, custom workflows, and data synchronization systems.
***
## How This Domain Fits Into Kibo
The Webhooks/Events domain is the connective tissue of the Kibo platform. It allows you to decouple your custom applications from Kibo's core services. This is useful for building scalable, event-driven architectures.
* **Orders**: Subscribe to `order.opened` to send a notification to a custom order fulfillment system.
* **Customer**: Subscribe to `customer.account.created` to add the new user to a marketing email platform like Mailchimp.
* **Inventory**: Subscribe to `product.instock.update` to alert staff when a popular item is back in stock.
* **Returns**: Subscribe to `return.opened` to trigger a workflow in a customer support tool like Zendesk.
***
## Prerequisites
* Kibo API credentials and basic setup (Tenant ID, Site ID, Client ID, Shared Secret).
* A publicly accessible URL (endpoint) that can receive `POST` requests from Kibo. Services like [ngrok](https://ngrok.com/) are excellent for local development.
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Webhook Subscriptions** and **Event** payloads (based on official API specs).
* The key patterns Kibo uses for event management (verified from apidocs.kibocommerce.com).
* Common workflows like creating subscriptions and debugging failed deliveries using the Dead Letter Queue (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to find available event topics in the official API documentation.
***
***
## Kibo Webhooks Fundamentals
### How Kibo Organizes Event Data
Kibo's eventing system is built on two primary concepts:
* **`EventSubscription`**: This is the configuration object for your webhook. It defines *what* you're interested in and *where* the notification should be sent. Key properties include:
* `id`: The unique identifier for the subscription.
* `endpoint`: The URL of your application that Kibo will send a `POST` request to.
* `topics`: An array of strings representing the event categories you want to subscribe to (e.g., `product.created`, `order.fulfilled`).
* `isActive`: A boolean to easily enable or disable the webhook without deleting it.
* **`Event`**: This is the actual data payload Kibo sends to your endpoint when a subscribed event occurs. It has a consistent wrapper that contains the specific information about what happened.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials. This object is then passed to the constructor of the `EventApi` client. The client will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call to manage your subscriptions.
**Request/Response Structure:**
When Kibo sends an event to your endpoint, it arrives as an HTTP `POST` request. The body of the request is a JSON object with a standard structure:
```json theme={null}
// Actual event payload structure from Kibo's API documentation
{
"eventId": "15d3d789-322e-41c1-90a6-16f0b480749e",
"topic": "product.created",
"entityId": "12345", // The ID of the product that was created
"tenantId": 1234,
"masterCatalogId": 1,
"catalogId": 1,
"siteId": 5678,
"correlationId": "ABC-DEF-GHI",
"isTest": false,
"data": {
// The actual data for the entity can be extended here
// but often you use the entityId to fetch the full object
}
}
```
**Error Handling Approach (Dead Letter Queue):**
What happens if your endpoint is down or returns an error? Kibo won't just discard the event. After several failed delivery attempts, it places the event in a **Dead Letter Queue (DLQ)** specific to that subscription. This allows you to inspect and manually retry failed events, ensuring no data is lost.
***
### Common Webhook Workflows
Kibo developers typically work with webhooks in these scenarios:
1. **Creating and Managing Subscriptions**: Setting up new webhooks to connect Kibo to other systems.
2. **Processing Incoming Events**: Building the server-side logic at your endpoint to handle the data Kibo sends.
3. **Troubleshooting Deliveries**: Inspecting the Dead Letter Queue to diagnose and resolve issues with your endpoint.
Let's explore each pattern step by step.
***
***
## Listing Event Subscriptions: The Kibo Way
### When You Need This
Before creating a new webhook, you often want to see what subscriptions are already configured for your Kibo tenant. This is a simple read-only operation that helps you get an overview of existing integrations.
### API Documentation Reference
* **Endpoint:** `GET /api/event/push/subscriptions`
* **Method:** `GET`
* **SDK Method:** `getSubscriptions`
### Understanding the Kibo Approach
Kibo provides a straightforward endpoint to list all configured subscriptions. This allows for easy auditing and management. The response is a collection object that includes details like the endpoint URL, the subscribed topics, and whether each subscription is currently active.
### Code Structure Walkthrough
Before we implement, let's understand what we're building (based on actual API requirements):
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Event Push Subscriptions resource.
// 3. **API Call**: Use the 'EventApi' client to call the 'getSubscriptions' method.
// 4. **Process Results**: Log the retrieved subscriptions to the console.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Event/Webhook operations.
// These imports are verified from @kibocommerce/rest-sdk documentation.
import { Configuration } from "@kibocommerce/rest-sdk";
import { EventApi, SubscriptionApi } from "@kibocommerce/rest-sdk/clients/Event";
// Configuration setup - this single object is reused for all API clients.
// It holds all necessary credentials for authentication and routing.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function fetches and displays all event subscriptions.
async function listAllEventSubscriptions() {
// 1. Instantiate a dedicated client for the Event Push API.
const subscriptionApi = new SubscriptionApi(configuration);
console.log("Attempting to fetch all event subscriptions...");
// 2. Call the 'getSubscriptions' method on the client.
// Always wrap API calls in a try/catch block.
try {
const subscriptionCollection = await subscriptionApi.getSubscriptions();
if (subscriptionCollection.items && subscriptionCollection.items.length > 0) {
console.log(`Success: Found ${subscriptionCollection.totalCount} subscriptions:`);
subscriptionCollection.items.forEach(sub => {
console.log(`
------------------------------------
ID: ${sub.id}
Endpoint: ${sub.endpoint}
Active: ${sub.isActive}
Topics: ${sub.topics?.join(', ')}
------------------------------------
`);
});
} else {
console.log("No event subscriptions found for this tenant.");
}
return subscriptionCollection;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
listAllEventSubscriptions();
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the standard `Configuration` object needed for authentication.
* The **API call** was made using an instance of `SubscriptionApi`. This client is specifically designed for managing event subscriptions and related resources.
* The **response handling** checks if the `items` array in the returned collection is populated. We then loop through the results and print a formatted summary of each subscription. A `try...catch` block is used to gracefully handle any potential API errors.
### Common Beginner Mistakes
**Mistake 1:** Looking for event logs instead of subscriptions.
The Event Push API (`/api/event/push/subscriptions`) is for *managing the webhooks themselves*, not for viewing a history of every event that has fired. To debug deliveries, you check the Dead Letter Queue.
**Mistake 2:** Confusing Push Subscriptions with Pull Queues.
Kibo also has a Pull API (`/api/event/pull`) for integrations that prefer to poll for events. The `EventApi` SDK client manages both. Ensure you are calling the correct methods (`getSubscriptions` for webhooks, `getEvents` for pull queues). This guide focuses on the more common webhook (push) pattern.
***
***
## Multiple Real-World Examples
Here are 3 complete, production-ready examples for common `Webhook` operations.
### Example 1: List Events in a Dead Letter Queue (DLQ)
Essential for debugging. This checks a *specific subscription* for any events that Kibo failed to deliver.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { EventApi } from "@kibocommerce/rest-sdk/clients/Event";
// (Use the same 'configuration' object as defined previously)
async function checkDeadLetterQueue() {
const subscriptionApi = new SubscriptionApi(configuration);
try {
const deadLetterEvents = await subscriptionApi.getDeliveryAttemptSummariesAllSubscriptions();
if (deadLetterEvents.items && deadLetterEvents.items.length > 0) {
console.warn(`Warning: Found ${deadLetterEvents.totalCount} failed events in the DLQ!`);
deadLetterEvents.items.forEach(event => {
console.log(` - Event ID: ${event.id}, Next Attempt: ${event.nextExecutionDate}`);
});
} else {
console.log("The Dead Letter Queue is empty. All deliveries were successful.");
}
return deadLetterEvents;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
if (error.body?.errorCode === 'ITEM_NOT_FOUND') {
console.error("Could not find a subscription with that ID.");
}
}
}
// Usage
// checkDeadLetterQueue();
```
### Example 2: View Events Sent
This example shows the alternative "pull" pattern. Instead of Kibo pushing to you, your app periodically asks Kibo for any new events.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { EventApi } from "@kibocommerce/rest-sdk/clients/Event";
// (Use the same 'configuration' object as defined previously)
async function pullSentEventsFromQueue() {
const eventApi = new EventApi(configuration);
console.log("Attempting to pull events from the queue...");
try {
// This fetches a batch of events. You would run this on a schedule (e.g., every 5 minutes).
const eventCollection = await eventApi.getEvents();
if (eventCollection.items && eventCollection.items.length > 0) {
console.log(`Success: Pulled ${eventCollection.events.length} events.`);
eventCollection.items.forEach(event => {
console.log(` - Processing Event ID: ${event.id}, Topic: ${event.topic}`);
});
} else {
console.log("No new events in the pull queue.");
}
return eventCollection;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// pullEventsFromQueue();
```
### Example 3: Get Events By Topic
Useful when you need to filter events to a specific topic.
```ts theme={null}
// ... imports and configuration setup ...
import { EventApi } from "@kibocommerce/rest-sdk/clients/Event";
async function getEventsByTopic(eventTopic: string) {
const eventApi = new EventApi(configuration);
console.log(`Fetching details for event topic: ${eventTopic}`);
try {
const subscription = await eventApi.getEvents({ filter: `topic eq ${eventTopic}` });
console.log("Success: Found subscription:", JSON.stringify(subscription, null, 2));
return subscription;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// getEventsByTopic("order.opened");
```
***
***
## Troubleshooting Your Webhook Implementation
### Reading Kibo Error Messages
When managing subscriptions via the API, errors are structured just like other Kibo APIs.
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string; // Human-readable description of the error
errorCode: string; // A specific code for programmatic handling
correlationId: string; // Unique ID for this request, useful for support tickets
}
}
```
**Common Error Codes for Webhooks:**
* `VALIDATION_ERROR`: The request body for creating/updating a subscription is invalid. This often means the `endpoint` URL is malformed or a `topic` does not exist.
* `ITEM_NOT_FOUND`: You tried to get, update, or check the DLQ for a `subscriptionId` that doesn't exist.
* `REQUIRED_FIELD_MISSING`: Your request to create a subscription is missing a required field like `endpoint` or `topics`.
**Reference:** [Status Codes](/pages/status-codes)
### Common Development Issues
**Issue 1:** My endpoint isn't receiving any events.
* **Why it happens:**
1. The subscription is marked as `isActive: false`.
2. Your endpoint URL is incorrect, inaccessible from the public internet, or blocked by a firewall.
3. Your endpoint is returning an error status code (e.g., 500 Server Error, 400 Bad Request), causing Kibo to stop trying and place the event in the DLQ.
4. `Disable Callbacks` is enabled. If the same credentials that are generating the event, are also receiving the event, this will prevent events being emitted.
* **How to fix it:**
1. Use `getSubscriptionDetails` to verify the subscription is active and the URL is correct.
2. Use a tool like `ngrok` to expose your local development server to the internet for testing.
3. **Check the Dead Letter Queue!** Use the `checkDeadLetterQueue` example function. This is the most important debugging step.
4. Ensure your endpoint returns a `2xx` status code (e.g., `200 OK` or `202 Accepted`) immediately upon receiving an event.
**Issue 2:** How do I know which `topics` are available to subscribe to?
* **Why it happens:** The list of available event topics is extensive and not immediately obvious from the API endpoints for managing subscriptions.
* **How to find it:** The Kibo documentation maintains a list of all available events. Always refer to the official documentation for an up-to-date list before creating a subscription. Creating a subscription with a non-existent topic will result in a `VALIDATION_ERROR`.
* **Reference:** Search for "Kibo Event Topics" on the official Kibo documentation site.
### Debugging Checklist
When your webhook implementation isn't working:
1. **Verify Subscription:** Is the subscription `isActive`? Is the `endpoint` URL publicly accessible and correct?
2. **Check the DLQ:** Is Kibo trying to send events but failing? Use `getDeadLetterEvents` with your `subscriptionId` to find out. This is your primary diagnostic tool.
3. **Inspect Endpoint Logs:** Is your server receiving the `POST` request from Kibo? Is it throwing an unhandled exception?
4. **Confirm Response Code:** Is your endpoint code *always* returning a `200 OK` response, even if your internal processing fails? Acknowledge receipt first, then process.
5. **Validate Topics:** Does the topic you subscribed to (`order.opened`) actually exist in the Kibo documentation?
6. **Check API Credentials:** Are your API calls to manage subscriptions failing? Double-check your `Configuration` object for correct credentials.
# Developer Guides Overview
Source: https://docs.kibocommerce.com/developer-guides/index
Technical API guides for building integrations with the Kibo Commerce platform
# Developer Guides
Welcome to the Kibo Commerce Developer Guides. These technical guides provide hands-on tutorials and code examples for working with Kibo's APIs, helping you build robust integrations and custom solutions.
## Catalog & Products
Managing products, attributes, product types, and categories
Customer-facing product display, search, and navigation
Price lists, pricing strategies, and B2B/B2C pricing
Location-based inventory management and stock tracking
## Commerce & Orders
Managing shopping carts and checkout flows
Order imports for OMS integrations
Temporary inventory holds during checkout
Recurring orders and subscription management
## Fulfillment & Locations
Fulfillment shipment management and dispatch
Physical package creation and tracking
Intelligent fulfillment routing and distribution
Managing fulfillment locations and capabilities
Grouping locations for inventory and routing
## Platform & Administration
Customer accounts, addresses, and authentication
User management, roles, and permissions
Business configuration and site settings
Custom data storage for extensions
## Data & Events
Bulk data operations and file management
Webhook subscriptions and event notifications
## How to Use These Guides
Each developer guide follows a consistent structure designed to help you quickly understand and implement API integrations:
1. **Understanding the Domain** - High-level overview of the API's purpose and architecture
2. **How It Fits Into Kibo** - Integration points with other platform domains
3. **Prerequisites** - Required setup and knowledge
4. **Fundamentals** - Core concepts and data structures
5. **Code Examples** - Working code samples with explanations
6. **Common Mistakes** - Pitfalls to avoid
7. **Troubleshooting** - Error handling and debugging tips
## Getting Started
If you're new to Kibo API development, we recommend starting with these foundational guides:
1. \[Catalog Admin API]\(/developer-guides/catalog-admin-api - How to manage product data
2. [Cart API](/developer-guides/cart) - Building shopping experiences
3. [Inventory API](/developer-guides/inventory) - Understanding location-based inventory
4. [Customer API](/developer-guides/customer) - Managing customer accounts
## Need Help?
These developer guides provide hands-on code examples for API integration. For conceptual overviews and business context, see the [Concept Guides](/concept-guides/index). For complete API specifications, visit the [API Reference](/api-overviews/getting-started).
# Inventory API
Source: https://docs.kibocommerce.com/developer-guides/inventory
Location-based inventory management, stock levels, and availability tracking
# Kibo Inventory API Developer Guide
Understand inventory architecture and concepts
Configure safety stock thresholds in the Admin UI
View and manage inventory segments in the Admin UI
Configure inventory attributes in the Admin UI
See practical examples of inventory workflows
Understand real-time inventory service architecture
## Understanding Inventory in Kibo
In Kibo, "Inventory" is not just a single number representing a product's stock. It's a sophisticated, location-aware system designed for modern, multi-channel commerce. Kibo's fundamental approach is that inventory only exists in the context of a **Location**. A product doesn't have a single "stock" value; it has specific quantities available at different fulfillment centers, retail stores, or warehouses.
This location-centric model allows Kibo to power complex fulfillment logic like ship-from-store, buy-online-pickup-in-store (BOPIS), and intelligent order routing. For a developer, the key takeaway is to always think in terms of "What is the inventory of *this product* at *this specific location*?"
***
## How This Domain Fits Into Kibo
The Inventory domain is a core service that underpins the entire commerce lifecycle. It's the source of truth for product availability.
* **Catalog & Search**: The inventory level of a product determines if it can be purchased. Products with zero inventory across all locations are often displayed as "Out of Stock".
* **Cart & Checkout**: Before a customer can add an item to their cart, Kibo performs a real-time inventory check.
* **Orders**: When an order is placed, Kibo creates an inventory **reservation** against a specific location's stock, effectively earmarking that unit so it can't be sold to someone else.
* **Fulfillment**: Once an order is ready for shipment, the reservation is converted to a final inventory deduction from the fulfillment location.
***
## Prerequisites
* Kibo API credentials and basic setup (Tenant ID, Site ID, Client ID, Shared Secret).
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Inventory** data, including the importance of locations (based on official API specs).
* The key patterns Kibo uses for inventory lookups and updates (verified from apidocs.kibocommerce.com).
* Common workflows like checking stock, making adjustments, and setting up automated exports (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official API documentation for the Inventory domain.
***
***
## Kibo Inventory Fundamentals
### How Kibo Organizes Inventory Data
Kibo's Inventory data model is designed for scalability and real-time accuracy. The core entities are:
* **`ItemQuantity`**: The central object representing the stock level of a single product (`partNumber` or `upc`) at a specific `locationCode`. It contains values like `onHand`, `available`, and `onOrder`.
* **`Location`**: A physical place that holds stock. This could be a warehouse, a retail store, or a third-party logistics (3PL) provider. Every inventory record is tied to a location code.
* **`Job`**: For large-scale inventory updates (e.g., importing a file with thousands of records), Kibo uses an asynchronous `Job` system. You submit a file or request, and Kibo processes it in the background. You can then query the job's status to see if it succeeded or failed.
* **`Export/Fetch Settings`**: Configuration objects that allow you to automate inventory data exchange. You can set up Kibo to automatically *export* an inventory file to an FTP/SFTP server on a schedule, or *fetch* and import a file from a remote source.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials. This object is then passed to the constructor of specific API clients (e.g., `new InventoryApi(configuration)`). The clients handle the OAuth 2.0 token exchange for every API call.
**Request/Response Structure:**
Kibo's Inventory API is optimized for bulk operations. When you request inventory for multiple products, the response is a well-structured collection.
```json theme={null}
// Actual response schema from the POST /api/commerce/inventory/v5/inventory endpoint
[
{
"locationName": "Dallas FC",
"locationCode": "DFW1",
"active": true,
"tenantID": 100041,
"onHand": 3,
"available": 3,
"allocated": 0,
"pending": 0,
"upc": "41020990357584",
"blockAssignment": false,
"holdBlockAssignment": false,
"ltd": 0,
"floor": 0,
"safetyStock": 0,
"distance": 0.003743714,
"directShip": true,
"deliveryEnabled": false,
"transferEnabled": false,
"pickup": false,
"countryCode": "US",
"attributes": []
},
{
"locationName": "Dallas FC",
"locationCode": "DFW1",
"active": true,
"tenantID": 100041,
"onHand": 1000,
"available": 996,
"allocated": 4,
"pending": 0,
"upc": "CampStove_003",
"blockAssignment": false,
"holdBlockAssignment": false,
"ltd": 0,
"floor": 0,
"safetyStock": 0,
"distance": 0.003743714,
"directShip": true,
"deliveryEnabled": false,
"transferEnabled": false,
"pickup": false,
"countryCode": "US",
"attributes": []
},
]
```
**Error Handling Approach:**
If an API call fails, the SDK throws a structured error. For inventory, a common error is `ITEM_NOT_FOUND` if you request a product that doesn't exist in the catalog or `LOCATION_NOT_FOUND` for an invalid location code.
**Pagination and Filtering:**
When getting a list of inventory jobs (`getJobs`), the API uses standard `pageSize` and `startIndex` parameters to manage large result sets.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs under the "Inventory" section at:
`/developer-guides/inventory`
***
### Common Inventory Workflows
Kibo developers typically work with Inventory in these scenarios:
1. **Real-time Stock Lookups**: A storefront checking if a product is available for purchase or in-store pickup.
2. **Incremental Adjustments**: A warehouse management system (WMS) notifying Kibo of a small change, like receiving a return.
3. **Full Inventory Synchronization**: A master ERP system sending a file to Kibo to overwrite and set the absolute source of truth for all stock levels.
Let's explore each pattern step by step.
***
***
## Getting Inventory (POST): The Kibo Way
### When You Need This
This is the most efficient way to check stock for multiple products across multiple locations in a single API call. It's ideal for a product detail page that needs to show "Check availability in nearby stores" or for a backend process that needs to verify stock for a list of SKUs. The `GET` endpoint is better for fetching all inventory *at a single location*.
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/inventory/v1/inventory`
* **Method:** `POST`
* **SDK Method:** `postQueryInventory`
* **API Docs:** [Query Inventory](/api-reference/inventory/get-inventory-post)
### Understanding the Kibo Approach
Kibo provides a `POST` endpoint for inventory lookups to handle complex queries that would be difficult to express in a URL. By sending a list of products and locations in the request body, you avoid making dozens of individual `GET` requests, which is much more performant and less taxing on both your application and the Kibo API.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Inventory resource.
// 3. **Data Preparation**: Construct the 'InventoryRequest' object with the products and locations we want to query.
// 4. **API Call**: Use the 'InventoryApi' client to call the 'postQueryInventory' method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Inventory operations.
// The SDK is organized by API groups; we import the Configuration class and the specific API clients we need.
import { Configuration } from "@kibocommerce/rest-sdk";
import { InventoryApi } from "@kibocommerce/rest-sdk/clients/Inventory";
import { InventoryRequest } from "@kibocommerce/rest-sdk/models/Inventory";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function checks inventory for specific products at given locations.
async function checkProductInventory() {
// 1. Instantiate a dedicated client for the Inventory API.
const inventoryApi = new InventoryApi(configuration);
// 2. Prepare the request body.
// This object must match the 'InventoryRequest' schema defined in the Kibo API documentation.
const payload: InventoryRequest = {
type: "ANY",
items: [
{ partNumber: "SHIRT-BLUE-SM", upc: "111222333444", quantity: "1" },
{ partNumber: "PANTS-BLK-32", upc: "555666777888", quantity: "1" },
],
locationCodes: ["WAREHOUSE-01", "STORE-AUSTIN"],
// You can set 'includeNegativeInventory' to true if needed
};
console.log("Attempting to fetch inventory for multiple items...");
// 3. Call the 'postQueryInventory' method on the client.
try {
const inventoryCollection = await inventoryApi.postQueryInventory({
inventoryRequest: payload,
});
console.log("Success: Inventory data received:");
inventoryCollection.items?.forEach(locationInventory => {
console.log(`\n--- Location: ${locationInventory.locationCode} ---`);
locationInventory.items?.forEach(item => {
console.log(` - Product: ${item.partNumber}, Available: ${item.available}`);
});
});
return inventoryCollection;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
checkProductInventory();
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the `Configuration` object required for authentication.
* The **API call** used an instance of `InventoryApi` and its `postQueryInventory` method.
* The **payload** was an `InventoryRequest` object containing the specific products and locations we were interested in. This is Kibo's pattern for efficient, targeted lookups.
* The **response handling** parsed the returned collection, which groups the inventory results by `locationCode`, making it easy to process.
### Common Beginner Mistakes
**Mistake 1:** Making multiple `GET` requests instead of a single `POST`.
```ts theme={null}
// Wrong (inefficient) - This makes one API call per product/location combo.
for (const product of products) {
for (const location of locations) {
// await inventoryApi.getInventory({ locationCode: location, partNumber: product.partNumber });
}
}
// Correct - Use the bulk endpoint for much better performance.
const inventory = await inventoryApi.postQueryInventory({ inventoryRequest: { items, locationCodes } });
```
**Mistake 2:** Confusing `onHand` vs. `available`.
* **`onHand`**: The total physical quantity of an item at a location.
* **`available`**: The quantity that is actually available for sale. This is typically `onHand` minus any `reservations` for open orders. You should almost always use `available` for storefront logic.
***
***
## Multiple Real-World Examples
Here are 5 complete, production-ready examples for common `Inventory` operations.
### Example 1: Make an Incremental Stock Adjustment
Use this to report small changes, like when a damaged item is removed from stock or a return is processed. This *adds or subtracts* from the current quantity.
* **API Docs:** [Adjust Inventory](/api-reference/modifyinventory/adjust)
```ts theme={null}
// ... imports and configuration setup ...
import { InventoryApi } from "@kibocommerce/rest-sdk/clients/Inventory";
import { InventoryAdjustment } from "@kibocommerce/rest-sdk/models/Inventory";
async function adjustStockQuantity() {
const inventoryApi = new InventoryApi(configuration);
// Prepare a list of adjustments.
// A positive quantity increases stock, a negative quantity decreases it.
const adjustments: InventoryAdjustment[] = [{
"locationCode": "WAREHOUSE-01",
"items": [
{
"upc": "PANTS-BLK-32", //mandatory field
"quantity": 10, //+ve adjustment as a result of cyclecount
"safetyStock": 2 //increasing safety stock by 2
},
{
"upc": "PANTS-BLK-33",
"quantity": -2, //negative adjustment, found damaged product
"safetyStock": 0 // no change in safety stock
}
]
}];
console.log("Submitting inventory adjustment...");
try {
await inventoryApi.adjust({ inventoryAdjustment: adjustments });
console.log("Success: Inventory adjustment completed.");
} catch (error: any)
{
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// adjustStockQuantity();
```
### Example 2: Set the Absolute Stock Quantity (Refresh)
Use this when you want to set the absolute stock level from a master system, overriding whatever value Kibo currently has. This is a "set" operation, not an "add/subtract".
* **API Docs:** [Refresh Inventory](/api-reference/modifyinventory/refresh)
For variable batch sizes, consider using the [Smart Adjust](/api-reference/modifyinventory/smart-adjust-inventory) and [Smart Refresh](/api-reference/modifyinventory/smart-refresh-inventory) APIs which automatically route requests to synchronous or asynchronous processing based on payload size. See the [Smart Inventory APIs guide](/pages/smart-inventory-apis) for more details.
```ts theme={null}
// ... imports and configuration setup ...
import { InventoryApi } from "@kibocommerce/rest-sdk/clients/Inventory";
import { RefreshRequest } from "@kibocommerce/rest-sdk/models/Inventory";
async function refreshStockLevels() {
const inventoryApi = new InventoryApi(configuration);
// Prepare a refresh request. This will SET the onHand quantity to the specified value.
const payload: RefreshRequest = {
locationCode: "WAREHOUSE-01",
items: [{
partNumber: "PANTS-BLK-32",
upc: "PANTS-BLK-32",
sku: "PANTS-BLK-32",
ltd: 0,
floor: 0,
quantity: 250, // Our ERP says we have exactly 250 units.
safetyStock: 0, //Represents qty for balancing minimum qty at location
condition: "", //Any particular tags used for inventory like damaged
deliveryDate: "", //Date at which particular qty is expected, often used along with condition
externalID: "", //Any reference number like purchase order
}]
};
console.log("Refreshing inventory from source of truth...");
try {
await inventoryApi.refresh({ refreshRequest: payload });
console.log("Success: Inventory refresh completed.");
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// refreshStockLevels();
```
### Example 3: Create an Automated Daily Inventory Export
This sets up a recurring job in Kibo to automatically generate an inventory report and upload it to an FTP/SFTP server.
If you need to sync only recently changed inventory records to a downstream system on a frequent schedule (e.g., every 30 minutes), see the [Inventory Delta Export Feed](/pages/inventory-delta-export-feed) — a Kibo-managed export that delivers incremental CSV files without requiring API configuration.
* **API Docs:** [Create Export Settings](/api-reference/exportinventory/create-export-settings)
```ts theme={null}
// ... imports and configuration setup ...
import { ExportSettingsApi } from "@kibocommerce/rest-sdk/clients/Inventory";
import { ExportSettings } from "@kibocommerce/rest-sdk/models/Inventory";
async function createDailyExport() {
// Note: We use the dedicated 'ExportSettingsApi' for this.
const exportApi = new ExportSettingsApi(configuration);
const exportConfig: ExportSettings = {
exportSettings: {
name: "Daily_ERP_Inventory_Sync", // Must be unique
fileFormat: "CSV", //supported format are XML, CSV
exportType: "AGGREGATE", //Type can be LOCATION, AGGREGATE
ftpInformation: {
name: "client ftp"
ftpServer: "ftp.my-erp.com",
ftpPort: "22",
ftpUser: "kibo-ftp-user",
ftpPassword: "SecurePassword123", // Use secrets management in production
ftpDirectory: "/incoming/inventory/"
}
}
};
console.log(`Creating export settings: ${exportConfig.name}`);
try {
const newExport = await exportApi.createExportSettings({ exportSettings: exportConfig });
console.log("Success: Created new export settings with name:", newExport.name);
return newExport;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// createDailyExport();
```
### Example 4: Check the Status of Inventory Jobs
After an export runs (or you submit a large import), you can check the status of the background job.
* **API Docs:** [Get Jobs](/api-reference/inventoryjob/get-jobs)
```ts theme={null}
// ... imports and configuration setup ...
import { JobApi } from "@kibocommerce/rest-sdk/clients/Inventory";
async function checkRecentJobs() {
// Note: We use the 'JobApi' for this operation.
const jobApi = new JobApi(configuration);
console.log("Fetching recent inventory jobs...");
try {
const jobCollection = await jobApi.getJobs({ pageSize: 5 }); // Get the 5 most recent
console.log(`Success: Found ${jobCollection.totalCount} total jobs.`);
jobCollection.items?.forEach(job => {
console.log(`
- Job ID: ${job.jobID}, Type: ${job.type}, Status: ${job.status}
`);
});
return jobCollection;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// checkRecentJobs();
```
### Example 5: Configure an Automated Inventory Fetch Job
This tells Kibo to periodically check an SFTP server for a file, download it, and import it. This is the inverse of an export.
* **API Docs:** [Save Fetch File Config](/api-reference/inventoryfetchfileconfig/save-fetch-config)
```ts theme={null}
// ... imports and configuration setup ...
import { FetchFileConfigApi } from "@kibocommerce/rest-sdk/clients/Inventory";
import { FetchFileConfig } from "@kibocommerce/rest-sdk/models/Inventory";
async function setupInventoryImport() {
const fetchApi = new FetchFileConfigApi(configuration);
const fetchConfig: FetchFileConfig = {
active: "true",
ftpServer: "sftp.my-wms.com",
ftpUsername: "kibo-sftp",
ftpPassword: "123*",
ftpPort: "22",
// In a real scenario, you'd use SFTP private key authentication
ftpRemotePath: "/outgoing/kibo-updates/*.csv",
ftpRemotePathArchive: "/outgoing/kibo-updates/archive/",
lockName: "inventory.lock",
postProcessAction: "1", //1 - move to archive, 2 - delete, 0 - do nothing
};
console.log("Saving fetch file configuration...");
try {
const newConfig = await fetchApi.saveFetchFileConfig({ fetchFileConfig: fetchConfig });
console.log("Success: Configuration saved.", newConfig);
return newConfig;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// setupInventoryImport();
```
***
***
## Integrating Inventory with Other Kibo Domains
### Inventory + Orders Integration
This is the primary integration. When a customer places an order, Kibo's order management system automatically creates an inventory reservation for each item in the order against a specific location's stock. This `available` quantity is immediately reduced. When the order is fulfilled (shipped), the `onHand` quantity is then decremented. This ensures you never oversell a product.
### Inventory + Catalog Integration
The inventory level directly impacts how products are displayed on the storefront. You can configure your Kibo site theme to:
* Show "Out of Stock" badges.
* Hide the "Add to Cart" button.
* Display low stock warnings ("Only 3 left!").
This is typically handled by checking the `available` count of a product returned from the Catalog APIs, which internally query the Inventory service.
***
***
## Troubleshooting Your Inventory Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string;
errorCode: string; // e.g., "ITEM_NOT_FOUND"
correlationId: string;
// For some errors, additional context is provided
items?: Array<{
name: string;
errorCode: string;
message: string;
}>
}
}
```
**Common Error Codes for Inventory:**
* `ITEM_NOT_FOUND`: The `partNumber` or `upc` you sent does not exist in the Kibo catalog.
* `LOCATION_NOT_FOUND`: The `locationCode` is invalid or not active.
* `VALIDATION_ERROR`: The request body is malformed. The `items` array in the error response will often pinpoint the exact field that is wrong.
* `JOB_ALREADY_EXISTS`: When creating an export setting, the `name` you provided is already in use.
### Common Development Issues
**Issue 1:** Inventory updates seem delayed or are not appearing.
* **Why it happens:** Large inventory updates via file import are processed asynchronously by Kibo's job system. It can take a few minutes for the job to be picked up and processed, especially in a busy environment.
* **How to fix it:** After submitting an import, use the `getJobs` endpoint to monitor the status of the job. Don't assume the update is instantaneous. Look for the job to reach a `COMPLETED` status.
* **API Reference:** [Get Jobs](/api-reference/inventoryjob/get-jobs)
**Issue 2:** What is the difference between `Adjust` and `Refresh`?
* **Why it happens:** This is a common point of confusion. Using the wrong one can lead to incorrect inventory levels.
* **How to fix it:**
* Use **`Adjust`** for **incremental changes**. It's a `+` or `-` operation. Example: "Received 5 new units," or "Removed 1 damaged unit."
* Use **`Refresh`** for **absolute changes**. It's a `set` operation. Example: "Our master system says there are exactly 100 units. Make Kibo match this number, regardless of what it was before."
* **How to avoid it:** For daily syncs from an ERP or master system, always use `Refresh`. For real-time updates from a WMS based on individual events (like receiving a shipment), use `Adjust`.
### Debugging Checklist
1. **Check Location Codes:** Are the `locationCode` strings you're sending an exact match for the codes set up in Kibo Admin?
2. **Check Product Identifiers:** Do the `partNumber` or `upc` values exist in the Master Catalog?
3. **Monitor Jobs:** For file-based imports/exports, are you checking the `JobApi` for the status? Look for `FAILED` jobs and inspect their details.
4. **Verify Payloads:** `console.log` your request body before sending it. Does it exactly match the schema shown in the API documentation?
5. **Check `available` vs. `onHand`:** Are you looking at the correct inventory field for your use case? (Storefronts use `available`, backend reports might use `onHand`).
6. **Review Cron Expressions:** For scheduled jobs, double-check your cron syntax. An invalid expression will prevent the job from ever running.
# Location Admin API
Source: https://docs.kibocommerce.com/developer-guides/location-admin
Managing fulfillment locations, capabilities, and operational settings
# Kibo Location (Admin) API Developer Guide
Understand how locations fit into fulfillment
Configure location types in the Admin UI
## Understanding Locations in Kibo
In Kibo, a **Location** is far more than just a physical address. It's a fundamental operational entity that represents any place where inventory is stored, from which orders can be fulfilled, or where customers can pick up purchases. This could be a massive warehouse, a retail store, a third-party drop-shipper, or even a virtual holding location.
What makes Kibo's approach different is that each Location is defined by its **capabilities**. You explicitly declare what a location can *do* using `fulfillmentTypes` (e.g., `DirectShip`, `InStorePickup`) and what it *is* using `locationTypes` (e.g., `Warehouse`, `Store`). This rich data model allows Kibo's advanced order routing and fulfillment logic to make intelligent decisions about how to process customer orders efficiently.
## How This Domain Fits Into Kibo
The Location domain is the foundation of Kibo's omnichannel commerce capabilities. It is linked to several other core domains:
* **Inventory:** Inventory levels are not stored globally; they are tracked *per Location*. To know if a product is in stock, you must ask, "How many are in stock at the Austin warehouse?"
* **Fulfillment & Orders:** When an order is placed, Kibo's fulfillment engine consults the list of Locations. It checks their inventory and their `fulfillmentTypes` to determine the optimal location(s) from which to source the order's shipments.
* **Returns:** Locations can be designated as places where customers can return items purchased online.
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures Location data, including its types and fulfillment capabilities (based on official API specs).
* The key patterns for creating, updating, and managing your physical and virtual locations (verified from apidocs.kibocommerce.com).
* Common workflows like onboarding a new warehouse or managing holiday shipping exceptions.
* How to avoid the most common beginner mistakes, like performing a partial update incorrectly.
* How to read and navigate the official Location Administration API documentation effectively.
***
## Kibo Location Fundamentals
### How Kibo Organizes Location Data
The system revolves around a few core data structures:
* **`Location`**: The central object. It is uniquely identified by a `code` (a user-defined string like `DAL-WAREHOUSE-01`). It contains properties like `name`, `address`, `phone`, and, most importantly, arrays defining its capabilities:
* **`fulfillmentTypes`**: An array of strings defining what the location can do. Key values verified from API docs include `DirectShip` (ship-to-home) and `InStorePickup` (BOPIS).
* **`locationTypes`**: An array of strings defining what the location is. Key values include `Store`, `Warehouse`, and `DropShipper`.
* **`CutoffTimeOverride`**: A subordinate object linked to a `Location`. It allows you to define exceptions to the location's standard shipping cutoff times, which is essential for managing holidays or special events. It is identified by its own unique `code`.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new LocationAdminApi(configuration)`). The clients will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call.
**Request/Response Structure:**
When you request a collection of locations, Kibo's API provides a consistent, paginated response. The actual data is always inside the `items` array.
```json theme={null}
// Actual response schema for GET /commerce/admin/locations
{
"startIndex": 0,
"pageSize": 20,
"pageCount": 2,
"totalCount": 35,
"items": [
{
"code": "AUS-01",
"name": "Austin Downtown Store",
"isActive": true,
"fulfillmentTypes": [
"DirectShip",
"InStorePickup"
],
"locationTypes": [
"Store"
]
}
]
}
```
**Error Handling Approach:**
If an API call fails, the SDK will throw a structured error object. This helps you programmatically handle failures instead of just getting a generic HTTP status code.
```json theme={null}
// Actual error schema from Kibo
{
"message": "Location with code 'AUS-01' already exists.",
"errorCode": "LOCATION_ALREADY_EXISTS",
"correlationId": "e0b5b9b012345abcdeffe0b5b9b012345abcdef"
}
```
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_location_admin_overview`
### Common Location Workflows
Kibo developers typically work with Locations in these scenarios:
1. **Onboarding a New Fulfillment Center:** Creating a new warehouse location and defining its shipping capabilities.
2. **Synchronizing Store Information:** Running a scheduled job to update details like phone numbers or addresses for a network of retail stores from an external system of record.
3. **Managing Holiday Operations:** Adding temporary overrides to shipping cutoff times for the peak holiday season to manage customer expectations.
Let's explore each pattern step by step.
***
## Add a New Location: The Kibo Way
### When You Need This
This is the foundational step for expanding your fulfillment network. You need this whenever you open a new retail store, partner with a new warehouse, or enable a new drop-shipper.
### API Documentation Reference
**Endpoint:** `POST /commerce/admin/locations`
**Method:** `POST`
**API Docs:** [Add Location](/api-reference/locationadmin/add-location)
### Understanding the Kibo Approach
Kibo treats the `code` of a location as its permanent, unique business key. You define it once during creation, and it cannot be changed. This `code` is used throughout the platform to reference this location in inventory, fulfillment, and reporting APIs. The creation process requires you to be explicit about the location's capabilities (`fulfillmentTypes`), ensuring it's immediately ready to be integrated into the order processing workflow.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Location Administration API.
// 3. **Data Preparation**: Construct the full request body object for the new Location according to the API schema.
// 4. **API Call**: Use the instantiated client to call the `addLocation` method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Location operations.
// The SDK is organized by API groups; we import the Configuration class and the specific API client we need.
// These imports are verified from @kibocommerce/rest-sdk documentation.
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationAdminApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin";
import { Location } from "@kibocommerce/rest-sdk/clients/LocationAdmin/models";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: Understanding the Data Flow**
Our application will send a complete `Location` JSON object to the Kibo API. The API validates that the `code` is unique and the payload is correctly structured. If successful, it creates the location and returns the full `Location` object, including any server-generated values.
**Step 3: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function adds a new retail store that can also ship orders.
async function addNewRetailStore(storeDetails: Location): Promise {
console.log(`Adding new location with code: ${storeDetails.code}...`);
// 1. Instantiate a dedicated client for the Location Administration API.
const locationAdminClient = new LocationAdminApi(configuration);
// 2. The storeDetails object is our request payload.
// It must match the schema defined in the Kibo API documentation.
// 3. Call the method on the client. The method name `addLocation` corresponds to the API operation.
try {
const newLocation = await locationAdminClient.addLocation({
location: storeDetails,
});
console.log(`Success! Location "${newLocation.name}" created.`);
return newLocation;
} catch (error) {
// Handle common errors, like the location code already existing.
console.error("API Error adding location:", JSON.stringify(error, null, 2));
throw error;
}
}
// Example usage:
// const newStorePayload: Location = {
// code: "ATX-Lamar",
// name: "Austin South Lamar Store",
// description: "Our newest retail location in Austin.",
// isActive: true,
// fulfillmentTypes: [
// { code: "DS", name: "Direct Ship" }, // Verified from API schema, this is an object
// { code: "SP", name: "In Store Pickup" }
// ],
// locationTypes: [{ code: "ST", name: "Store" }],
// address: {
// address1: "123 S Lamar Blvd",
// cityOrTown: "Austin",
// stateOrProvince: "TX",
// postalOrZipCode: "78704",
// countryCode: "US"
// },
// phone: "512-555-1234"
// };
// addNewRetailStore(newStorePayload);
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the standard `Configuration` object for authentication.
* The **API call** was made using an instance of `LocationAdminApi`. This client provides type-safe methods for all location management operations.
* The **payload** we prepared was a complete `Location` object. We explicitly defined its unique `code` and its `fulfillmentTypes`, making it immediately available to Kibo's fulfillment engine.
* The **response** was the newly created `Location` object, confirming its creation.
### Common Beginner Mistakes
**Mistake 1:** Trying to update a location's `code`.
The `code` is immutable. Once a location is created with `code: "STORE-A"`, you cannot change it. To "rename" it, you would need to deactivate the old location and create a new one.
**Mistake 2:** Using `PUT` for a partial update and accidentally deleting data.
The `updateLocation` endpoint (`PUT`) performs a **full replacement** of the object. If you only send `{ "phone": "new-number" }`, you will wipe out the address, fulfillment types, and everything else. The correct pattern is to `GET` the location, modify the object, then `PUT` the entire modified object back.
***
## Advanced Patterns & Multiple Examples
### Pattern 1: Idempotent Location Synchronization
**Business Scenario:** You need a script that runs daily to sync location data from an external "source of truth" into Kibo. The script must correctly create new locations and update existing ones without creating duplicates.
**Kibo's Architecture Consideration:** The API does not have a single "upsert" endpoint. The correct, idempotent pattern is to first try to `GET` the location by its unique code. If you get a `404 Not Found` error, you know it doesn't exist and you should call `POST` to create it. If the `GET` call succeeds, you know it exists and you should call `PUT` to update it.
**API Endpoints Used:**
* `GET /commerce/admin/locations/{locationCode}`
* `PUT /commerce/admin/locations/{locationCode}`
* `POST /commerce/admin/locations`
**Implementation Strategy (Example 1: The Sync Function):**
```typescript theme={null}
// Advanced example: A function to synchronize a single location's data.
async function syncLocation(locationData: Location) {
const locationAdminClient = new LocationAdminApi(configuration);
const locationCode = locationData.code as string;
try {
// 1. Try to GET the location first.
const existingLocation = await locationAdminClient.getLocation({ locationCode });
console.log(`Location ${locationCode} exists. Updating...`);
// 2. If it exists, PUT the new data.
// Important: We send the full locationData object to replace the existing one.
await locationAdminClient.updateLocation({ locationCode, location: locationData });
console.log(`Location ${locationCode} updated successfully.`);
} catch (error: any) {
// 3. If GET fails with a 404, we know we need to create it.
if (error.status === 404) {
console.log(`Location ${locationCode} does not exist. Creating...`);
await locationAdminClient.addLocation({ location: locationData });
console.log(`Location ${locationCode} created successfully.`);
} else {
// Re-throw any other unexpected errors.
console.error(`An unexpected error occurred for location ${locationCode}:`, error);
throw error;
}
}
}
```
### Example 2: Get a Specific Location
```ts theme={null}
// A simple function to retrieve a single location by its code.
async function getLocationByCode(locationCode: string): Promise {
const locationAdminClient = new LocationAdminApi(configuration);
try {
console.log(`Fetching details for location: ${locationCode}`);
const location = await locationAdminClient.getLocation({ locationCode });
console.log("Found location:", location.name);
return location;
} catch (error: any) {
if (error.status === 404) {
console.log(`Location with code ${locationCode} not found.`);
return null;
}
throw error;
}
}
```
### Example 3: Add a Holiday Cutoff Time Override
```ts theme={null}
// Adds a special shipping cutoff time for a specific date.
async function addHolidayCutoff(id: string,locationCode: string, date: string, startTime: string, endTime:string) {
const locationAdminClient = new LocationAdminApi(configuration);
console.log(`Adding cutoff override for ${date} at ${locationCode}`);
try {
await locationAdminClient.createCutoffTimeOverride({
cutoffTimeOverride: {
id: id,
locationCode,
date, // Format: "YYYY-MM-DD"
startTime: startTime, // Format: "HH:MM:SS"
endTime: endTime, // Format: "HH:MM:SS"
}
});
console.log("Cutoff override added successfully.");
} catch (error) {
console.error("Failed to add cutoff override:", JSON.stringify(error, null, 2));
throw error;
}
}
// Usage: addHolidayCutoff("override-1","ATX-Lamar", "2025-12-23", "14:00:00", "XMAS-EVE-2025");
```
### Example 4: Get All Cutoff Overrides for a Location
```ts theme={null}
// Retrieves all configured shipping cutoff exceptions for a location.
async function listCutoffOverrides(locationCode: string) {
const locationAdminClient = new LocationAdminApi(configuration);
try {
const overrides = await locationAdminClient.getCutoffTimeOverrides({ locationCode });
console.log(`Found ${overrides.items?.length} cutoff overrides for ${locationCode}:`, overrides);
return overrides;
} catch (error) {
console.error("Failed to get cutoff overrides:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### Example 5: Delete a Cutoff Time Override
```ts theme={null}
// Removes a specific shipping cutoff exception.
async function deleteCutoffOverride(locationCode: string, overrideId: string) {
const locationAdminClient = new LocationAdminApi(configuration);
console.log(`Deleting override ${overrideId} from location ${locationCode}`);
try {
// This call returns a 204 No Content on success.
await locationAdminClient.deleteCutoffTimeOverride({ overrideId});
console.log("Override deleted successfully.");
} catch (error) {
console.error("Failed to delete cutoff override:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Integrating Location with Other Kibo Domains
### Location + Inventory Integration
Inventory is always location-specific. You cannot ask Kibo for a product's overall stock level. You must ask for its stock level at a particular location. Any API call to update or retrieve inventory will require a `locationCode`. This direct link is what enables features like ship-from-store and in-store pickup.
### Location + Fulfillment Integration
The fulfillment process is a direct consumer of Location data. When an order needs to be shipped, the fulfillment engine queries for active locations with the `DirectShip` fulfillment type and available inventory for the ordered items. The location's address is used to calculate shipping rates, and its cutoff times determine the expected ship date.
***
## Troubleshooting Your Location Implementation
### Reading Kibo Error Messages
```typescript theme={null}
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
}
```
**Common Error Codes for Location:**
* `LOCATION_ALREADY_EXISTS`: You tried to call `addLocation` with a `code` that is already in use.
* `LOCATION_NOT_FOUND`: The `locationCode` you provided in a URL (e.g., for `getLocation` or `updateLocation`) does not exist.
* `VALIDATION_ERROR`: The request body is malformed. A common cause is providing an invalid `countryCode` or malformed `fulfillmentTypes` object.
### Common Development Issues
**Issue 1:** My location was created, but it never gets assigned any shipments.
* **Why it happens:** This is almost always because the `fulfillmentTypes` array is either empty or does not contain the necessary capability, like `DirectShip`. If a location cannot ship orders, the fulfillment engine will ignore it.
* **How to fix it:** `GET` the location, add the correct fulfillment type object(s) to the array (e.g., `{ code: "DS", name: "Direct Ship" }`), and then `PUT` the entire updated location object back.
* **API Reference:** [`/api-reference/locationadmin/update-location`](/api-reference/locationadmin/update-location)
**Issue 2:** I tried to update a location's name, and now its address and phone number are gone.
* **Why it happens:** The `PUT /commerce/admin/locations/{locationCode}` endpoint performs a **complete replacement** of the location object. If your request body only contains `{"name": "New Name"}`, you are telling Kibo to replace the entire existing object with that, effectively deleting all other fields.
* **How to fix it:** This is a standard REST pattern. You **must always** `GET` the full location object first, modify the properties you want to change on that object in your code, and then `PUT` the entire modified object back in the request body. See the `syncLocation` advanced example for the correct implementation.
# Location Groups API
Source: https://docs.kibocommerce.com/developer-guides/location-group
Grouping locations for inventory aggregation and fulfillment routing
# Kibo Locations API Developer Guide
Understand how location groups fit into fulfillment
Manage location groups in the Admin UI
## Understanding Locations in Kibo
In Kibo, a **Location** is a fundamental concept representing any physical place relevant to your commerce operations. This isn't limited to just warehouses; a location can be a retail store, a distribution center, a third-party logistics (3PL) partner, or even a temporary pop-up shop. Each location has its own inventory and fulfillment capabilities.
Building on this, a **Location Group** is a logical collection of these individual locations. Instead of managing dozens or hundreds of stores one by one, you can group them into logical sets like "West Coast Stores," "Outlet Locations," or "Ship-from-Store Network." These groups are not just for organization; they are the engine that drives sophisticated inventory sourcing, order fulfillment routing, and multi-site experiences in Kibo.
***
## How This Domain Fits Into Kibo
The Locations domain is the backbone of Kibo's distributed order management and fulfillment capabilities. Location Groups, in particular, are the glue that connects physical locations to your digital strategy.
* **Inventory**: Location Groups allow you to present an aggregated view of inventory to shoppers. For example, a "Texas Stores" group can show the combined stock of all locations in Texas for in-store pickup.
* **Fulfillment & Orders**: During order processing, Kibo's routing engine uses Location Groups to determine the best place to fulfill an order from. You can define rules like "Fulfill online orders from the 'Main Warehouses' group first."
* **Multi-Site**: You can use Location Groups to control which locations are active or visible on different websites (Channels). Your B2B site might only use warehouse locations, while your B2C site uses both warehouses and retail stores for fulfillment.
***
## Prerequisites
* Kibo API credentials with appropriate administrative permissions.
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Location** and **Location Group** data (based on official API specs).
* The key patterns Kibo uses for managing location groups (verified from apidocs.kibocommerce.com).
* Common workflows like creating, viewing, and updating location groups (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official API documentation for Location administration.
***
***
## Kibo Location Group Fundamentals
### How Kibo Organizes Location Data
Kibo's Location Group data is straightforward and powerful. The core object is the `LocationGroup`.
* **`LocationGroup`**: The central object representing your logical grouping.
* `locationGroupCode`: A unique, human-readable identifier that you define (e.g., `WEST_COAST_STORES`). This is the primary key you'll use in API calls.
* `name`: A friendly name for display in the Kibo Admin UI (e.g., "West Coast Stores").
* `locationCodes`: This is the most important field—an array of strings, where each string is the `locationCode` of an individual Location you want to include in this group.
* `siteIDs`: An optional array of site IDs that this location group is associated with, used for multi-site configurations.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials. This object is then passed to the constructor of the `LocationGroupApi` client. The client automatically handles the OAuth 2.0 token exchange for every API call.
**Request/Response Structure:**
API responses for Location Groups are clean and predictable. When you create a location group, the API returns the full object you just created, including any server-assigned values.
```json theme={null}
// Actual response schema from creating a Location Group
{
"locationGroupCode": "SGFG",
"name": "All Texas Retail Locations",
"locationCodes": [
"W001",
"W002",
"W003"
],
"siteIDs": [
12345
]
}
```
**Error Handling Approach:**
If an API call fails, the SDK throws a structured error. A common error when creating a location group is a `VALIDATION_ERROR` if one of the `locationCodes` you provided doesn't actually exist in Kibo.
**Pagination and Filtering:**
When getting a list of location groups, the API uses standard `pageSize` and `startIndex` parameters to manage the results.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs under the "Tenant" administration section, as Location Groups are a tenant-level concept.
[`/api-reference/locationgroup/get-location-groups`](/api-reference/locationgroup/get-location-groups)
***
### Common Location Group Workflows
Kibo developers typically work with Location Groups in these scenarios:
1. **Initial Setup**: Programmatically creating location groups as part of an initial environment setup or migration.
2. **Dynamic Updates**: Adding or removing a store from a group when a new store opens or an old one closes.
3. **Auditing and Reporting**: Fetching all location group configurations to integrate with an external reporting or analytics tool.
Let's explore each pattern step by step.
***
***
## Adding a Location Group: The Kibo Way
### When You Need This
This is the foundational "create" operation. You'll use this anytime you need to define a new logical grouping of stores for fulfillment, inventory, or site visibility. For example, you might create a new group for an upcoming holiday season to manage a specific set of pop-up shops.
### API Documentation Reference
* **Endpoint:** `POST /api/platform/admin/locationgroups`
* **Method:** `POST`
* **SDK Method:** `addLocationGroup`
* **API Docs:** [Add Location Group](/api-reference/locationgroup/add-location-group)
### Understanding the Kibo Approach
Kibo treats Location Group creation as a simple, atomic operation. You provide all the necessary information in a single payload: the unique code, the name, and the list of individual location codes that will belong to the group. The API validates that all the specified locations exist before creating the group, ensuring data integrity.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the LocationGroup resource.
// 3. **Data Preparation**: Construct the 'LocationGroup' request body according to the API schema.
// 4. **API Call**: Use the 'LocationGroupApi' client to call the 'addLocationGroup' method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Location Group operations.
// The SDK client for this is found under the 'Tenant' group.
import dotenv from "dotenv";
dotenv.config();
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";
// Configuration setup - this single object is reused for all API clients.
// Note: Location Group management often requires higher-level API permissions.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST || "https://home.mozu.com",
});
```
**Step 2: The Core Implementation**
```ts theme={null}
async function createLocationGroup() {
try {
const api = new LocationGroupApi(configuration);
// Correct structure expected by AddLocationGroupRequest
const payload = {
locationLocationGroup: {
locationGroupId: 10, // or omit if auto-assigned
locationGroupCode: "SGFG",
siteIds: [73029],
name: "SG-Fulfillment",
locationCodes: ["W001"],
},
};
console.log(`Creating location group '${payload.locationLocationGroup.name}'...`);
const response = await api.addLocationGroup(payload);
console.log("Success: Location group created successfully:");
console.log(JSON.stringify(response, null, 2));
} catch (err) {
console.error("Error: Error creating location group:", err);
}
}
createLocationGroup();
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the `Configuration` object. Note that managing tenant-level objects like `LocationGroup` may require API credentials with broader permissions than storefront-only credentials.
* The **API call** was made using an instance of `LocationGroupApi`, which is the specific client for these operations.
* The **payload** was a `LocationGroup` object. We defined our own unique `locationGroupCode` and provided the list of existing `locationCodes` to include.
* The **response handling** uses a `try...catch` block. On success, Kibo returns the group object we just created. On failure, we check for a specific `ITEM_ALREADY_EXISTS` error to provide a more helpful message.
### Common Beginner Mistakes
**Mistake 1:** Trying to create a group with non-existent location codes.
```ts theme={null}
// Wrong - The API will reject this with a VALIDATION_ERROR.
const payload = {
locationGroupCode: "BAD_GROUP",
name: "Group with Fake Stores",
locationCodes: [
"STORE-THAT-DOES-NOT-EXIST" // Kibo validates this list
]
};
```
**Solution:** Always ensure the locations you are adding to a group have been created in Kibo first. You can use the `LocationApi` to list existing locations to verify codes.
**Mistake 2:** Using the wrong API client.
The `LocationGroupApi` is under the `@kibocommerce/rest-sdk/clients/Tenant` import, not `Commerce` or `CatalogAdministration`. Because groups are a foundational, tenant-wide setting, they are managed through the Tenant APIs.
***
***
## Multiple Real-World Examples
Here are 5 complete, production-ready examples for common `Location Group` operations.
### Example 1: Get a Specific Location Group
Fetch the configuration for a single, known location group. This is useful for checking details before an update.
* **API Docs:** [Get Location Group](/api-reference/locationgroup/get-location-group)
```ts theme={null}
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
async function getLocationGroupDetails(groupCode: string) {
const api = new LocationGroupApi(configuration);
console.log(`Fetching details for location group: ${groupCode}...`);
try {
// The SDK expects the property name to match API spec exactly:
const response = await api.getLocationGroup({ locationGroupCode: groupCode });
console.log("Success: Success! Found group:");
console.log(JSON.stringify(response, null, 2));
return response;
} catch (err: any) {
console.error("Error: Error fetching location group:", err);
if (err.apiError?.errorCode === "ITEM_NOT_FOUND") {
console.error(`No location group found with code '${groupCode}'.`);
}
}
}
getLocationGroupDetails("SGFG");
// Usage
// getLocationGroupDetails("SGFG");
```
### Example 2: Update a Location Group (Add a New Store)
This covers the common scenario of opening a new store and adding it to an existing fulfillment group.
* **API Docs:** [Update Location Group](/api-reference/locationgroup/update-location-group)
```ts theme={null}
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
import { LocationGroup } from "@kibocommerce/rest-sdk/models/Tenant";
async function addStoreToGroup(groupCode: string, newLocationCode: string) {
const api = new LocationGroupApi(configuration);
console.log(`Adding location '${newLocationCode}' to group '${groupCode}'...`);
try {
// 1. Get current group details
const currentGroup = await api.getLocationGroup({ locationGroupCode: groupCode });
console.log(`Fetched group: ${currentGroup.name}`);
// 2. Add new code (no duplicates)
const updatedCodes = Array.from(new Set([...(currentGroup.locationCodes || []), newLocationCode]));
// 3. Build payload using correct key
const payload = {
locationGroupCode: groupCode,
locationLocationGroup: {
locationGroupId: currentGroup.locationGroupId,
locationGroupCode: currentGroup.locationGroupCode,
siteIds: currentGroup.siteIds,
name: currentGroup.name,
locationCodes: updatedCodes,
},
};
// 4. Call update API
const response = await api.updateLocationGroup(payload);
console.log("Success: Successfully updated group!");
console.log(JSON.stringify(response, null, 2));
} catch (err: any) {
console.error("Error: Error updating location group:", err);
if (err.apiError) console.error("API Error:", err.apiError);
}
}
// Example run
addStoreToGroup("SGFG", "W003");
// Usage: Assumes a "W003" location has been created.
// addStoreToGroup("SGFG", "W003");
```
### Example 3: List All Location Groups
A utility function to get a high-level overview of all location groups configured in the tenant.
* **API Docs:** [Get Location Groups](/api-reference/locationgroup/get-location-groups)
```ts theme={null}
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
async function listAllLocationGroups() {
const locationGroupApi = new LocationGroupApi(configuration);
console.log("Fetching all location groups...");
try {
const groupsCollection = await locationGroupApi.getLocationGroups({ pageSize: 200 });
console.log(`Success: Found ${groupsCollection.totalCount} location groups.`);
groupsCollection.items?.forEach(group => {
console.log(` - ${group.name} (Code: ${group.locationGroupCode})`);
});
return groupsCollection;
} catch (error: any) {
console.error("Error: API Error:", JSON.stringify(error, null, 2));
}
}
listAllLocationGroups();
// listAllLocationGroups();
```
### Example 4: Remove a Store from a Location Group
The inverse of Example 2, this is for when a store closes or is no longer part of a specific fulfillment strategy.
```ts theme={null}
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
import { LocationGroup } from "@kibocommerce/rest-sdk/models/Tenant";
async function removeStoreFromGroup(groupCode: string, locationCodeToRemove: string) {
const api = new LocationGroupApi(configuration);
console.log(`Removing location '${locationCodeToRemove}' from group '${groupCode}'...`);
try {
// 1. Get current group details
const currentGroup = await api.getLocationGroup({ locationGroupCode: groupCode });
console.log(`Fetched group: ${currentGroup.name}`);
// 2. Remove the given code (instead of adding)
const updatedCodes = (currentGroup.locationCodes || []).filter(
(code) => code !== locationCodeToRemove
);
// 3. Build payload using correct key
const payload = {
locationGroupCode: groupCode,
locationLocationGroup: {
locationGroupId: currentGroup.locationGroupId,
locationGroupCode: currentGroup.locationGroupCode,
siteIds: currentGroup.siteIds,
name: currentGroup.name,
locationCodes: updatedCodes,
},
};
// 4. Call update API
const response = await api.updateLocationGroup(payload);
console.log("Success: Successfully updated group (location removed)!");
console.log(JSON.stringify(response, null, 2));
} catch (err: any) {
console.error("Error: Error updating location group:", err);
if (err.apiError) console.error("API Error:", err.apiError);
}
}
// Example run
removeStoreFromGroup("SGFG", "W002");
// Usage
// removeStoreFromGroup("SGFG", "W002");
```
### Example 5: Delete a Location Group
Permanently remove a location group. This does *not* delete the individual locations within it.
* **API Docs:** [Delete Location Group](/api-reference/locationgroup/delete-location-group)
```ts theme={null}
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
async function deleteLocationGroup(groupCode: string) {
const api = new LocationGroupApi(configuration);
console.log(`Deleting location group '${groupCode}'...`);
try {
// Call delete endpoint — no body is returned
await api.deleteLocationGroup({ locationGroupCode: groupCode });
console.log(`Successfully deleted location group '${groupCode}'.`);
} catch (err: any) {
console.error("Error: Error deleting location group:", err);
if (err.apiError?.errorCode === "ITEM_NOT_FOUND") {
console.error(`No location group found with code '${groupCode}'.`);
}
}
}
// Example run
deleteLocationGroup("SGFG");
// Usage
// deleteLocationGroup("SGFG");
```
***
***
## Troubleshooting Your Location Group Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string;
errorCode: string; // e.g., "ITEM_NOT_FOUND"
correlationId: string;
}
}
```
**Common Error Codes for Location Groups:**
* `ITEM_NOT_FOUND`: You tried to get, update, or delete a location group using a `locationGroupCode` that does not exist.
* `ITEM_ALREADY_EXISTS`: You tried to `addLocationGroup` with a `locationGroupCode` that is already in use. Codes must be unique.
* `VALIDATION_ERROR`: The request body is invalid. The most common cause is including a `locationCode` in the `locationCodes` array that does not correspond to an existing Location in your Kibo tenant.
* `REQUIRED_FIELD_MISSING`: You tried to create a group without a `locationGroupCode` or `name`.
### Common Development Issues
**Issue 1:** My `updateLocationGroup` call is wiping out other settings.
* **Why it happens:** The `PUT` operation for updating a location group expects the *entire* `LocationGroup` object in the payload. If you send only the field you want to change (e.g., `{ "locationCodes": [...] }`), Kibo will interpret the missing fields (like `name`) as null and clear them.
* **How to fix it:** Always perform a `GET` on the location group first, modify the retrieved object in your code, and then `PUT` the complete, modified object back.
* **How to avoid it:** Follow the "Read-Modify-Write" pattern shown in Examples 2 and 4.
**Issue 2:** I created a group, but it's not being used for fulfillment.
* **Why it happens:** Creating a `LocationGroup` is just step one. You also need to configure Kibo's Order Management system to *use* that group in its fulfillment logic.
* **How to fix it:** In the Kibo Admin, navigate to **Main > Orders > Settings**. Here you can configure Order Routing and define which location groups should be used for sourcing inventory.
* **API Reference:** The APIs for managing fulfillment settings are separate from the `LocationGroupApi`. Look under the `Commerce/Settings` and `Commerce/Orders` API groups for more advanced configuration.
### Debugging Checklist
1. **Check the `locationGroupCode`:** Is it an exact string match, including case?
2. **Validate `locationCodes`:** Before creating or updating a group, are you sure every single `locationCode` in your array exists in the Kibo tenant?
3. **Verify API Client**: Are you using `LocationGroupApi` from the `@kibocommerce/rest-sdk/clients/Tenant` package?
4. **Check Permissions**: Do your API credentials have the necessary administrative permissions to manage tenant-level settings?
5. **Use the Read-Modify-Write Pattern:** For updates, are you fetching the object first to avoid accidental data loss?
# Order Routing API
Source: https://docs.kibocommerce.com/developer-guides/order-routing
Intelligent fulfillment routing and suggestion-based order distribution
# Kibo Order Routing API Developer Guide
Understand order routing architecture and concepts
Configure routing strategies in the Admin UI
Debug routing decisions using suggestion logs
## Understanding Order Routing in Kibo
In Kibo, **Order Routing** is the intelligent decision-making engine that determines the best possible way to fulfill an order. It's not just about finding a location with inventory; it's a sophisticated process that considers business rules, location capabilities, inventory levels, and even estimated delivery dates to produce an optimal fulfillment plan.
Think of it as a logistics expert in a box. You give it an order, and it gives you back a precise recommendation—a **Suggestion**—on which location(s) should ship which items. This is the core of Kibo's Distributed Order Management (DOM) system, enabling complex strategies like ship-from-store, splitting shipments to reduce distance, or prioritizing warehouses over retail locations. For a developer, understanding Order Routing means you're tapping into the "brain" of Kibo's fulfillment logic.
***
## How This Domain Fits Into Kibo
Order Routing is the bridge between an accepted **Order** and the physical **Fulfillment** process. It sits right in the middle of the post-purchase workflow.
* **Orders**: An order is created with a `Pending` status. This is the primary input for the Order Routing service.
* **Inventory & Locations**: The routing engine queries the **Inventory** domain to see which **Locations** and **Location Groups** have the required products in stock.
* **Fulfillment**: The output of the routing process—the **Suggestion**—is used to create one or more **Shipments**. A shipment is the instruction for a specific location to pick, pack, and ship a set of items.
* **Customer**: Advanced routing can use customer data, such as their shipping address, to calculate distances and estimated delivery dates, influencing the routing decision to improve the customer experience.
***
## Prerequisites
* Kibo API credentials and basic setup.
* An understanding of Kibo's **Locations**, **Location Groups**, and **Inventory** concepts. Order Routing relies heavily on these configurations.
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Order Routing Suggestions** and **Candidates** (based on official API specs).
* The key patterns Kibo uses for generating and auditing fulfillment plans (verified from apidocs.kibocommerce.com).
* Common workflows like requesting a routing suggestion, checking all possible candidates, and debugging the logic with suggestion logs (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official Order Routing API documentation effectively.
***
***
## Kibo Order Routing Fundamentals
### How Kibo Organizes Routing Data
Kibo's Order Routing service is built around a few key objects that represent the decision-making process:
* **`Suggestion`**: This is the primary output object. It represents Kibo's recommended fulfillment plan for an order. A Suggestion contains one or more proposed `Shipments`, each detailing which `locationCode` should fulfill which `items`.
* **`Candidate`**: A candidate represents a single, *possible* way to fulfill an item or group of items. The routing engine first generates a list of all candidates (e.g., "Warehouse A can ship this," "Store B can also ship this") and then uses business rules to select the best ones to build the final `Suggestion`.
* **`SuggestionLog`**: This is an audit trail. It provides a detailed, step-by-step explanation of *why* the routing engine made the decisions it did. It shows which rules were evaluated, which locations were considered, and which were rejected, making it invaluable for debugging.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials. This object is then passed to the constructor of the `OrderRoutingApi` client. The client automatically handles the OAuth 2.0 token exchange for every API call.
**Request/Response Structure:**
The routing APIs are action-oriented. You send a request with an order ID, and Kibo returns a complex object representing the plan.
```json theme={null}
// Actual response schema from the suggestRouting endpoint
{
"suggestionId": "e1f2b6e1-...",
"orderId": "065c71b12476b7000184b123",
"shipments": [
{
"locationCode": "WAREHOUSE-01",
"items": [
{
"lineId": 1,
"productCode": "SHIRT-BLUE-SM",
"quantity": 1
}
]
}
],
"warnings": []
}
```
**Error Handling Approach:**
If the routing engine cannot find any possible way to fulfill the order (e.g., no inventory anywhere), the API call won't necessarily fail with a 4xx error. Instead, it may return a `Suggestion` with an empty `shipments` array and a `warnings` message explaining the problem. You must check the response body for these business-level issues.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs under the "Fulfillment" section at:
`/developer-guides/order-routing`
***
### Common Order Routing Workflows
Kibo developers typically work with Order Routing in these scenarios:
1. **Automated Fulfillment**: A backend process listens for new orders, immediately calls the `suggestRouting` API, and automatically creates the recommended shipments.
2. **Manual Review**: A custom application for a warehouse manager fetches all possible `Candidates` for a complex order, allowing the manager to manually choose the best fulfillment plan.
3. **Debugging and Auditing**: A developer uses the `getSuggestionLog` API to understand why a specific order was routed to an unexpected location.
Let's explore each pattern step by step.
***
***
## Suggesting a Route: The Kibo Way
### When You Need This
This is the most common and essential operation in the Order Routing domain. You use it when you have a new, unfulfilled order and you need Kibo to tell you the single best way to fulfill it based on your configured rules.
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/fulfillment/orderrouting/suggestions`
* **Method:** `POST`
* **SDK Method:** `suggestRouting`
* **API Docs:** Suggest Routing
### Understanding the Kibo Approach
Kibo's `suggestRouting` endpoint is designed to be the "easy button" for fulfillment. Instead of requiring you to manually check inventory at every location, it encapsulates all that complex logic. You provide an `orderId`, and the API does the heavy lifting: it finds all possible fulfillment options (candidates), evaluates them against your business rules (e.g., "lowest cost," "fewest shipments"), and returns a single, actionable `Suggestion`.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Order Routing resource.
// 3. **Data Preparation**: Construct the 'SuggestionRequest' object, which primarily contains the order ID.
// 4. **API Call**: Use the 'OrderRoutingApi' client to call the 'suggestRouting' method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Order Routing operations.
// The SDK client for this is found under the 'Fulfillment' group.
import { Configuration } from "@kibocommerce/rest-sdk";
import { OrderRoutingApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
import { SuggestionRequest } from "@kibocommerce/rest-sdk/models/Fulfillment";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function gets the optimal fulfillment plan for a given order ID.
async function getFulfillmentSuggestion(orderId: string) {
// 1. Instantiate a dedicated client for the Order Routing API.
const orderRoutingApi = new OrderRoutingApi(configuration);
// 2. Prepare the request body.
// The schema requires a 'SuggestionRequest' object.
const payload: SuggestionRequest = {
orderId: orderId,
// You can optionally specify which line items to route,
// but by default, it will route all unfulfilled items.
};
console.log(`Attempting to get routing suggestion for Order ID: ${orderId}`);
// 3. Call the 'suggestRouting' method.
try {
const suggestion = await orderRoutingApi.suggestRouting({
suggestionRequest: payload,
});
if (suggestion.shipments && suggestion.shipments.length > 0) {
console.log("Success: Success! Optimal route found:");
suggestion.shipments.forEach((shipment, index) => {
console.log(` - Shipment ${index + 1}: Fulfill from Location '${shipment.locationCode}'`);
shipment.items?.forEach(item => {
console.log(` - Item: ${item.productCode}, Quantity: ${item.quantity}`);
});
});
} else {
console.warn("Warning: Could not find a valid route. The order may be unfulfillable.");
suggestion.warnings?.forEach(warning => console.warn(` - Warning: ${warning.message}`));
}
return suggestion;
} catch (error: any) {
console.error("Error: API Error:", JSON.stringify(error, null, 2));
}
}
// Usage with a real, pending Order ID from your Kibo tenant
// getFulfillmentSuggestion("065c71b12476b7000184b123");
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the standard `Configuration` object.
* The **API call** was made using an instance of `OrderRoutingApi`. This is the specialized client for all routing-related actions.
* The **payload** was a simple `SuggestionRequest` object containing the `orderId`. This is all Kibo needs to look up the order and its items.
* The **response handling** is important. We first check if the `shipments` array has content. If it's empty, it signifies a business-level problem (like no stock), which we log as a warning. If it succeeds, we parse and display the recommended fulfillment plan.
### Common Beginner Mistakes
**Mistake 1:** Assuming a failed route throws a 4xx/5xx error.
An unfulfillable order is not an API error. The API call will succeed (HTTP 200 OK), but the returned `Suggestion` object will have an empty `shipments` array. Your code **must** check for this condition.
**Mistake 2:** Treating the `Suggestion` as the final fulfillment.
The `suggestRouting` endpoint only *recommends* a plan. It does not create shipments or deduct inventory. You must take the data from the `Suggestion` object and use it to make subsequent API calls to the **Shipment API** to actually create the fulfillment shipments.
***
***
## Multiple Real-World Examples
Here are 5 complete, production-ready examples for common `Order Routing` operations.
### Example 1: Suggest All Possible Candidates
Instead of the single best route, this gets you *every possible location* that could fulfill the order. This is great for UIs where a user makes the final decision.
* **API Docs:** Suggest Candidates
```ts theme={null}
// ... imports and configuration setup ...
import { OrderRoutingApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
async function getFulfillmentCandidates(orderId: string) {
const orderRoutingApi = new OrderRoutingApi(configuration);
console.log(`Fetching all fulfillment candidates for Order ID: ${orderId}`);
try {
// The payload is the same SuggestionRequest as suggestRouting
const candidatesResponse = await orderRoutingApi.suggestCandidates({
suggestionRequest: { orderId: orderId }
});
console.log(`Success: Found ${candidatesResponse.candidates?.length} candidates.`);
candidatesResponse.candidates?.forEach(candidate => {
console.log(`
- Location '${candidate.locationCode}' can fulfill:
${candidate.items?.map(i => ` - ${i.quantity}x ${i.productCode}`).join('\n')}
`);
});
return candidatesResponse;
} catch (error: any) {
console.error("Error: API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// getFulfillmentCandidates("065c71b12476b7000184b123");
```
### Example 2: Get the Suggestion Log for Debugging
This retrieves the detailed audit trail for a routing decision, explaining exactly why Kibo chose a specific location.
* **API Docs:** Get Suggestion Log
```ts theme={null}
// ... imports and configuration setup ...
import { OrderRoutingApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
async function getRoutingDebugLog(suggestionId: string) {
const orderRoutingApi = new OrderRoutingApi(configuration);
console.log(`Fetching suggestion log for Suggestion ID: ${suggestionId}`);
try {
// Note: This endpoint requires the suggestionId, not the orderId.
const logs = await orderRoutingApi.getSuggestionLog({ suggestionId: suggestionId });
console.log("Success: Success! Log retrieved.");
logs.forEach(log => {
console.log(`[${log.logLevel}] ${log.message}`);
});
return logs;
} catch (error: any) {
console.error("Error: API Error:", JSON.stringify(error, null, 2));
}
}
// First, get a suggestion to have a suggestionId
async function debugRouting(orderId: string) {
const suggestion = await getFulfillmentSuggestion(orderId);
if (suggestion?.suggestionId) {
await getRoutingDebugLog(suggestion.suggestionId);
}
}
// Usage
// debugRouting("065c71b12476b7000184b123");
```
### Example 3: Suggest Routing with Estimated Delivery Dates (EDD)
A more advanced version of routing that factors in shipping times to find the best route that meets a customer's expectations.
```ts theme={null}
// ... imports and configuration setup ...
import { OrderRoutingApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
import { SuggestionRequest } from "@kibocommerce/rest-sdk/models/Fulfillment";
async function getFastestFulfillmentSuggestion(orderId: string) {
const orderRoutingApi = new OrderRoutingApi(configuration);
const payload: SuggestionRequest = { orderId: orderId };
console.log(`Getting EDD-aware routing suggestion for Order ID: ${orderId}`);
try {
// This endpoint has the same request shape but uses different underlying logic.
const suggestion = await orderRoutingApi.suggestRoutingWithEDD({
suggestionRequest: payload
});
// The response shape is the same as the standard suggestRouting
if (suggestion.shipments && suggestion.shipments.length > 0) {
console.log("Success: Success! EDD-optimized route found:", suggestion.shipments);
} else {
console.warn("Warning: Could not find a valid EDD-aware route.");
}
return suggestion;
} catch (error: any) {
console.error("Error: API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// getFastestFulfillmentSuggestion("065c71b12476b7000184b123");
```
### Example 4: Full Workflow - Route and Create Shipments
This advanced example shows the full, practical workflow: get a suggestion, then immediately act on it by creating the necessary shipments.
```ts theme={null}
// ... imports and configuration setup ...
// We need both OrderRoutingApi and ShipmentApi for this!
import { OrderRoutingApi, ShipmentApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
import { Shipment } from "@kibocommerce/rest-sdk/models/Fulfillment";
async function routeAndFulfillOrder(orderId: string) {
const orderRoutingApi = new OrderRoutingApi(configuration);
const shipmentApi = new ShipmentApi(configuration);
// Step 1: Get the routing suggestion
const suggestion = await orderRoutingApi.suggestRouting({
suggestionRequest: { orderId: orderId }
});
if (!suggestion || !suggestion.shipments || suggestion.shipments.length === 0) {
console.error("Routing failed or produced no shipments. Halting fulfillment.");
return;
}
console.log("Suggestion received. Creating shipments...");
// Step 2: Loop through the suggested shipments and create each one.
for (const suggestedShipment of suggestion.shipments) {
try {
const shipmentPayload: Shipment = {
orderId: orderId,
locationCode: suggestedShipment.locationCode,
items: suggestedShip-ment.items,
// You would set other properties like shippingMethodCode here
};
const newShipment = await shipmentApi.createShipment({ shipment: shipmentPayload });
console.log(`Created Shipment ${newShipment.shipmentNumber} for Location ${newShipment.locationCode}`);
} catch(error: any) {
console.error(`Failed to create shipment for location ${suggestedShipment.locationCode}:`, error);
}
}
}
// Usage
// routeAndFulfillOrder("065c71b12476b7000184b123");
```
***
***
## Troubleshooting Your Order Routing Implementation
### Reading Kibo Error Messages
While business logic failures appear in the response body, direct API errors follow the standard Kibo pattern.
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string;
errorCode: string; // e.g., "ITEM_NOT_FOUND"
correlationId: string;
}
}
```
**Common Error Codes for Order Routing:**
* `ITEM_NOT_FOUND`: You passed an `orderId` or `suggestionId` that does not exist.
* `VALIDATION_ERROR`: The request body is malformed. This is rare for simple suggestion requests but can happen if you provide invalid line item numbers.
* `UNAUTHORIZED`: Your API credentials do not have permission to access the fulfillment and routing APIs.
### Common Development Issues
**Issue 1:** The API always routes to the same location, even when other locations have stock.
* **Why it happens:** This is almost always a configuration issue, not an API issue. The Order Routing engine is only as smart as the rules you give it. You might have a rule that gives one location group (e.g., "Warehouses") a much higher priority than another (e.g., "Retail Stores").
* **How to fix it:** In the Kibo Admin, go to **Main > Orders > Settings > Order Routing** and carefully inspect your routing rules and location group rankings. Use the `getSuggestionLog` API call to see exactly which rules are being applied and why other locations are being passed over.
* **How to avoid it:** Before writing code, understand the routing configuration in the Kibo Admin. The API is a tool to *execute* the configuration, not to define it.
**Issue 2:** The `suggestRouting` call is slow.
* **Why it happens:** Order routing can be a complex calculation, especially for orders with many items and a large number of potential fulfillment locations. The engine has to check inventory and evaluate rules for many different combinations.
* **How to fix it:** Ensure your Location Groups are well-defined and not unnecessarily large. If you have 500 stores, consider creating smaller, regional groups to limit the number of locations the engine has to evaluate for any given order.
* **API Reference:** There are no API parameters to directly control performance, but a well-structured Location and Location Group hierarchy is the key to efficient routing.
### Debugging Checklist
1. **Check the Order Status:** Is the order you're trying to route in a `Pending` state and does it have unfulfilled items? You cannot route an already fulfilled or canceled order.
2. **Verify Inventory:** Manually check the inventory of the order's items. Does any location actually have stock?
3. **Inspect Routing Rules:** Go to the Kibo Admin and review the configured routing rules. Are they logical? Are your locations assigned to the correct location groups?
4. **Use the Suggestion Log:** If a routing decision is unexpected, the `getSuggestionLog` endpoint is your best friend. It will tell you *exactly* what the engine was thinking.
5. **Check the Response Body:** Is your code checking for an empty `shipments` array and the `warnings` collection? Don't just assume a 200 OK means a valid plan was found.
# Pricing API
Source: https://docs.kibocommerce.com/developer-guides/pricing
Price lists, pricing strategies, and B2B/B2C pricing management
# Kibo Pricing API Developer Guide
Understand pricing architecture and concepts
Organize discounts using folders in the Admin UI
## Understanding Pricing in Kibo
In Kibo, pricing is a powerful, standalone concept that is **decoupled from the core product**. Unlike platforms where a product has a single, fixed price attribute, a Kibo product has no inherent price. Instead, prices are defined in **Price Lists**, and products are assigned prices within those lists.
This architecture is incredibly flexible. It allows you to create an unlimited number of price lists for different contexts without ever duplicating a product. You can have separate price lists for:
* Different currencies (USD Price List, EUR Price List)
* B2B customers with negotiated contract rates (Contract A Price List)
* VIP customer segments (Gold Member Price List)
* Time-bound sales and promotions (Black Friday Sale Price List)
The Kibo platform automatically "resolves" the correct price for a shopper based on their context (which site they're on, their customer account, etc.), making it seamless to manage complex pricing strategies.
***
## How This Domain Fits Into Kibo
The Pricing domain is a foundational service that is consulted throughout the entire customer journey.
* **Catalog**: When a product is displayed on a category or search results page, Kibo's platform determines the correct price list for the shopper and shows the appropriate price.
* **Cart & Checkout**: As items are added to the cart, the Pricing engine calculates the subtotal. This same engine is what applies discounts from the Promotion domain.
* **Customer**: Customer accounts or B2B accounts can be "entitled" to specific price lists, giving them access to exclusive or negotiated pricing.
* **Orders**: The final, resolved prices for each item are captured and stored on the order record at the time of purchase.
***
## Prerequisites
* Kibo API credentials with Catalog Administration permissions.
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Price List** and **Price List Entry** data (based on official API specs).
* The key patterns Kibo uses for all pricing CRUD operations (verified from apidocs.kibocommerce.com).
* Common workflows like creating sale lists and bulk-updating prices (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official API documentation for pricing.
***
***
## Kibo Pricing Fundamentals
### How Kibo Organizes Pricing Data
Kibo's Pricing data model is built on a simple but powerful hierarchy:
* **`PriceList`**: This is the container object for a set of prices. It acts as a named bucket. Key properties include:
* `priceListCode`: A unique, user-defined string identifier (e.g., `USD-RETAIL` or `VIP-PRICING`). You'll use this code in almost every API call.
* `name`: A human-readable name for the list (e.g., "USD Retail Prices").
* `enabled`: A boolean to activate or deactivate the entire price list.
* **`PriceListEntry`**: This is the actual price for a single product within a price list. A `PriceList` can contain thousands of these entries. Key properties include:
* `productCode`: The product this price applies to.
* `currencyCode`: The currency of the price (e.g., "USD").
* `price`: The final price a customer pays. If a `salePrice` is active, this is ignored.
* `salePrice`: An optional, lower price that takes precedence over the `price`.
* `startDate` / `endDate`: Optional ISO 8601 date-time strings that define when the price entry is active. This is perfect for scheduling sales.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials. This object is then passed to the constructor of the `PriceListsApi` client. The client will automatically handle the OAuth 2.0 token exchange for every API call.
**Request/Response Structure:**
Many pricing operations are designed for bulk updates. When adding or updating price list entries, you send an array of entry objects in the request body. The API will process them as a batch.
```json theme={null}
// Actual request schema for adding Price List Entries
// POST /api/commerce/catalog/admin/pricelists/{priceListCode}/entries
[
{
"productCode": "SHIRT-BLUE-SM",
"currencyCode": "USD",
"price": 24.99,
"msrp": 30.00
},
{
"productCode": "PANTS-BLK-32",
"currencyCode": "USD",
"price": 55.00
}
]
```
**Error Handling Approach:**
If an API call fails, the SDK throws a structured error. For pricing, a common error is `ITEM_ALREADY_EXISTS` when trying to create a `PriceList` with a `priceListCode` that's already in use.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs under the "Catalog Administration" section at:
[`/api-reference/pricelists/get-price-lists`](/api-reference/pricelists/get-price-lists)
***
### Common Pricing Workflows
Kibo developers typically work with Pricing in these scenarios:
1. **System Integration**: Syncing prices from an external ERP or PIM system into Kibo by creating and updating price lists.
2. **Promotional Pricing**: Creating a new, temporary price list for a holiday sale and scheduling it to activate and deactivate automatically.
3. **B2B/Contract Pricing**: Managing dedicated price lists for specific B2B accounts with negotiated rates.
Let's explore each pattern step by step.
***
***
## Creating a Price List: The Kibo Way
### When You Need This
This is the first step for any new pricing strategy. You need a container to hold your prices, whether it's for a new currency, a new customer segment, or a temporary sale. This operation creates that empty container.
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/catalog/admin/pricelists`
* **Method:** `POST`
* **SDK Method:** `addPriceList`
* **API Docs:** [Add Price List](/api-reference/pricelists/add-price-list)
### Understanding the Kibo Approach
Kibo separates the creation of the price list (the container) from the act of adding prices to it. This allows you to set up the structure and metadata of your price list first. The `priceListCode` you define here becomes the unique key for all future operations, like adding or updating the prices within it.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Price List resource.
// 3. **Data Preparation**: Construct the 'PriceList' request body object according to the API schema.
// 4. **API Call**: Use the 'PriceListsApi' client to call the 'addPriceList' method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Pricing operations.
// The SDK client for this is found under the 'CatalogAdministration' group.
import { Configuration } from "@kibocommerce/rest-sdk";
import { PriceListsApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
import { CatalogAdminsPriceList } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
// Configuration setup - this single object is reused for all API clients.
// Pricing management requires administrative permissions.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function creates a new, empty price list for a fall sale.
async function createNewPriceList() {
// 1. Instantiate a dedicated client for the Price Lists API.
const priceListsApi = new PriceListsApi(configuration);
// 2. Prepare the request body.
// This object must match the 'CatalogAdminsPriceList' schema.
const payload: CatalogAdminsPriceList = {
priceListCode: "FALL_SALE_2025",
name: "Fall Sale 2025",
enabled: true,
resolvable: true, // 'resolvable' means the platform can automatically select this list for shoppers.
// 'validSites' can be used to limit this list to specific sites in a multi-site environment.
};
console.log(`Attempting to create price list: ${payload.name}`);
// 3. Call the 'addPriceList' method on the client.
try {
const newPriceList = await priceListsApi.addPriceList({
catalogAdminsPriceList: payload
});
console.log("Success: New price list created:", JSON.stringify(newPriceList, null, 2));
return newPriceList;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
if (error.body?.errorCode === 'ITEM_ALREADY_EXISTS') {
console.error(`Error: A price list with code '${payload.priceListCode}' already exists.`);
}
}
}
createNewPriceList();
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the `Configuration` object, which is standard for all SDK interactions.
* The **API call** used an instance of `PriceListsApi` to interact with the pricing endpoints.
* The **payload** was a `PriceList` object. We defined our own unique `priceListCode` which acts as its permanent ID. We also set `resolvable` to true, which is important for allowing the storefront to use this price list.
* The **response handling** uses a `try...catch` block. On success, Kibo returns the full price list object we just created. On failure, we specifically check for the `ITEM_ALREADY_EXISTS` error to give a more user-friendly message.
### Common Beginner Mistakes
**Mistake 1:** Trying to add prices at the same time as creating the list.
The `addPriceList` endpoint only creates the container. You cannot include an array of `PriceListEntry` objects in its payload. Adding prices is a separate, subsequent API call.
**Mistake 2:** Not setting `resolvable` to true.
If a price list is not `resolvable`, the Kibo platform won't consider it when determining which price to show a shopper on the storefront. It can still be accessed directly via the API, but it won't be used automatically. For most B2C use cases, you want this to be true.
***
***
## Multiple Real-World Examples
Here are 5 complete, production-ready examples for common `Price List` CRUD operations.
### Example 1: Bulk Add Prices to a Price List
After creating a price list, you need to populate it. This is the most common "write" operation.
* **API Docs:** [Add Price List Entry](/api-reference/pricelistentries/add-price-list-entry)
```ts theme={null}
// ... imports and configuration setup ...
import { PriceListsApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
import { PriceListEntry } from "@kibocommerce/rest-sdk/models/CatalogAdministration";
async function addPricesToSaleList(priceListCode: string) {
const priceListsApi = new PriceListsApi(configuration);
// The payload is an array of PriceListEntry objects.
const priceEntries: PriceListEntry[] = [
{
productCode: "SHIRT-BLUE-SM",
currencyCode: "USD",
price: 19.99, // The sale price
},
{
productCode: "PANTS-BLK-32",
currencyCode: "USD",
price: 45.00,
},
];
console.log(`Adding ${priceEntries.length} prices to list '${priceListCode}'...`);
try {
// NOTE: This is a bulk operation. It has no return body on success (204 No Content).
await priceListsApi.addPriceListEntries({
priceListCode: priceListCode,
priceListEntry: priceEntries,
// You can set 'throwErrorOnInvalidEntries' to true to make the whole batch fail if one entry is bad.
});
console.log("Success: Prices added to the list.");
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// addPricesToSaleList("FALL_SALE_2025");
```
### Example 2: Get Price List Entries with Pagination
This shows how to read the prices contained within a list.
* **API Docs:** [Get Price List Entries](/api-reference/pricelistentries/get-price-list-entries)
```ts theme={null}
// ... imports and configuration setup ...
import { PriceListsApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
async function getPricesFromList(priceListCode: string) {
const priceListsApi = new PriceListsApi(configuration);
console.log(`Fetching prices from list '${priceListCode}'...`);
try {
const entriesCollection = await priceListsApi.getPriceListEntries({
priceListCode: priceListCode,
pageSize: 5, // Fetching in pages of 5
startIndex: 0
});
console.log(`Success: Found ${entriesCollection.totalCount} total entries.`);
entriesCollection.items?.forEach(entry => {
console.log(` - ${entry.productCode}: ${entry.price} ${entry.currencyCode}`);
});
return entriesCollection;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// getPricesFromList("FALL_SALE_2025");
```
### Example 3: Bulk Update Existing Prices
Use this to change prices that are already in a price list.
* **API Docs:** [Update Price List Entry](/api-reference/pricelistentries/update-price-list-entry-by-currency)
```ts theme={null}
// ... imports and configuration setup ...
import { PriceListsApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
import { PriceListEntry } from "@kibocommerce/rest-sdk/models/CatalogAdministration";
async function updatePricesInSaleList(priceListCode: string) {
const priceListsApi = new PriceListsApi(configuration);
const updatedPriceEntries: PriceListEntry[] = [
{
productCode: "SHIRT-BLUE-SM",
currencyCode: "USD",
price: 18.99, // Further reduction!
}
];
console.log(`Updating ${updatedPriceEntries.length} prices in list '${priceListCode}'...`);
try {
await priceListsApi.updatePriceListEntries({
priceListCode: priceListCode,
priceListEntry: updatedPriceEntries
});
console.log("Success: Prices updated.");
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// updatePricesInSaleList("FALL_SALE_2025");
```
### Example 4: Schedule a Future Sale Price
This example shows how to use `startDate` and `endDate` to create a price that only becomes active during a specific window.
```ts theme={null}
// ... imports and configuration setup ...
import { PriceListsApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
import { PriceListEntry } from "@kibocommerce/rest-sdk/models/CatalogAdministration";
async function scheduleHolidayPrice(priceListCode: string) {
const priceListsApi = new PriceListsApi(configuration);
const futureSalePrice: PriceListEntry[] = [{
productCode: "PANTS-BLK-32",
currencyCode: "USD",
price: 39.99,
// Dates must be in ISO 8601 format
startDate: "2025-11-28T00:00:00-06:00", // Start of Black Friday (US Central Time)
endDate: "2025-12-01T23:59:59-06:00", // End of Cyber Monday
}];
console.log(`Scheduling future price in list '${priceListCode}'...`);
try {
// We use the 'update' method as it performs an "upsert" for entries.
await priceListsApi.updatePriceListEntries({
priceListCode: priceListCode,
priceListEntry: futureSalePrice
});
console.log("Success: Future sale price has been scheduled.");
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// scheduleHolidayPrice("FALL_SALE_2025");
```
### Example 5: Clean Up - Delete Prices and the Price List
This demonstrates the full lifecycle: removing specific prices from a list and then deleting the list itself.
* **API Docs (Delete Entries):** [Delete Price List Entry](/api-reference/pricelistentries/delete-price-list-entry-by-currency)
* **API Docs (Delete List):** [Delete Price List](/api-reference/pricelists/delete-price-list)
```ts theme={null}
// ... imports and configuration setup ...
import { PriceListsApi } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
async function cleanupPriceList(priceListCode: string) {
const priceListsApi = new PriceListsApi(configuration);
// Step 1: Delete specific entries from the list.
// The payload is an array of product codes to delete.
const productsToDelete = ["SHIRT-BLUE-SM", "PANTS-BLK-32"];
console.log(`Deleting ${productsToDelete.length} entries from list '${priceListCode}'...`);
try {
await priceListsApi.deletePriceListEntries({
priceListCode: priceListCode,
productCode: productsToDelete
// Note: The SDK parameter is 'productCode' but it accepts an array.
});
console.log("Entries deleted.");
} catch (error: any) {
console.error("Error deleting entries:", JSON.stringify(error, null, 2));
// We might want to stop if this fails
return;
}
// Step 2: Delete the now-empty price list container.
console.log(`Deleting price list '${priceListCode}'...`);
try {
await priceListsApi.deletePriceList({ priceListCode: priceListCode });
console.log("Price list deleted successfully.");
} catch (error: any) {
console.error("Error deleting price list:", JSON.stringify(error, null, 2));
}
}
// Usage
// cleanupPriceList("FALL_SALE_2025");
```
***
***
## Troubleshooting Your Pricing Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string;
errorCode: string; // e.g., "ITEM_ALREADY_EXISTS"
correlationId: string;
items?: Array<{ // Present for bulk validation errors
name: string;
errorCode: string;
message: string;
}>
}
}
```
**Common Error Codes for Pricing:**
* `ITEM_ALREADY_EXISTS`: You tried to `addPriceList` with a `priceListCode` that is already in use.
* `ITEM_NOT_FOUND`: You tried to operate on a `priceListCode` that does not exist.
* `VALIDATION_ERROR`: The request body is malformed. When performing bulk entry updates, the `items` array in the error response will tell you which product code or price was invalid.
### Common Development Issues
**Issue 1:** My price updates aren't appearing on the storefront immediately.
* **Why it happens:** Kibo's platform has several layers of caching to ensure high performance. Price list information is cached, so changes made via the API might not be reflected for a few minutes until the cache expires.
* **How to fix it:** For immediate testing, you can often trigger a cache clear in the Kibo Admin under **System > Caching**. For automated processes, you can either wait for the cache TTL (Time To Live) to expire naturally or, for advanced use cases, include a special `X-Vol-Cache-Flush: true` header in your API call to request a cache invalidation.
* **How to avoid it:** Be aware that caching is a feature. For most bulk updates that run overnight, this is not an issue. Factor in a potential delay of a few minutes for changes to propagate.
**Issue 2:** My bulk update of 1,000 prices is failing, but I don't know which one is wrong.
* **Why it happens:** A single invalid `productCode` or a malformed price in a large batch will cause the entire API call to fail (if `throwErrorOnInvalidEntries` is true).
* **How to fix it:** Inspect the `items` array within the error response body. Kibo will often report which specific entry in your payload caused the validation failure. Also, consider sending your updates in smaller chunks (e.g., 100-200 entries per call) to make it easier to isolate a bad record.
* **API Reference:** Review the schema for `PriceListEntry` carefully to ensure all your data types are correct (e.g., `price` is a number, not a string).
# Redaction Services
Source: https://docs.kibocommerce.com/developer-guides/redaction-services
Handle data subject erasure and right-to-deletion requests under GDPR, CCPA, DPDP, LGPD, LFPDPPP, and other privacy regulations using Kibo's two-phase redaction workflow
## Overview
Kibo's Redaction Services provide a **two-phase workflow** for processing data subject erasure requests as required by privacy regulations such as:
* **GDPR** (General Data Protection Regulation — EU/EEA)
* **CCPA / CPRA** (California Consumer Privacy Act / California Privacy Rights Act — US)
* **LGPD** (Lei Geral de Proteção de Dados — Brazil)
* **DPDP** (Digital Personal Data Protection Act — India)
* **PIPL** (Personal Information Protection Law — China)
* **PDPA** (Personal Data Protection Act — Thailand, Singapore, and others)
* **LFPDPPP** (Ley Federal de Protección de Datos Personales en Posesión de los Particulares — Mexico)
Regardless of the specific regulation, the workflow is the same: identify the data subject's PII, review the scope, and irreversibly remove it. The two phases are:
1. **Create a draft report** — Kibo scans the tenant's data for all PII associated with the subject and returns a report listing every affected record. No data is modified at this stage.
2. **Execute the redaction** — After reviewing the draft, you trigger the irreversible redaction that overwrites or removes the identified PII.
This separation exists to provide an auditable review step before any destructive action is taken. Your compliance team can inspect exactly what will be redacted before committing.
***
## How This Domain Fits Into Kibo
A single data subject's PII can exist across many parts of the Kibo platform. The redaction engine covers:
| Entity type | What is redacted |
| ---------------- | -------------------------------------------------------------- |
| Orders | Billing/shipping addresses, contact details, custom attributes |
| Payments | Payment method identifiers attached to orders |
| Checkouts | In-progress or abandoned checkout PII |
| Returns | Return contact and address details |
| Wishlists | Wishlist owner identity |
| Shipments | Recipient contact and address details |
| Customer account | The account record itself (identified by `customerAccountId`) |
The two-phase design lets you audit the scope of a deletion request before executing it — important both for regulatory compliance and for avoiding accidental data loss.
***
## Prerequisites
* Kibo API credentials (client ID and shared secret) with access to the `platform/data` namespace
* The `customerAccountId` (integer) or `userId` (string) of the data subject whose data must be erased
* An understanding of any custom attribute FQNs attached to orders, customers, returns, or shipments for your tenant, if you need those included in the redaction
***
## The Two-Phase Workflow
### Phase 1 — Create a Redaction Report (Draft)
**Endpoint:** `POST /platform/data/redaction/report` — [API reference](/api-reference/redaction/generate-redaction-report)
This call scans the tenant's data and returns a draft report. **No data is modified.**
#### Request body
```json theme={null}
{
"customerAccountId": 4820193,
"userId": null,
"attributeFqns": {
"order": ["tenant~gdpr-consent-date"],
"customer": ["tenant~marketing-opt-in"],
"return": null,
"shipment": null
},
"clearDataNodes": {
"orders": false,
"checkouts": true,
"shipments": false
}
}
```
**Field descriptions:**
| Field | Type | Description |
| -------------------------- | --------- | --------------------------------------------------------------------------------------- |
| `customerAccountId` | integer | The Kibo customer account ID of the data subject. Required if `userId` is not provided. |
| `userId` | string | The user ID of the data subject. Required if `customerAccountId` is not provided. |
| `attributeFqns.order` | string\[] | Fully-qualified names of custom order attributes to include in the redaction scope. |
| `attributeFqns.customer` | string\[] | Fully-qualified names of custom customer attributes to include. |
| `attributeFqns.return` | string\[] | Fully-qualified names of custom return attributes to include. |
| `attributeFqns.shipment` | string\[] | Fully-qualified names of custom shipment attributes to include. |
| `clearDataNodes.orders` | boolean | If `true`, wipes the entire order data node rather than field-level PII only. |
| `clearDataNodes.checkouts` | boolean | If `true`, wipes the entire checkout data node. |
| `clearDataNodes.shipments` | boolean | If `true`, wipes the entire shipment data node. |
#### Example response
```json theme={null}
{
"reportId": "a3f9c2d1-4e7b-4f8a-b2c3-9d0e1f2a3b4c",
"schemaVersion": 1,
"tenantId": 1000000,
"status": "Draft",
"subject": {
"customerAccountId": 4820193,
"userId": null,
"resolvedEmailAddresses": ["jane.doe@example.com"]
},
"auditInfo": {
"createBy": "840065bee668435b9d5346e60e6b1f88",
"createDate": "2026-03-19T14:00:00Z",
"updateBy": null,
"updateDate": null
},
"request": {
"correlationId": "corr-7f3a9b21",
"attributeFqns": {
"order": ["tenant~gdpr-consent-date"],
"customer": ["tenant~marketing-opt-in"],
"return": null,
"shipment": null
},
"clearDataNodes": {
"orders": false,
"checkouts": true,
"shipments": false
}
},
"createdAt": "2026-03-19T14:00:00Z",
"executionStartedAt": null,
"executionCompletedAt": null,
"affectedEntities": {
"customerAccountId": 4820193,
"orders": { "count": 3, "ids": ["1ab0edd566b26c0001ce7f1f000186e3", "2bc1fee677c37d1102df8g2g111297f4", "3cd2gff788d48e2213eg9h3h222308g5"] },
"payments": { "count": 2, "ids": ["af6f5fd885de41c589f4b363012f78ef", "be7g6ge996ef52d69ag5c474123g89fg"] },
"checkouts": { "count": 2, "ids": ["1ab0edd566b26c0001ce7f1f000186e3", "2bc1fee677c37d1102df8g2g111297f4"] },
"returns": { "count": 1, "ids": ["3cd2gff788d48e2213eg9h3h222308g5"] },
"wishlists": { "count": 1, "ids": ["4de3hgg899e59f3324fh0i4i333419h6"] },
"shipments": { "count": 3, "ids": ["802", "803", "804"] }
},
"operationLog": null,
"errorSummary": null
}
```
The key field to note is `status: "Draft"`. The report has been created and the affected entities have been identified, but nothing has been changed yet.
***
### Phase 2 — Review the Draft Report
**Endpoint:** `GET /platform/data/redaction/report/{reportId}` — [API reference](/api-reference/redaction/get-redaction-report)
Retrieve the draft report and verify the scope before committing to the redaction.
```
GET /platform/data/redaction/report/a3f9c2d1-4e7b-4f8a-b2c3-9d0e1f2a3b4c
```
Review the `affectedEntities` object carefully:
* `orders.count` / `orders.ids` — the orders that will have PII removed
* `payments.count` / `payments.ids` — payment records linked to those orders
* `checkouts.count` / `checkouts.ids` — any checkout records found
* `returns.count` / `returns.ids` — return records
* `wishlists.count` / `wishlists.ids` — wishlist records
* `shipments.count` / `shipments.ids` — shipment records
* `customerAccountId` — the resolved account ID of the subject
Confirm that `status` is `"Draft"` before proceeding to execution. A report with `status: "Executed"` cannot be executed again.
***
### Phase 3 — Execute the Redaction
**Endpoint:** `POST /platform/data/redaction/execute/{reportId}` — [API reference](/api-reference/redaction/execute-redaction)
Execution is **irreversible**. Once you call this endpoint the identified PII is permanently removed or overwritten. There is no undo. Ensure the draft report has been reviewed and approved before proceeding.
```
POST /platform/data/redaction/execute/a3f9c2d1-4e7b-4f8a-b2c3-9d0e1f2a3b4c
```
This endpoint has no request body. The `reportId` in the path identifies which draft to execute.
#### Example response
```json theme={null}
{
"reportId": "a3f9c2d1-4e7b-4f8a-b2c3-9d0e1f2a3b4c",
"schemaVersion": 1,
"tenantId": 1000000,
"status": "Executed",
"subject": {
"customerAccountId": 4820193,
"userId": null,
"resolvedEmailAddresses": ["jane.doe@example.com"]
},
"createdAt": "2026-03-19T14:00:00Z",
"executionStartedAt": "2026-03-19T14:05:00Z",
"executionCompletedAt": "2026-03-19T14:05:03Z",
"affectedEntities": {
"customerAccountId": 4820193,
"orders": { "count": 3, "ids": ["1ab0edd566b26c0001ce7f1f000186e3", "2bc1fee677c37d1102df8g2g111297f4", "3cd2gff788d48e2213eg9h3h222308g5"] },
"payments": { "count": 2, "ids": ["af6f5fd885de41c589f4b363012f78ef", "be7g6ge996ef52d69ag5c474123g89fg"] },
"checkouts": { "count": 2, "ids": ["1ab0edd566b26c0001ce7f1f000186e3", "2bc1fee677c37d1102df8g2g111297f4"] },
"returns": { "count": 1, "ids": ["3cd2gff788d48e2213eg9h3h222308g5"] },
"wishlists": { "count": 1, "ids": ["4de3hgg899e59f3324fh0i4i333419h6"] },
"shipments": { "count": 3, "ids": ["802", "803", "804"] }
},
"operationLog": [
{
"timestamp": "2026-03-19T14:05:00Z",
"phase": "Execution",
"store": "main",
"entityType": "Order",
"entityId": "1ab0edd566b26c0001ce7f1f000186e3",
"operation": "RedactPii",
"status": "Success",
"recordsAffected": 1,
"durationMs": 42,
"errorMessage": null
},
{
"timestamp": "2026-03-19T14:05:01Z",
"phase": "Execution",
"store": "main",
"entityType": "CustomerAccount",
"entityId": "4820193",
"operation": "RedactPii",
"status": "Success",
"recordsAffected": 1,
"durationMs": 38,
"errorMessage": null
}
],
"errorSummary": null
}
```
After execution, `status` changes to `"Executed"`, `executionCompletedAt` is populated, and `operationLog` contains one entry per operation performed.
#### Reading the operation log
| Field | Description |
| ----------------- | ------------------------------------------------------------------ |
| `timestamp` | When this individual operation ran |
| `phase` | Processing phase (e.g., `"Execution"`) |
| `store` | The data store or context within the tenant |
| `entityType` | The type of record affected (e.g., `"Order"`, `"CustomerAccount"`) |
| `entityId` | The ID of the specific record |
| `operation` | The action taken (e.g., `"RedactPii"`) |
| `status` | `"Success"` or `"Failed"` for this individual operation |
| `recordsAffected` | Number of records modified by this operation |
| `durationMs` | Time taken in milliseconds |
| `errorMessage` | Populated only on failure; describes what went wrong |
If any entries have `status: "Failed"`, check `errorMessage` for details and review `errorSummary` on the report for a rolled-up description.
***
## Listing and Auditing Reports
**Endpoint:** `GET /platform/data/redaction/report` — [API reference](/api-reference/redaction/list-redaction-reports)
Use this endpoint to retrieve a paginated list of reports — useful for auditing which requests have been fulfilled and which drafts are awaiting execution.
#### Query parameters
| Parameter | Type | Description |
| ---------- | --------- | ------------------------------------------------------------------ |
| `status` | string | Filter by report status: `Draft` or `Executed` |
| `from` | date-time | Return only reports created at or after this timestamp (ISO 8601) |
| `to` | date-time | Return only reports created at or before this timestamp (ISO 8601) |
| `page` | integer | Page number (1-based) |
| `pageSize` | integer | Number of results per page |
#### Example request
```
GET /platform/data/redaction/report?status=Draft&page=1&pageSize=20
```
#### Example response
```json theme={null}
{
"startIndex": 0,
"pageSize": 20,
"items": [
{
"reportId": "a3f9c2d1-4e7b-4f8a-b2c3-9d0e1f2a3b4c",
"schemaVersion": 1,
"tenantId": 1000000,
"status": "Draft",
"subject": {
"customerAccountId": 4820193,
"userId": null,
"resolvedEmailAddresses": ["jane.doe@example.com"]
},
"createdAt": "2026-03-19T14:00:00Z",
"executionStartedAt": null,
"executionCompletedAt": null,
"errorSummary": null
}
]
}
```
Note that the list response returns `RedactionReportSummaryResponse` objects, which do **not** include `affectedEntities`, `request`, or `operationLog`. To get those fields, retrieve the individual report by ID.
***
## Field Reference
Key fields on `RedactionReportResponse`:
| Field | Type | Description |
| -------------------------------- | --------- | ------------------------------------------------------------ |
| `reportId` | string | Unique identifier for this redaction report |
| `status` | string | `"Draft"` before execution, `"Executed"` after |
| `tenantId` | integer | The Kibo tenant this report belongs to |
| `subject.customerAccountId` | integer | Resolved customer account ID of the data subject |
| `subject.resolvedEmailAddresses` | string\[] | Email addresses resolved from the subject's account |
| `affectedEntities` | object | Counts and IDs of all records that will be / were redacted |
| `operationLog` | array | Per-record operation results; populated only after execution |
| `createdAt` | date-time | When the draft report was created |
| `executionStartedAt` | date-time | When execution began (null on Draft) |
| `executionCompletedAt` | date-time | When execution finished (null on Draft) |
| `errorSummary` | string | High-level error description if any operations failed |
***
## Troubleshooting
**Empty `affectedEntities` on a draft report**
The subject identifier provided (`customerAccountId` or `userId`) did not match any records. Verify the ID is correct for your tenant. Note that `customerAccountId` is a tenant-scoped integer, not a global Kibo user ID.
**`400` or `422` when creating a report**
Ensure you are providing at least one of `customerAccountId` or `userId`. Providing neither, or providing an `attributeFqns` array with invalid FQN strings, will result in a validation error.
**Attempting to execute an already-executed report**
Once a report has `status: "Executed"`, calling `POST /platform/data/redaction/execute/{reportId}` again will return an error. Each data subject erasure request requires a new draft report.
**Partial failures in the operation log**
If some `operationLog` entries show `status: "Failed"`, the redaction completed partially. Records that failed were not redacted. Review each failed entry's `errorMessage`. You may need to create and execute a new report to retry the affected records, or investigate the underlying data integrity issue before retrying.
# Reservation API
Source: https://docs.kibocommerce.com/developer-guides/reservation
Temporary inventory holds during checkout to prevent overselling
# Kibo Reservations API Developer Guide
Understand how reservations fit into inventory management
Handle inventory reservations for low-stock items
## Understanding Reservations in Kibo
In Kibo, a **Reservation** is a temporary, short-term hold on a specific quantity of a product at a specific location. It's a key mechanism to prevent overselling during the active shopping process, especially in high-volume environments.
What makes Kibo's approach different is that a reservation is an explicit, API-managed object, not an implicit side-effect of adding an item to a cart. When a customer proceeds to checkout, your application should create a reservation for the items in their cart. This "soft-allocates" the inventory, taking it out of the available-to-sell pool for a limited time. If the customer completes the purchase, the reservation is **committed**; if they abandon the cart, the reservation is **deleted** or expires, and the inventory is automatically returned to the pool. This system provides a robust guarantee that what's in the cart is available to be purchased.
## How This Domain Fits Into Kibo
The Reservations domain is the bridge between the **Cart/Checkout** process and the **Inventory** domain. It ensures data integrity for inventory during the most volatile part of the customer journey.
* **Inventory:** A reservation reduces the `available` quantity of a product at a location but does not affect the `onHand` quantity. It's a temporary promise. Only when an order is fulfilled is the `onHand` quantity decremented.
* **Checkout & Cart:** The checkout flow is the primary driver for creating and managing reservations. A successful checkout should commit the reservation, while an abandoned cart should delete it.
* **Orders:** Once an order is placed, the associated reservation is typically committed. The `orderId` is a key piece of data stored on the reservation object itself, linking the inventory hold to the final transaction.
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs and asynchronous concepts
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo uses reservations to temporarily hold inventory (based on official API specs).
* The key patterns for creating, updating, committing, and deleting reservations (verified from apidocs.kibocommerce.com).
* The common workflow for managing inventory holds during a customer checkout.
* How to avoid the most common beginner mistakes, like confusing a reservation with a final inventory transaction.
* How to read and navigate the official Commerce Inventory Reservations API documentation effectively.
***
## Kibo Reservations Fundamentals
### How Kibo Organizes Reservation Data
The system is centered on the `Reservation` object. It's a simple yet powerful construct:
* **`Reservation`**: The core object representing the inventory hold. It is identified by a system-generated `reservationId`. The most important properties are:
* `orderId`: Links the reservation to a cart or checkout object (which will later become the order).
* `locationCode`: Specifies *where* the inventory is being held. Inventory is always location-specific.
* `items`: An array of objects, each specifying a `productCode`, `quantity`, `lineId` and `id` (a unique identifier for that item within the cart/order).
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new ReservationsApi(configuration)`).
**Request/Response Structure:**
Many reservation operations are done in bulk for efficiency. The API expects and returns a `ReservationCollection` object, which contains an array of individual `Reservation` objects.
```json theme={null}
// Actual response schema for POST /api/commerce/reservation
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"userId": "string",
"customerAccountId": 0,
"items": [
{
"lineId": 0,
"id": "string",
"orderItemId": "string",
"product": {
"productCode": "string",
"name": "string",
"productType": "string",
"mfgPartNumber": "string",
"variationProductCode": "string",
"sku": "string",
"goodsType": "string",
"productUsage": "string",
"bundledProducts": [
{
"productCode": "string",
"name": "string",
"goodsType": "string",
"quantity": 0,
"optionAttributeFQN": "string",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
}
}
],
"isSplitExtrasInShipment": true,
"properties": [
{
"attributeFQN": "string",
"values": [
{
"stringValue": "string"
}
]
}
],
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"isTaxable": true,
"serialNumber": "string",
"condition": "string"
},
"quantity": 0,
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"allocations": [
{
"itemId": "string",
"quantity": 0,
"fulfillmentLocationCode": "string",
"transferLocationCode": "string",
"productCode": "string",
"futureDate": "2025-11-07T16:33:22.065Z",
"isStateChange": true,
"allocationId": 0
}
],
"allowsBackOrder": true,
"allocationStatus": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"suggestions": [
{
"locationCode": "string",
"suggestionType": "string",
"quantity": 0,
"productCode": "string",
"futureDate": "2025-11-07T16:33:22.065Z"
}
],
"fulfillmentContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
}
}
],
"cartId": "string",
"orderId": "string",
"orderNumber": 0,
"expirationDateTime": "2025-11-07T16:33:22.065Z",
"zipCode": "string",
"status": "string",
"auditInfo": {
"createdBy": "string",
"createdAt": "2025-11-07T16:33:22.065Z",
"updatedBy": "string",
"updatedAt": "2025-11-07T16:33:22.065Z"
},
"changeMessages": [
{
"id": "string",
"identifier": "string",
"correlationId": "string",
"userId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-11-07T16:33:22.065Z"
}
],
"reservationType": "string",
"fulfillmentContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
}
}
```
**Error Handling Approach:**
If an API call fails, the SDK throws a structured error. For reservations, a common error is `VALIDATION_CONFLICT`, which indicates that the requested quantity is not available to be reserved.
```json theme={null}
// Actual error schema from Kibo
{
"message": "Validation Error: Enough inventory not found for the items [Hats_001,787872]",
"errorCode": "VALIDATION_CONFLICT",
"correlationId": "e0b5b9b0-a5f1-4f1e-9a0c-12345abcdef"
}
```
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_reservation_overview`
### Common Reservation Workflows
1. **Standard Checkout:** Create a reservation when a user enters the checkout flow. Commit the reservation on successful order placement. Delete the reservation if the user abandons the flow.
2. **Cart Quantity Update:** Update the reservation when a user changes an item's quantity in their cart during checkout.
3. **Order Cancellation:** If a customer cancels an order shortly after placing it (before fulfillment), the corresponding reservation might be deleted to release the inventory immediately.
Let's explore each CRUD operation step by step.
***
## Create Reservations: The Kibo Way
### When You Need This
This is the first step in the checkout process. As soon as a customer signals their intent to buy (e.g., by clicking "Proceed to Checkout"), you should create a reservation to hold the items in their cart.
### API Documentation Reference
**Endpoint:** `POST /commerce/reservation`
**Method:** `POST`
**API Docs:** [/api-overviews/openapi\_reservation\_overview](/api-overviews/openapi_reservation_overview)
### Understanding the Kibo Approach
Kibo optimizes this operation by allowing you to reserve items for a single order at multiple locations in one API call. You provide an array of `Reservation` objects, and the system processes them together. The API call is synchronous—it will immediately check for available inventory and either succeed by returning the created reservation objects or fail with an `VALIDATION_CONFLICT` error. This gives you instant feedback to show the customer.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance.
// 2. **API Client Instantiation**: Create a dedicated client for the Reservations API.
// 3. **Data Preparation**: Construct an array of Reservation objects based on the items in the customer's cart.
// 4. **API Call**: Use the instantiated client to call the `addReservations` method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Reservation operations.
import { Configuration } from "@kibocommerce/rest-sdk";
import { Reservati as Reservation } from "@kibocommerce/rest-sdk/clients/Reservation/models";
import { ReservationApi } from "@kibocommerce/rest-sdk/clients/Reservation";
import { ReservationCollecti as ReservationCollection } from "@kibocommerce/rest-sdk/clients/Reservation/models";
import 'dotenv/config';
// Global configuration object available to all examples
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID || 'test-tenant',
siteId: process.env.KIBO_SITE_ID || 'test-site',
clientId: process.env.KIBO_CLIENT_ID || 'test-client',
sharedSecret: process.env.KIBO_SHARED_SECRET || 'test-secret',
authHost: process.env.KIBO_AUTH_HOST || 'home.mozu.com',
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example for creating reservations for a cart.
// 'cartItems' would be the items from your cart object.
// 'orderId' would be the ID of your cart/checkout object.
async function createReservationsForCart(
orderId: string,
cartItems: { lineId: number;fulfillmentMethod: string, product : any; quantity: number }[],
zipCode: string
): Promise {
console.log(`Creating reservations for order ID: ${orderId}...`);
const reservationsClient = new ReservationApi(configuration);
// 1. Prepare the request payload. The API expects an array of Reservation objects.
const reservationPayload: Reservation = {
cartId: orderId,
items: cartItems,
zipCode: zipCode
};
// 2. Call the method on the client.
try {
const createdReservations = await reservationsClient.createReservation({
reservati: reservationPayload,
});
console.log("Success! Reservations created:", createdReservations);
return createdReservations;
} catch (error) {
// This error should be handled in the UI.
console.error("API Error creating reservations:", JSON.stringify(error, null, 2));
throw error; // Propagate the error to be handled by the checkout flow.
}
}
```
***
## Update & Delete Reservations
### Update Reservations
**When You Need This:** If a customer changes the quantity of an item or adds/removes an item *after* the initial reservation has been made (e.g., on the final review step of checkout).
**API Documentation Reference:**
* **Endpoint:** `PUT /commerce//reservation`
* **Method:** `PUT`
* **API Docs:** [Update Reservation](/api-reference/reservation/update-reservation)
**The Kibo Approach:** Similar to creation, updating is a bulk operation. You send the complete, updated set of `Reservation` objects. Kibo then adjusts the inventory holds accordingly.
```ts theme={null}
async function updateReservationsForCart(
updatedReservations: Reservation
): Promise {
const reservationClient = new ReservationApi(configuration);
try {
const result = await reservationClient.updateReservation({
reservationId: updatedReservations.id as string,
reservati: updatedReservations,
});
console.log("Reservations updated successfully.");
return result;
} catch (error) {
console.error("API Error updating reservations:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### Delete a Reservation
**When You Need This:** When a customer abandons the checkout flow or their session expires. Deleting the reservation releases the held inventory back into the available-to-sell pool.
**API Documentation Reference:**
* **Endpoint:** `DELETE /commerce/reservation/{reservationId}`
* **Method:** `DELETE`
* **API Docs:** [Delete Reservation](/api-reference/reservation/delete-reservation)
**The Kibo Approach:** This is a simple, direct operation to remove a single reservation hold by its unique ID.
```ts theme={null}
async function deleteReservationById(reservationId: string): Promise {
const reservationClient = new ReservationApi(configuration);
try {
// This call returns a 204 No Content on success.
await reservationClient.deleteReservation({ reservationId });
console.log(`Reservation ${reservationId} deleted successfully.`);
} catch (error) {
console.error("API Error deleting reservation:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Multiple Real-World Examples
**Example 1: The Full Checkout Reservation Workflow**
This example simulates the entire lifecycle of a reservation during a successful purchase.
```ts theme={null}
async function runFullCheckoutReservation(orderId: string, items: any[], locationCode: string) {
const reservationClient = new ReservationApi(configuration);
// 1. Create the reservation at the start of checkout.
const createdReservation = await createReservationsForCart(orderId, items, locationCode);
if (!createdReservation) {
throw new Error("Failed to create any reservations.");
}
const reservationId = createdReservation.id as string;
console.log(`Reservation ${reservationId} created.`);
// --- Customer completes the order successfully ---
console.log("Order placed. Closing reservation...");
// 2. Close the reservation. This is an advanced action.
try {
await reservationClient.closeReservation({ reservationId: reservationId });
console.log(`Reservation ${reservationId} has been closed.`);
} catch (error) {
console.error("Failed to close reservation:", JSON.stringify(error, null, 2));
// In a real app, you might need to handle this failure (e.g., by cancelling the order).
throw error;
}
}
```
**Example 2: Get All Reservations for a Specific Order**
```ts theme={null}
async function getReservationsByOrderId(orderId: string): Promise {
const reservationClient = new ReservationApi(configuration);
try {
// Use the filter parameter to query for reservations linked to a specific orderId.
const response = await reservationClient.getReservationsByCartId({
cartId: orderId
});
console.log(`Found ${response.items?.length} reservation(s) for order ${orderId}.`);
return response;
} catch (error) {
console.error("Failed to get reservations:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 3, 4, 5:** The `createReservationsForCart`, `updateReservationsForCart`, and `deleteReservationById` functions shown in the previous sections serve as complete, runnable examples for the core CRUD operations.
***
## Integrating Reservations with Other Kibo Domains
### Reservations + Inventory Integration
This is the most direct relationship. A reservation's entire purpose is to manipulate inventory availability. The `addReservations` call will fail if the `available` quantity at the specified `locationCode` is less than the requested quantity. Committing a reservation signals to the inventory system that this quantity is now allocated to an order and will be decremented from the `onHand` count upon shipment.
### Reservations + Order Management (OMS)
In a sophisticated Order Management System (OMS) flow, reservations are used to determine sourcing. Before fulfilling an order, the OMS may create temporary reservations at several possible locations to find the optimal sourcing solution. Once the best location is determined, the reservation at that location is committed, and the temporary reservations at the other locations are deleted.
***
## Troubleshooting Your Reservations Implementation
### Reading Kibo Error Messages
```typescript theme={null}
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
}
```
**Common Error Codes for Reservations:**
* `INSUFFICIENT_STOCK`: The most common error. It means you cannot create or update a reservation because there is not enough available inventory.
* `RESERVATION_NOT_FOUND`: The `reservationId` you provided to `deleteReservation` or another endpoint does not exist.
* `VALIDATION_ERROR`: The request body is malformed. A common cause is a missing `locationCode` or an invalid `productCode`.
### Common Development Issues
**Issue 1:** My `addReservations` call fails with an `INSUFFICIENT_STOCK` error, but the UI shows the item is in stock.
* **Why it happens:** This is a classic race condition. Between the time the customer loaded the product page and when they tried to check out, another customer (or a store associate) purchased the last item. The reservation API provides the real-time, authoritative answer on availability.
* **How to fix it:** Your checkout UI must gracefully handle this error. When you catch an `INSUFFICIENT_STOCK` error, you should display a clear message to the user (e.g., "An item in your cart is no longer available") and prompt them to review their cart.
**Issue 2:** Inventory is being "locked" and never becomes available again.
* **Why it happens:** This usually means your application is creating reservations but failing to delete them when a user abandons their cart. Without a `deleteReservation` call, the inventory will remain held until the reservation automatically expires (typically after a short period, like 30 minutes).
* **How to fix it:** Ensure your application has a robust mechanism to detect an abandoned session or an explicit "Remove from Cart" action during checkout. This mechanism must trigger a call to the `deleteReservation` endpoint. While Kibo's automatic expiration is a good safety net, you should not rely on it for normal operation.
# Settings API
Source: https://docs.kibocommerce.com/developer-guides/settings
Business configuration and site settings for platform behavior
# Kibo Settings API Developer Guide
## Understanding Settings in Kibo
In Kibo, **Settings** are the administrative controls that define the business logic and behavior of your e-commerce site. Unlike data that changes frequently (like orders or inventory), settings are configured once and then modified occasionally to adapt to business needs. They are the "switches and dials" of the platform.
What makes Kibo's approach different is the granularity and scope of its settings. They are not just a flat list of key-value pairs; they are structured, domain-specific JSON objects. For example, `InventorySettings` is a complete object that controls everything from backordering logic to how stock levels are displayed, while `ReturnSettings` governs the entire RMA workflow. Interacting with these settings programmatically allows you to automate site configuration, synchronize environments, and build powerful administrative tools.
## How This Domain Fits Into Kibo
The Settings domain is foundational. It underpins the logic of virtually every other part of the Kibo platform. The settings you configure dictate how the other APIs behave.
* **Inventory:** `InventorySettings` determine if a product can be backordered, which directly affects the **Inventory** and **Order** domains.
* **Fulfillment:** `ShippingSettings` define the origin address and other parameters used by the **Fulfillment** domain to calculate shipping costs.
* **Subscription:** `SubscriptionSettings` control fundamental subscription behaviors, like the next order date offset and how pricing is applied on continuity orders.
* **Returns:** `ReturnSettings` define the rules that the **Returns** API enforces, such as the valid window for a customer to initiate a return.
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo organizes its business logic into distinct, structured settings objects (based on official API specs).
* The key "read-then-write" pattern required to safely update settings (verified from apidocs.kibocommerce.com).
* Common workflows like enabling backordering or updating your shipping origin address programmatically.
* How to avoid the most common beginner mistake: accidentally deleting settings with a partial update.
* How to read and navigate the official Settings API documentation effectively.
***
## Kibo Settings Fundamentals
### How Kibo Organizes Settings Data
Kibo groups settings into logical, domain-specific objects. Each object is a complete document containing all the configurable properties for that domain. The primary objects you'll work with are:
* `GeneralSettings`: Site-wide information like name, contact info, and security settings.
* `InventorySettings`: Controls for stock levels, backordering, and out-of-stock behavior.
* `ReturnSettings`: Rules for the customer return process.
* `ShippingSettings`: The master configuration for order shipping, including origin address.
* `CartSettings`: Controls for the shopping cart behavior.
* `CustomerCheckoutSettings`: Rules for the customer-facing checkout process.
* `SubscriptionSettings`: Configuration for subscription products and continuity programs.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new GeneralSettingsApi(configuration)`).
**Request/Response Structure:**
When you get a settings object, Kibo returns the complete JSON document for that domain.
```json theme={null}
// Actual response schema for GET /commerce/settings/general
{
"isMozuWebstore": true,
"isMultishipEnabled": false,
"isTaxEstimationEnabled": true,
"isUspsValidationEnabled": false,
"siteName": "My Kibo Store",
"siteTimezone": "Central Standard Time"
// ... many other general settings
}
```
**The Required Update Pattern (GET then PUT):**
This is the most important pattern for settings. **The `update` endpoints use the `PUT` HTTP method, which performs a complete replacement of the object.** If you send only a partial object, you will wipe out all the other settings in that group. The only safe way to update a setting is to:
1. **GET** the full settings object.
2. **Modify** the specific property you want to change on that object.
3. **PUT** the entire, modified object back.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_settings_overview`
### Common Settings Workflows
1. **Environment Synchronization:** Reading settings from a production environment and programmatically applying them to a sandbox or staging environment to ensure consistency.
2. **Automated Configuration:** As part of a new site deployment script, automatically enabling or disabling features like guest checkout or backordering.
3. **Building Custom Admin Tools:** Creating a simplified UI for business users to change a specific setting without giving them full access to the Kibo Admin.
Let's explore the core pattern for a few key settings types.
***
## Managing General Settings: The Kibo Way
### When You Need This
This is the most basic settings operation, often used to update your site's name, timezone, or contact email programmatically. It serves as the introduction to the required "GET then PUT" pattern.
### API Documentation Reference
**Get Endpoint:** `GET /commerce/settings/general`
**Update Endpoint:** `PUT /commerce/settings/general`
**Method:** `GET`, `PUT`
**API Docs:** [/api-overviews/openapi\_settings\_overview#get-general-settings](/api-reference/generalsettings/get-general-settings)
### Understanding the Kibo Approach
Kibo groups all top-level site settings into a single `GeneralSettings` object. To ensure data integrity and prevent accidental misconfigurations, it requires you to submit the *entire* object when making a change. This forces you to acknowledge the current state of all other settings before applying an update.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance.
// 2. **API Client Instantiation**: Create a client for the General Settings API.
// 3. **GET Operation**: Fetch the current GeneralSettings object.
// 4. **Data Modification**: Change a value on the retrieved object.
// 5. **PUT Operation**: Send the entire modified object back to the API.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Settings operations.
// The SDK is organized by API groups; we import the clients for each settings area we need.
import { Configuration } from "@kibocommerce/rest-sdk";
import { GeneralSettingsApi, InventorySettingsApi, ReturnSettingsApi, ShippingSettingsApi, CartSettingsApi, CustomerCheckoutSettingsApi, SubscriptionSettingsApi } from "@kibocommerce/rest-sdk/clients/Settings";
import { GeneralSettings } from "@kibocommerce/rest-sdk/clients/Settings/models";
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function updates the site's public email address.
async function updateSiteEmail(newEmail: string) {
console.log("Updating site email address...");
const generalSettingsClient = new GeneralSettingsApi(configuration);
try {
// 1. GET the current settings first. This is mandatory.
console.log("Fetching current general settings...");
const currentSettings = await generalSettingsClient.getGeneralSettings();
// 2. Modify only the property you want to change on the retrieved object.
console.log(`Changing email from '${currentSettings.replyToEmailAddress}' to '${newEmail}'`);
currentSettings.replyToEmailAddress = newEmail;
// 3. PUT the entire modified object back.
const updatedSettings = await generalSettingsClient.updateGeneralSettings({
generalSettings: currentSettings
});
console.log("Success! Site email has been updated.");
return updatedSettings;
} catch (error) {
console.error("API Error updating general settings:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the standard `Configuration` object.
* We instantiated the `GeneralSettingsApi` client to work with general settings.
* The **required step** was calling `getGeneralSettings()` *before* attempting the update. This gave us a complete object representing the current state.
* We then modified a single property on this local object.
* Finally, the `updateGeneralSettings()` call sent the **full object** back, ensuring that only our desired change was made while preserving all other existing settings.
### Common Beginner Mistakes
**Mistake 1:** Performing a partial update and deleting settings. This is the most dangerous mistake when working with settings.
```ts theme={null}
// Wrong - This will delete all other general settings.
await generalSettingsClient.updateGeneralSettings({
generalSettings: { replyToEmailAddress: "new@example.com" }
});
// Correct - Always get the full object, modify it, then put it back.
const current = await generalSettingsClient.getGeneralSettings();
current.replyToEmailAddres = "new@example.com";
await generalSettingsClient.updateGeneralSettings({ generalSettings: current });
```
***
## Multiple Real-World Examples
The "GET then PUT" pattern applies to all settings. The only difference is the client and the structure of the settings object.
**Example 1: Enable Backordering (Inventory Settings)**
```ts theme={null}
async function enableBackordering() {
const fulfillmentSettingsClient = new FulfillmentSettingsApi(configuration);
console.log("Enabling backordering...");
try {
// 1. GET
const currentSettings = await fulfillmentSettingsClient.getFulfillmentSettings();
// 2. MODIFY
currentSettings.fulfillmentJobSettings.releaseBackorderJob = {
"partialReleaseEnabled": false,
"isEnabled": true,
"interval": 2
}; // Verified from API schema
// 3. PUT
const updatedSettings = await fulfillmentSettingsClient.updateFulfillmentSettings({ fulfillmentSettings: currentSettings });
console.log("Backordering is now enabled.");
return updatedSettings;
} catch (error) {
console.error("Failed to enable backordering:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 2: Update the Return Restock Setting**
```ts theme={null}
async function setUpdateOnHandOnReturnStock(days: number) {
const returnSettingsClient = new ReturnSettingsApi(configuration);
console.log(`Setting return window to ${days} days...`);
try {
const currentSettings = await returnSettingsClient.getReturnSettings();
currentSettings.updateInventoryOnRestock = true;
const updatedSettings = await returnSettingsClient.updateReturnSettings({ returnSettings: currentSettings });
console.log("Return window updated.");
return updatedSettings;
} catch (error) {
console.error("Failed to update return window:", JSON.stringify(error, null, 2));
throw error;
}
}
```
**Example 3: Update Subscriptions Settings**
```ts theme={null}
async function updateSubscriptionSettings(allow: boolean) {
const subscriptionSettingClient = new SubscriptionSettingsApi(configuration);
try {
const currentSettings = await subscriptionSettingClient.getSubscriptionSettings();
currentSettings.continuityOrderDateOffset = 15;
const updatedSettings = await subscriptionSettingClient.updateSubscriptionSettings({ subscriptionSettings: currentSettings });
console.log(`Subscription continuity order date offset updated to ${currentSettings.continuityOrderDateOffset}.`);
return updatedSettings;
} catch (error) {
console.error("Failed to continuity order date offset setting:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Integrating Settings with Other Kibo Domains
### Settings + Storefront Experience
Settings have a direct and immediate impact on the storefront. When you update `CustomerCheckoutSettings` to disallow guest checkout, the very next user who tries to check out without logging in will be blocked. When you update `CartSettings`, the `cross-sell` products a user sees may change. These settings are the primary way a business user configures the customer experience without changing code.
### Settings + Order Management
The entire order management lifecycle is governed by settings. `InventorySettings` control sourcing, `ShippingSettings` control rate calculation, and `ReturnSettings` control post-purchase workflows. Programmatically changing these settings allows you to adapt your fulfillment logic to changing conditions, such as disabling backorders during a supply chain disruption.
***
## Troubleshooting Your Settings Implementation
### Reading Kibo Error Messages
```typescript theme={null}
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
}
```
**Common Error Codes for Settings:**
* `VALIDATION_ERROR`: The request body is malformed or contains an invalid value for a setting (e.g., an incorrect enum value for `backorderBehavior`). The `message` field will often contain details about which property was invalid.
* `ITEM_NOT_FOUND`: Usually means the settings for that domain have not been initialized. This is rare.
* `UNAUTHORIZED`: Your API credentials do not have the permissions required to read or update settings.
### Common Development Issues
**Issue 1:** "I updated a setting, and now my entire site configuration is broken!"
* **Why it happens:** You fell into the most common trap: you performed a partial update using `PUT`. You sent a request body with only the single setting you wanted to change, which caused the Kibo API to delete all the other settings in that group.
* **How to fix it:** Immediately `GET` the settings from a backup environment (like Production) and `PUT` the full, correct object back into the broken environment.
* **How to avoid it:** **NEVER** call an `update` (PUT) endpoint for settings without first calling the corresponding `get` endpoint and modifying the result. Your code must always follow the "GET, Modify, PUT" pattern.
* **API Reference:** This applies to all `PUT` endpoints in the Settings API group.
**Issue 2:** "I'm trying to update a setting, but the API returns a `VALIDATION_ERROR` with a confusing message."
* **Why it happens:** The value you are trying to set is invalid for that specific property. Many settings properties are not free-form strings; they must be one of a specific set of enumerated values (e.g., `backorderBehavior` must be `AllowBackorder`, `AllowBackorderAndNotify`, or `EnterPendingOrder`).
* **How to fix it:** Carefully review the API documentation at `apidocs.kibocommerce.com` for the specific settings object you are working with. The schema definition will show the allowed values for each property. The `GET` response for that setting will also show you the currently valid value.
# Shipment Packages API
Source: https://docs.kibocommerce.com/developer-guides/shipment-packages
Physical package creation, dimensions, and tracking for shipments
# Kibo Shipment Packages API Developer Guide
Understand fulfillment architecture and concepts
Configure multi-piece shipments in the Admin UI
## Understanding Shipment Packages in Kibo
In Kibo, it's essential to distinguish between a **Shipment** and a **Package**. A Shipment is an abstract concept representing a group of items from an order that are being fulfilled together. A **Package**, the focus of this guide, is the tangible, physical box that you put those items into. You can have a single shipment that is split across multiple packages, each with its own dimensions, weight, and tracking number.
What makes Kibo's approach different is that creating a Package is a distinct, explicit step in the fulfillment workflow. It's the point where the abstract "shipment" becomes a real-world object ready for a shipping label. This explicit step allows for granular control over the packing process and precise communication with shipping carriers.
## How This Domain Fits Into Kibo
The Shipment Packages domain is a key part of the **Fulfillment** process and is tightly coupled with the **Order** domain. It represents the final stage of preparing an order for dispatch.
* **Fulfillment & Shipments:** A `Package` is always a child of a `Shipment`. You cannot create a package without first having a shipment to associate it with. The shipment dictates *what* items need to be packed, and the package records *how* they are packed.
* **Orders:** Creating packages and generating shipping labels are key steps that trigger order status updates. Once a package has a shipping label, the associated shipment is typically marked as "Fulfilled," and the customer is notified with the tracking information.
* **Carrier Integration:** The details you provide when creating a package (like weight and dimensions) are sent directly to integrated shipping carriers (like FedEx or UPS) to generate accurate shipping labels and rates.
## Prerequisites
* Kibo API credentials and basic setup
* Node.js 16+ with TypeScript
* Familiarity with REST APIs
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo models physical packages as distinct objects within a shipment (based on official API specs).
* The key patterns for creating, updating, and deleting packages as part of the fulfillment process (verified from apidocs.kibocommerce.com).
* The common workflow for packing items and preparing a shipment for label generation.
* How to avoid the most common beginner mistakes, like trying to create a package for a shipment that isn't ready.
* How to read and navigate the official Shipments API documentation effectively.
***
## Kibo Shipment Packages Fundamentals
### How Kibo Organizes Package Data
The data model is hierarchical and straightforward:
* **`Order`**: Contains one or more `Shipments`.
* **`Shipment`**: A group of items to be fulfilled. It is identified by a `shipmentNumber`. A shipment must be in the "Ready" state before you can create packages for it.
* **`Package`**: The core object of this guide. It is a child of a `Shipment` and is identified by a system-generated `packageId`. Its key properties include:
* `packagingType`: A string indicating the type of box (e.g., "Custom" or a carrier-specific type like "FedEx\_Box").
* `measurements`: An object containing the `weight` and `length`, `width`, `height`.
* `items`: An array specifying which items from the parent shipment (and in what quantity) are in this specific box.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:**
The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials (Client ID, Shared Secret, etc.). This object is then passed to the constructor of specific API clients (e.g., `new ShipmentApi(configuration)`).
**Request/Response Structure:**
When you create a new package, the API returns the complete `Package` object, including its newly assigned `packageId`.
```json theme={null}
// Actual response schema for POST /commerce/shipments/{shipmentNumber}/packages
{
"packageId": "a1b2c3d4e5f6",
"packagingType": "Custom",
"measurements": {
"weight": { "value": 5, "unit": "lbs" },
"length": { "value": 12, "unit": "in" },
"width": { "value": 10, "unit": "in" },
"height": { "value": 8, "unit": "in" }
},
"items": [
{
"productCode": "SHIRT-BLUE-M",
"quantity": 1
}
]
}
```
**Error Handling Approach:**
If an API call fails, the SDK throws a structured error. A common error in this domain is a `VALIDATION_ERROR` if you try to create a package for a shipment that is not yet in a "Ready" state.
```json theme={null}
// Actual error schema from Kibo
{
"message": "The shipment is not in a valid state to create a package. Current status is 'Pending'.",
"errorCode": "VALIDATION_ERROR",
"correlationId": "e0b5b9b0-a5f1-4f1e-9a0c-12345abcdef"
}
```
**API Documentation Reference:**
All package operations are part of the Shipments API group. Find complete specs at:
`/developer-guides/shipments`
### Common Shipment Package Workflows
1. **Standard Fulfillment:** A warehouse worker scans the items for a shipment, puts them in a box, weighs it, and a system calls the API to create the package record before generating a shipping label.
2. **Multi-Package Shipment:** An order for one large item and one small item is fulfilled in two separate boxes. Two `Package` objects are created under the same `Shipment`, each containing the appropriate item and its own dimensions.
3. **Correcting Mistakes:** A worker realizes they used the wrong box size. A system calls the API to update the package with the correct dimensions before the shipping label is created.
Let's explore each CRUD operation step by step.
***
## New Shipment Package: The Kibo Way
### When You Need This
This is the core operation in the packing process. You need this after you have physically placed items into a box and are ready to record its contents, weight, and dimensions in Kibo. This is the prerequisite for generating a shipping label.
### API Documentation Reference
**Endpoint:** `POST /commerce/shipments/{shipmentNumber}/packages`
**Method:** `POST`
**API Docs:** [/developer-guides/shipments#new-shipment-package](/api-reference/shipmentpackages/new-package)
### Understanding the Kibo Approach
Kibo requires you to be explicit about what is in each box. The API call to create a package requires you to specify which items from the parent shipment are included. This creates a detailed digital packing slip for each physical package, which is useful for accurate tracking, customer service, and managing claims with carriers if a package is lost or damaged.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance.
// 2. **API Client Instantiation**: Create a client for the Shipments API.
// 3. **Data Preparation**: Construct the request body for the new Package, detailing its contents and measurements.
// 4. **API Call**: Use the instantiated client to call the `newShipmentPackage` method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Shipment Package operations.
import { Configuration } from "@kibocommerce/rest-sdk";
import { ShipmentPackagesApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
import { Package } from "@kibocommerce/rest-sdk/models/Fulfillment";
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function creates a new package for a given shipment.
async function createNewPackage(
shipmentNumber: number,
packageDetails: Package
): Promise {
console.log(`Creating a new package for shipment ${shipmentNumber}...`);
// 1. Instantiate a dedicated client for the Shipment Packages API.
const shipmentPackagesApi = new ShipmentPackagesApi(configuration);
// 2. The packageDetails object is our request payload.
// It must match the schema defined in the Kibo API documentation.
// 3. Call the method on the client.
try {
const newPackage = await shipmentPackagesApi.newPackage({
shipmentNumber,
packageDto: packageDetails,
});
console.log(`Success! Package with ID "${newPackage.packageId}" created.`);
return newPackage;
} catch (error) {
console.error("API Error creating package:", JSON.stringify(error, null, 2));
throw error;
}
}
// Example usage:
// Assume shipment #10052 has one item: { productCode: 'TSHIRT-BLK-L', quantity: 2 }
// We are packing both items into one box.
// const newPackagePayload: ModelPackage = {
// packagingType: "Custom",
// measurements: {
// weight: { value: 2.5, unit: "lbs" },
// length: { value: 12, unit: "in" },
// width: { value: 12, unit: "in" },
// height: { value: 4, unit: "in" }
// },
// items: [
// {
// productCode: "TSHIRT-BLK-L",
// quantity: 2
// }
// ]
// };
// createNewPackage(10052, newPackagePayload);
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the standard `Configuration` object.
* We used an instance of `ShipmentApi`, as all package operations are nested under shipments.
* The **payload** we prepared was a `ModelPackage` object that precisely described the physical box: its dimensions, weight, and the exact contents from the parent shipment.
* The `newShipmentPackage` call sent this data to Kibo. Kibo validated that the items were part of the shipment and that the shipment was in a "Ready" state, then created the package record and returned it with its new `packageId`.
***
## Update & Delete Shipment Packages
### Update Shipment Package
**When You Need This:** If you need to correct the weight, dimensions, or contents of a package *before* a shipping label has been generated. For example, a packer uses a different box than originally planned, or a scale gives a more accurate weight.
**API Documentation Reference:**
* **Endpoint:** `PUT /commerce/shipments/{shipmentNumber}/packages/{packageId}`
* **Method:** `PUT`
* **API Docs:** [/developer-guides/shipments#update-shipment-package](/api-reference/shipmentpackages/update-package)
```ts theme={null}
// This function updates an existing package. Note: PUT is a full replacement.
async function updatePackageDetails(
shipmentNumber: number,
packageId: string,
updatedPackageDetails: Package
): Promise {
const shipmentPackagesApi = new ShipmentPackagesApi(configuration);
console.log(`Updating package ${packageId}...`);
try {
// As with other Kibo PUT operations, this performs a full replacement.
// It's safest to GET the package first, modify it, then PUT it back.
const updatedPackage = await shipmentPackagesApi.updatePackage({
shipmentNumber,
packageId,
packageDto: updatedPackageDetails,
});
console.log("Package updated successfully.");
return updatedPackage;
} catch (error) {
console.error("API Error updating package:", JSON.stringify(error, null, 2));
throw error;
}
}
```
### Delete Shipment Package
**When You Need This:** If you need to completely re-pack a shipment. For example, you decide to split a single-box shipment into two smaller boxes. You would delete the original package and create two new ones. You can only delete a package before a shipping label has been created for it.
**API Documentation Reference:**
* **Endpoint:** `DELETE /commerce/shipments/{shipmentNumber}/packages/{packageId}`
* **Method:** `DELETE`
* **API Docs:** [/developer-guides/shipments#delete-shipment-package](/api-reference/shipmentpackages/delete-shipment-package)
```ts theme={null}
// This function deletes a package from a shipment.
async function deletePackage(shipmentNumber: number, packageId: string): Promise {
const shipmentClient = new ShipmentApi(configuration);
console.log(`Deleting package ${packageId}...`);
try {
// This call returns a 204 No Content on success.
await shipmentClient.deleteShipmentPackage({
shipmentNumber,
packageId,
});
console.log("Package deleted successfully.");
} catch (error) {
console.error("API Error deleting package:", JSON.stringify(error, null, 2));
throw error;
}
}
```
***
## Multiple Real-World Examples
**Example 1: Split a Shipment into Two Packages**
This advanced workflow shows how to pack a single shipment into two boxes.
```ts theme={null}
async function splitShipmentIntoTwoPackages(shipmentNumber: number) {
// Assume shipment #10053 has two items:
const item1 = { productCode: 'MUG-01', quantity: 1 };
const item2 = { productCode: 'BOOK-02', quantity: 1 };
// Package 1: Just the mug
const package1Payload: ModelPackage = {
packagingType: "Custom",
measurements: { weight: { value: 2, unit: "lbs" }, /*...dims...*/ },
items: [item1]
};
const package1 = await createNewPackage(shipmentNumber, package1Payload);
// Package 2: Just the book
const package2Payload: ModelPackage = {
packagingType: "Custom",
measurements: { weight: { value: 3, unit: "lbs" }, /*...dims...*/ },
items: [item2]
};
const package2 = await createNewPackage(shipmentNumber, package2Payload);
console.log(`Shipment ${shipmentNumber} successfully split into two packages: ${package1.packageId} and ${package2.packageId}`);
}
```
**Example 2, 3, 4, 5**: The `createNewPackage`, `updatePackageDetails`, and `deletePackage` functions above serve as complete, runnable examples for each core CRUD operation. The combination in Example 1 also showcases an advanced, multi-step pattern.
***
## Integrating Shipment Packages with Other Kibo Domains
### Packages + Fulfillment Workflow
The creation of a package is a key state transition in the fulfillment process. Once all items in a shipment are assigned to one or more packages, the shipment is typically considered "Packed" and is ready for the next step: generating shipping labels. The `packageId` is a required parameter for the API call that creates a shipping label.
### Packages + Customer Experience
The `packageId` and its associated `trackingNumber` (which is added to the package object after label generation) are important for the customer experience. This information is used to populate the "Your order has shipped!" email and to provide detailed tracking information on the order status page. Having separate packages allows you to show a customer that their single order is arriving in multiple boxes, each with its own tracking link.
***
## Troubleshooting Your Package Implementation
### Reading Kibo Error Messages
```typescript theme={null}
interface KiboApiError {
errorCode: string; // Specific error codes from apidocs.kibocommerce.com
message: string; // Error description
correlationId: string; // For support tracking
}
```
**Common Error Codes for Packages:**
* `VALIDATION_ERROR`: The most common error. This can happen for many reasons: the shipment is not in a "Ready" state, you try to put an item in a package that isn't in the parent shipment, or the quantities don't match. The `message` field is essential for debugging.
* `SHIPMENT_NOT_FOUND`: The `shipmentNumber` you provided does not exist.
* `PACKAGE_NOT_FOUND`: The `packageId` you provided for an update or delete operation does not exist.
### Common Development Issues
**Issue 1:** My call to `newShipmentPackage` is failing with a `VALIDATION_ERROR` about the shipment's state.
* **Why it happens:** You can only create packages for shipments that are in the `Ready` state. If the shipment is still `Pending` or has already been `Fulfilled`, the API will reject the request.
* **How to fix it:** Before attempting to create a package, your application should first `GET` the shipment and verify that its `status` is `Ready`. If it's not, you cannot proceed with packing.
**Issue 2:** I created a package, but now I can't delete it.
* **Why it happens:** The most likely reason is that a shipping label has already been generated for that package. Once a package is associated with a carrier label and tracking number, it becomes part of a financial transaction with the carrier and is effectively "locked" to prevent data integrity issues.
* **How to fix it:** The fulfillment workflow must be reversed in the correct order. You would first need to void the shipping label through the carrier integration, which would then allow the package to be deleted. In practice, it's often easier to work with the shipment as-is unless there is a significant error.
# Shipments API
Source: https://docs.kibocommerce.com/developer-guides/shipments
Fulfillment shipment management and order dispatch workflows
# Kibo Shipments API Developer Guide
Understand fulfillment architecture and concepts
Manage shipment holds in the Admin UI
Configure pick lists and sheets in the Admin UI
Set up shipment attributes in the Admin UI
Configure multi-piece shipments in the Admin UI
/
### Understanding Fulfillment (Shipments) in Kibo
In Kibo, a **Shipment** is the fundamental object in the fulfillment process. It's a concrete, actionable instruction for a specific location (like a warehouse or a retail store) to pick, pack, and dispatch a set of items from an order.
The key thing to understand is the separation of concerns:
* An **Order** is the customer's request—what they bought.
* **Order Routing** is the decision—*how* the order should be fulfilled.
* A **Shipment** is the action—the specific "to-do list" sent to a fulfillment location.
An order can be broken down into **multiple shipments**, each assigned to a different location. Managing the lifecycle of these individual shipments is the core of fulfillment in Kibo.
***
### How This Domain Fits Into Kibo
The Shipment is the workhorse of the post-purchase process. It's where the digital order becomes a physical reality.
* **Order Routing**: The output of the Order Routing engine is a "suggestion" that becomes the direct input for creating one or more shipments.
* **Inventory**: When a shipment is created, Kibo firms up the inventory reservation. When it's fulfilled, the `onHand` inventory at the assigned location is finally decremented.
* **Customer**: The customer is notified about the progress of their shipments, including tracking numbers which are stored on the shipment record.
* **Returns**: If a customer wants to return an item, the return is processed against the original shipment it came from.
***
### Prerequisites
* Kibo API credentials with Fulfillment permissions.
* An understanding of Kibo's **Order** and **Location** concepts.
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
### What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Shipment** data and its state-driven lifecycle (based on official API specs).
* The key "**Task-Based**" pattern Kibo uses for all shipment modifications.
* Common workflows like fulfilling and canceling shipments (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official API documentation for Fulfillment.
***
***
## Kibo Shipment Fundamentals
### How Kibo Organizes Fulfillment Data
Kibo's Fulfillment data is built around a **state machine**, where a **Shipment** moves through various stages. The core objects are:
* **`Shipment`**: The main object representing a fulfillment task.
* `shipmentNumber`: A unique, Kibo-assigned number identifying the shipment.
* `orderId`: The order this shipment belongs to.
* `locationCode`: The specific location responsible for fulfilling this shipment.
* `workflowState`: The current stage of the shipment (e.g., `Ready`, `Fulfilled`, `Cancelled`). This is the most important status field.
* `items`: An array of `ShipmentItem` objects detailing the products and quantities to be fulfilled.
* **`Pickup`**: For "Buy Online, Pick Up in Store" (BOPIS) shipments, a related `Pickup` object is created to manage the customer pickup process.
* **`Task`**: This is an *action* you send. To change a shipment's state (e.g., to fulfill it), you must **execute a named task** on it, like `"Fulfill"`. This is a key Kibo pattern.
### Key Kibo Patterns You'll See Everywhere
**Task-Based Workflow:** This is the most important pattern in fulfillment. **You cannot directly modify a shipment's state**. You must use the "Fulfill" task to move a shipment from `Ready` to `Fulfilled`. The request to execute a task looks like this:
```json theme={null}
// Actual request schema for the performShipmentTask endpoint
// POST /api/commerce/fulfillment/shipments/{shipmentNumber}/tasks
{
"_embedded": {
"tasks": [
{
"name": "Accept Shipment",
"subject": "",
"inputs": [
{
"name": "shipmentAccepted",
"type": "BOOLEAN"
}
],
"active": false,
"completed": true,
"completedDate": "2022-01-18T15:10:30.908Z",
"_links": {}
},
{
"name": "Validate Items In Stock",
"subject": "",
"inputs": [
{
"name": "stockLevel",
"type": "STRING"
}
],
"active": false,
"completed": true,
"completedDate": "2022-01-18T15:10:31.269Z",
"_links": {}
},
{
"name": "Print Packing Slip",
"subject": "",
"inputs": [
{
"name": "back",
"type": "BOOLEAN"
}
],
"active": false,
"completed": true,
"completedDate": "2022-01-18T15:10:31.631Z",
"_links": {}
},
{
"name": "Prepare for Shipment",
"subject": "",
"inputs": [
{
"name": "canceled",
"type": "BOOLEAN"
},
{
"name": "back",
"type": "BOOLEAN"
}
],
"active": false,
"completed": true,
"completedDate": "2023-05-30T19:24:25.104Z",
"_links": {}
}
]
},
"_links": {
"self": {
"href": "https://t31271.sandbox.mozu.com/api/commerce/shipments/123/tasks"
},
"shipment": {
"href": "https://t31271.sandbox.mozu.com/api/commerce/shipments/123"
}
}
}
```
**Error Handling Approach:** If an API call fails, the SDK throws a structured error. A common error is a `VALIDATION_ERROR` if you try to execute a task that isn't valid in the shipment's current `workflowState`.
**API Documentation Reference:** Find complete specs under the "Fulfillment" section at: `/api-overviews/openapi_fulfillment_overview`
***
### Common Shipment Workflows
Kibo developers typically work with Shipments in these scenarios:
1. **Backend Integration**: A Warehouse Management System (WMS) uses the API to get new shipments, and then notifies Kibo as they are packed and shipped.
2. **In-Store Operations**: Building a simple tablet application for store associates to manage BOPIS orders, marking them ready for pickup and then as collected.
3. **Customer Service Tools**: A custom UI for support agents to cancel or reassign shipments when a customer calls with an issue.
***
***
## SDK Fulfillment Workflows
The following examples use the **Task-Based Pattern** to move shipments through their lifecycle, which is the correct and auditable way to manage shipment state in Kibo.
### SDK Setup
All examples rely on a base `Configuration` and `ShipmentApi` client instance.
```typescript theme={null}
// Essential imports for Fulfillment operations.
import { Configuration } from "@kibocommerce/rest-sdk";
import { ShipmentApi, PickupApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
import { Task, Pickup, PickupItem } from "@kibocommerce/rest-sdk/models/Fulfillment";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
const shipmentApi = new ShipmentApi(configuration);
```
***
### 1. Ship-to-Home (STH) Fulfillment Workflow
A standard STH fulfillment involves a series of tasks.
| Step | Task Name / Action | Endpoint Type | Required Body Fields |
| :-------------------------- | :------------------------ | :--------------- | :-------------------------------------------- |
| **1. Accept Shipment** | `Accept Shipment` | Task Completion | `shipmentAccepted: true` |
| **2. Validate Stock** | `Validate Items In Stock` | Task Completion | `stockLevel: "IN_STOCK"` or `"PARTIAL_STOCK"` |
| **3. Print Packing Slip** | `Print Packing Slip` | Task Completion | Empty `{}` |
| **4. Add Tracking** | *None* (Direct Call) | Edit Package | `trackingNumbers` |
| **5. Prepare for Shipment** | `Prepare for Shipment` | Task Completion | `back: false`, `canceled: false` |
| **6. Mark As Fulfilled** | *None* (Direct Call) | PUT `/fulfilled` | None (Optional Manual Step) |
```typescript theme={null}
async function processShipToHome(shipmentNumber: number, trackingNumber: string) {
console.log(`Processing STH for Shipment #${shipmentNumber}`);
try {
// Step 1: Accept Shipment
let taskBodyAccept = { "taskBody": { "shipmentAccepted": true }, "handleOption": {} } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Accept Shipment', taskCompleteDto: taskBodyAccept });
console.log(" Step 1: Accepted.");
// Step 2: Validate Stock (assuming IN_STOCK for success case)
let taskBodyValidate = { "taskBody": { "stockLevel": "IN_STOCK" }, "handleOption": {} } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Validate Items In Stock', taskCompleteDto: taskBodyValidate });
console.log(" Step 2: Stock validated (IN_STOCK).");
// Step 3: Print Packing Slip
let taskBodyPrint = {}; // Empty body
await shipmentApi.execute({ shipmentNumber, taskName: 'Print Packing Slip', taskCompleteDto: taskBodyPrint });
console.log(" Step 3: Pick List Printed.");
// Step 5: Prepare for Shipment (Marks it as fulfilled)
let taskBodyPrepare = { "taskBody": { "back": false, "canceled": false } } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Prepare for Shipment', taskCompleteDto: taskBodyPrepare });
console.log(" Step 5: Prepared for Shipment (Now Fulfilled).");
console.log("STH Fulfillment Complete.");
} catch (error: any) {
console.error("STH Fulfillment API Error:", JSON.stringify(error, null, 2));
}
}
```
***
### 2. Buy Online, Pick Up in Store (BOPIS) Fulfillment Workflow
BOPIS fulfillment follows a flow for in-store pickup.
| Step | Task Name / Action | Endpoint Type | Required Body Fields |
| :------------------------- | :------------------------ | :--------------- | :-------------------------------------------- |
| **1. Accept Shipment** | `Accept Shipment` | Task Completion | `shipmentAccepted: true` |
| **2. Print Pick List** | `Print Pick List` | Task Completion | Empty `{}` |
| **3. Validate Stock** | `Validate Items In Stock` | Task Completion | `stockLevel: "IN_STOCK"` or `"PARTIAL_STOCK"` |
| **4. Provide to Customer** | `Customer Pickup` | Task Completion | `customerAccepted: true` |
| **5. Mark As Fulfilled** | *None* (Direct Call) | PUT `/fulfilled` | None (Optional Manual Step) |
```typescript theme={null}
async function processBopisFulfillment(shipmentNumber: number) {
console.log(`Processing BOPIS for Shipment #${shipmentNumber}`);
try {
// Step 1: Accept Shipment
let taskBodyAccept = { "taskBody": { "shipmentAccepted": true }, "handleOption": {} } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Accept Shipment', taskCompleteDto: taskBodyAccept });
console.log(" Step 1: Accepted.");
// Step 2: Print Pick List
let taskBodyPrint = {};
await shipmentApi.execute({ shipmentNumber, taskName: 'Print Pick List', taskCompleteDto: taskBodyPrint });
console.log(" Step 2: Pick List Printed.");
// Step 3: Validate Stock
let taskBodyValidate = { "taskBody": { "stockLevel": "IN_STOCK" }, "handleOption": {} } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Validate Items In Stock', taskCompleteDto: taskBodyValidate });
console.log(" Step 3: Stock validated (IN_STOCK).");
// Step 4: Provide to Customer (Customer Pickup task)
let taskBodyPickup = { "taskBody": { "customerAccepted": true } } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Customer Pickup', taskCompleteDto: taskBodyPickup });
console.log(" Step 4: Provided to Customer. Shipment should now be Fulfilled.");
console.log("BOPIS Fulfillment Complete.");
} catch (error: any) {
console.error("BOPIS Fulfillment API Error:", JSON.stringify(error, null, 2));
}
}
```
***
### 3. Transfer Fulfillment Workflow
Transfer shipments move inventory between locations to fulfill an order.
| Step | Task Name / Action | Endpoint Type | Required Body Fields |
| :-------------------------------- | :--------------------------- | :-------------- | :-------------------------------------------- |
| **1. Validate Stock** | `Validate Items In Stock` | Task Completion | `stockLevel: "IN_STOCK"` or `"PARTIAL_STOCK"` |
| **2. Print Packing Slip** | `Print Packing Slip` | Task Completion | Empty `{}` |
| **3. Add Tracking** | *None* (Direct Call) | Edit Package | `trackingNumbers` |
| **4. Prepare for Shipment** | `Prepare for Shipment` | Task Completion | `back: false`, `canceled: false` |
| **5. Validate Incoming Transfer** | `Validate Incoming Transfer` | Task Completion | `stockLevel: "IN_STOCK"` or `"PARTIAL_STOCK"` |
```typescript theme={null}
async function processTransferFulfillment(shipmentNumber: number) {
console.log(`Processing Transfer for Shipment #${shipmentNumber}`);
try {
// Step 1: Validate Stock at Origin Location
let taskBodyValidateOrigin = { "taskBody": { "stockLevel": "IN_STOCK" }, "handleOption": {} } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Validate Items In Stock', taskCompleteDto: taskBodyValidateOrigin });
console.log(" Step 1: Origin Stock validated (IN_STOCK).");
// Step 2: Print Packing Slip
let taskBodyPrint = {};
await shipmentApi.execute({ shipmentNumber, taskName: 'Print Packing Slip', taskCompleteDto: taskBodyPrint });
console.log(" Step 2: Pick List Printed.");
// Step 4: Prepare for Shipment (Marks it as Fulfilled/In Transit)
let taskBodyPrepare = { "taskBody": { "back": false, "canceled": false } } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Prepare for Shipment', taskCompleteDto: taskBodyPrepare });
console.log(" Step 4: Prepared for Shipment (In Transit).");
// Step 5: Validate Incoming Transfer at Destination Location
let taskBodyValidateIncoming = { "taskBody": { "stockLevel": "IN_STOCK" } } as any;
await shipmentApi.execute({ shipmentNumber, taskName: 'Validate Incoming Transfer', taskCompleteDto: taskBodyValidateIncoming });
console.log(" Step 5: Incoming Transfer validated (IN_STOCK).");
console.log("Transfer Fulfillment Complete.");
} catch (error: any) {
console.error("Transfer Fulfillment API Error:", JSON.stringify(error, null, 2));
}
}
```
***
### Additional Common Operations (Task-Based)
These examples align with Kibo's use of either the `execute` task method or direct API actions for state changes.
#### Example 1: Get a Shipment's Details
```typescript theme={null}
async function getShipmentDetails(shipmentNumber: number) {
console.log(`Fetching details for Shipment #${shipmentNumber}`);
try {
const shipment = await shipmentApi.getShipment({ shipmentNumber: shipmentNumber });
console.log("Success: Found shipment.");
console.log(" Current State:", shipment.workflowState);
console.log(" Fulfillment Location:", shipment.locationCode);
return shipment;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
```
#### Example 2: Reassign a Shipment
Reassigning a shipment is a direct action to transfer the fulfillment responsibility.
```typescript theme={null}
async function reassignShipment(shipmentNumber: number, newLocationCode: string) {
console.log(`Reassigning Shipment #${shipmentNumber} to ${newLocationCode}`);
try {
// This is a direct action call
const reassignResult = await shipmentApi.reassignShipment({
shipmentNumber: shipmentNumber,
reassignShipmentRequestDto: {
fulfillmentLocationCode: newLocationCode
}
});
const newShipmentNumber = reassignResult.childShipmentNumbers?.[0] || 'N/A';
console.log(`Success: Original shipment reassigned. New shipment created: ${newShipmentNumber}`);
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
```
#### Example 3: Cancel an Item from a Shipment
Canceling items uses a specific direct API call (`/canceledItems`).
```typescript theme={null}
async function cancelItemFromShipment(shipmentNumber: number, lineIdToCancel: number, quantityToCancel: number) {
console.log(`Canceling ${quantityToCancel} item(s) from Shipment #${shipmentNumber}`);
try {
// Using the SDK's direct method for canceled items (PUT /commerce/shipments/{shipmentNumber}/canceledItems)
const canceledShipment = await shipmentApi.cancelItems({
shipmentNumber: shipmentNumber,
canceledItemsDto: {
items: [
{
lineId: lineIdToCancel,
quantity: quantityToCancel,
reason: { reasonCode: "Customer request" }
},
],
}
});
console.log("Success: The item(s) have been canceled from the shipment. New state:", canceledShipment.workflowState);
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
```
***
***
## Troubleshooting Your Fulfillment Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string;
errorCode: string; // e.g., "VALIDATION_ERROR"
correlationId: string;
}
}
```
**Common Error Codes for Shipments:**
* `ITEM_NOT_FOUND`: The `shipmentNumber` or `orderId` you provided does not exist.
* `VALIDATION_ERROR`: This means you tried to do something that violates the shipment's current state.
* Example: Trying to execute the `Fulfill` task on a shipment not in the `Ready` state.
* `TASK_NOT_FOUND`: The `name` provided in your `Task` object is not a valid task (e.g., misspelled).
### Common Development Issues
**Issue 1:** My shipment is "stuck" and I can't update it.
* **Why it happens:** The shipment object is largely read-only; its state is controlled by the **task-based workflow**. Developers mistakenly try to `PUT` an update to the shipment object to change its status.
* **How to fix it:** You must use the `performShipmentTask` (or `execute`) endpoint for all state changes. Before trying to change a shipment, ask "What *task* do I need to execute?"
**Issue 2:** The order status is still "Awaiting Shipment" even after I fulfilled one of its shipments.
* **Why it happens:** An order's status is an aggregate of all its shipments. The order will not move to a `Completed` status until **all** of its constituent shipments have been fulfilled (or canceled).
* **How to fix it:** Ensure your fulfillment process handles all shipments associated with the order.
***
# Storefront Catalog API
Source: https://docs.kibocommerce.com/developer-guides/storefront-catalog
Customer-facing product display, search, and navigation APIs
# Kibo Storefront Catalog API Developer Guide
Understand catalog architecture and concepts
## Understanding Storefront Catalog in Kibo
The Kibo Storefront Catalog API is your primary tool for building customer-facing experiences. Unlike the Catalog Admin API, which is for managing product data, the **Storefront API is optimized for speed, security, and displaying product information to shoppers**. It's designed to be called directly from a browser or a front-end application. Kibo's philosophy here is to provide a performant, read-only view of your catalog that respects all merchandizing rules, such as active products, sale prices, and inventory visibility, without exposing sensitive administrative data.
***
## How This Domain Fits Into Kibo
The Storefront Catalog API is the bridge between your back-end product data and your live website. It's the engine that powers key e-commerce experiences:
* **Search**: When a shopper uses the search bar, the Storefront API's search endpoints are used to find relevant products.
* **Navigation**: When a shopper clicks on a category link, the Storefront API fetches the category details and the products within it.
* **Product Detail Pages (PDP)**: Viewing a specific product involves calling the Storefront API to get its details, including images, price, and options.
* **Cart & Checkout**: Before a product is added to the cart, the Storefront API is often used to validate its price and availability.
***
## Prerequisites
* Kibo Application Key (public key, safe for front-end use)
* Node.js 16+ with TypeScript
* Familiarity with REST APIs and front-end development concepts
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures storefront-facing catalog data (based on official API specs)
* The key patterns Kibo uses across all Storefront Catalog APIs (verified from apidocs.kibocommerce.com)
* Common workflows for building a storefront experience, like searching and navigation
* How to avoid the most common beginner mistakes
* How to effectively use Kibo's powerful search and filtering capabilities
***
## Kibo Storefront Catalog Fundamentals
### How Kibo Organizes Storefront Data
The Storefront API presents a curated version of your catalog data. A `Product` object from this API will include shopper-centric information like its `priceRange`, `productImages`, and `options`, but will omit internal data like cost. It also returns a `productCode` which is the key identifier used to add an item to the cart.
### Key Kibo Patterns You'll See Everywhere
**Authentication Pattern:**
Storefront APIs use a simpler authentication method. You only need your public **Application Key**, which is passed in the `x-vol-app-claims` header. The Kibo SDK handles this header for you when you create your `Configuration` object, but it's important to know you're not using a shared secret on the front end.
**Request/Response Structure:**
Storefront API responses for product collections (`ProductSearchResult`) include not only the products (`items`) but also useful metadata for building a UI, such as `facets`, `totalCount`, and `pageSize`.
**Error Handling Approach:**
If a shopper tries to access a disabled product or a non-existent category, the API will return a standard `404 Not Found` error. The SDK will throw an error containing the response details.
**Pagination and Filtering:**
Pagination is important for storefront performance. You'll use `startIndex` and `pageSize` to load products on category and search pages. Filtering on the storefront is often done through **facets**, which are dynamically returned by the search API.
**API Documentation Reference:**
Throughout this guide, we'll reference specific endpoints. Find complete specs at:
`/api-overviews/openapi_catalog_storefront_overview`
***
### Common Storefront Catalog Workflows
1. **Building Navigation**: Fetching the category tree to create menus and navigation bars.
2. **Displaying Product Grids**: Getting a list of products for a specific category or search query.
3. **Powering Site Search**: Using the search endpoint with various parameters to handle user queries, filtering, and sorting.
Let's explore each pattern step by step.
***
## Getting a List of Products: The Kibo Way
### When You Need This
This is one of the most common operations. You need it whenever you want to display a grid of products, such as on a category page, a search results page, or a "New Arrivals" promotional page.
***
### API Documentation Reference
* **Endpoint:** `GET /api/commerce/catalog/storefront/products/`
* **Method:** `GET`
* **API Docs:** [`/api-reference/storefrontproducts/get-products`](/api-reference/storefrontproducts/get-products)
***
### Understanding the Kibo Approach
Kibo's `storefrontGetProducts` endpoint is a powerful, multi-purpose tool. It's not just for fetching all products; it's designed to be filtered and sorted to meet various storefront needs. The key Kibo pattern here is the use of the `filter` parameter. Instead of having separate endpoints for "products in a category" vs. "products by brand," you use one endpoint and apply different filters. For example, `filter=categoryId eq 123` gets products for a specific category.
***
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our storefront API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Storefront Products API.
// 3. **Parameter Preparation**: Define the filter, page size, and other parameters for our query.
// 4. **API Call**: Use the client to call the `storefrontGetProducts` method.
```
***
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Storefront Catalog operations.
// We import the Configuration class and the specific API client we need.
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductSearchApi } from "@kibocommerce/rest-sdk/clients/CatalogStorefront/apis/ProductSearchApi.js";
// Configuration setup for storefront. Note the absence of a sharedSecret.
// Your Application Key (also known as App ID) is used instead.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST || "https://home.mozu.com",
});
```
**Step 2: Understanding the Data Flow**
The parameters for this request, such as `filter` and `pageSize`, are passed as arguments to the SDK method. The SDK constructs the final URL with these query parameters. The API responds with a `ProductSearchResult` object, which contains an `items` array of `Product` objects and pagination details.
**Step 3: The Core Implementation**
```ts theme={null}
// This example fetches the first 12 products from a specific category (ID: 4).
async function getCategoryProducts(categoryId: number) {
const productSearchClient = new ProductSearchApi(configuration);
try {
console.log(`Fetching first 12 products for category ID: ${categoryId}...`);
// storefrontSearch lets you query and filter product results
const result = await productSearchClient.storefrontSearch({
filter: `categoryId eq ${categoryId}`,
pageSize: 12,
startIndex: 0,
});
console.log(`Fetched ${result.items?.length || 0} products.`);
console.log(`Total products available: ${result.totalCount}`);
// Display product names
result.items?.forEach((p, i) => {
console.log(`${i + 1}. ${p.content?.productName}`);
});
return result;
} catch (error) {
console.error("API Error:", JSON.stringify(error, null, 2));
throw error;
}
}
// Step 3: Execute
getCategoryProducts(2);
```
***
### What Just Happened? (Code Explanation)
* The **setup phase** created a `Configuration` object using the public `appKey`. This is an important security distinction from the admin APIs.
* The **API call** was made using an instance of the storefront `ProductsApi`. We passed a configuration object to its `storefrontGetProducts` method containing a `filter` string. This demonstrates the Kibo pattern of using a single powerful endpoint for multiple use cases.
* The **response handling** shows how to access both the `items` array (the products themselves) and the `totalCount`, which is essential for building pagination controls in a UI.
***
### Common Beginner Mistakes
**Mistake 1:** Using admin credentials on the storefront.
```ts theme={null}
// Wrong - Never expose your clientId and sharedSecret in a front-end application.
const config = new Configuration({ clientId: '...', sharedSecret: '...' });
// Correct - Use your public appKey for all storefront API calls.
const config = new Configuration({ appKey: '...' });
```
**Mistake 2:** Not handling pagination.
```ts theme={null}
// Wrong - This only gets the first page of results (the default pageSize).
// If there are more products, the shopper will never see them.
const result = await client.storefrontGetProducts({ filter: 'categoryId eq 4' });
// Correct - Always use pageSize and startIndex to control which products you are displaying.
const result = await client.storefrontGetProducts({
filter: 'categoryId eq 4',
pageSize: 24, // The number of items you want per page
startIndex: 48 // The starting index (e.g., for page 3, startIndex would be 48)
});
```
***
### How This Connects to Other Kibo Operations
* **Site Search**: The `storefrontGetProducts` endpoint is also the engine behind search. You simply change the `filter` parameter to a `query` parameter.
* **Cart**: Once a user selects a product from the list you fetched, you'll use its `productCode` to add it to the cart using the Cart API.
***
## Advanced Storefront Patterns
### Pattern 1: Implementing Faceted Search
**Business Scenario:**
A shopper searches for "hiking boots." You need to display the search results and also show a list of filters (facets) like "Brand," "Color," and "Price" so the shopper can narrow down the results. When the shopper checks the "Waterproof" box, the search results must update accordingly.
**Kibo's Architecture Consideration:**
Kibo's search is designed to be efficient and powerful. The key is that the same API call that gets the product results **also returns the available facets**. You don't need to make a separate API call to figure out what filters to show. You simply include the `facet` parameter in your request, and the response will contain a `facets` array, perfectly structured for building a filtering UI.
**API Endpoints Used:**
* `GET /api/commerce/catalog/storefront/products/`
* **Full API Reference:** [`/api-reference/storefrontproducts/get-products`](/api-reference/storefrontproducts/get-products)
**Implementation Strategy:**
1. **Initial Search**: Make a `storefrontGetProducts` call with the user's `query` and a list of fields you want to `facet` on (e.g., `brand`, `color`).
2. **Render UI**: Use the `items` from the response to display the products. Use the `facets` array from the same response to build the filtering sidebar.
3. **Refine Search**: When a user selects a facet value (e.g., clicks the "Brand: Kibo Hikers" checkbox), you modify the `filter` parameter in your next API call to include this selection (e.g., `filter=brand eq "Kibo Hikers"`) and re-run the search.
```typescript theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductsApi, ProductSearchResult } from "@kibocommerce/rest-sdk/clients/Commerce";
// Use the same storefront configuration from the previous example
const configuration = new Configuration({ /* ... your credentials ... */ });
async function performFacetedSearch(query: string, categoryCode?: string) {
const productSearchClient = new ProductSearchApi(configuration);
// Define which fields to use as facets
const facetFields = "categoryCode"; // use correct field names defined in catalog
// Build a filter dynamically
let facetTemplate = "";
if (categoryCode) {
facetTemplate = `categoryCode:"${categoryCode}"`;
}
try {
console.log(`Searching for "${query}" with filter "${facetTemplate || "none"}"...`);
// The core search call
const result = await productSearchClient.storefrontSearch({
query,
facet: facetFields,
facetTemplate,
pageSize: 12,
startIndex: 0,
});
console.log(`Found ${result.totalCount} products.`);
console.log("Available Facets:");
console.log(JSON.stringify(result.facets, null, 2));
// Show a few sample product names
result.items?.slice(0, 5).forEach((item, i) => {
console.log(`${i + 1}. ${item.content?.productName}`);
});
return result;
} catch (error) {
console.error("Search Error:", JSON.stringify(error, null, 2));
throw error;
}
}
// Step 3: Execute
performFacetedSearch("", "11111");
```
***
### Multiple Real-World Examples
**Example 1: Get the Storefront Category Tree**
This is essential for building your site's main navigation menu.
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { CategoriesApi, CategoryCollection } from "@kibocommerce/rest-sdk/clients/CatalogAdministration";
async function getNavigationMenu() {
const categoryClient = new CategoriesApi(configuration);
try {
console.log("Fetching category tree...");
const categoryTree = await categoryClient.storefrontGetCategoryTree({
includeAttributes: false, // optional
});
console.log(`Found ${categoryTree.items?.length || 0} top-level categories.`);
console.log(JSON.stringify(categoryTree.items, null, 2));
} catch (error) {
console.error("Error fetching category tree:", error);
}
}
getNavigationMenu();
```
**Example 2: Site Search with Sorting**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductsApi, ProductSearchResult } from "@kibocommerce/rest-sdk/clients/Commerce";
async function searchAndSort(query: string, sortBy: string = "price asc") {
const searchClient = new ProductSearchApi(configuration);
try {
console.log(`Searching for "${query}" sorted by "${sortBy}"...`);
const searchResult = await searchClient.storefrontSearch({
query,
sortBy,
pageSize: 12,
});
console.log(`Found ${searchResult.totalCount} results.\n`);
console.log(
searchResult.items?.map((p) => ({
code: p.productCode,
name: p.content?.productName,
price: p.price?.price,
}))
);
return searchResult;
} catch (error) {
console.error("Search Error:", JSON.stringify(error, null, 2));
throw error;
}
}
searchAndSort("Apple"); // Default sort: price asc
```
**Example 3: Powering a Search Autocomplete Feature**
```ts theme={null}
import { Configuration } from "@kibocommerce/rest-sdk";
import { ProductSearchApi, SearchSuggestionResult } from "@kibocommerce/rest-sdk/clients/Commerce";
const productSearchApi = new ProductSearchApi(configuration);
export async function searchAndSort(query: string) {
try {
const response = await productSearchApi.storefrontSuggest({
query, // ← dynamic input
groups: "products,categories",
pageSize: 10,
});
console.log("Search Suggestions:", response);
return response;
} catch (err) {
console.error("Error fetching suggestions:", err);
}
}
searchAndSort("Samsung");
```
***
## Integrating Storefront Catalog with Other Kibo Domains
### Storefront Catalog + Cart Integration
The entire shopping journey starts with the catalog. A shopper finds a product using the `ProductsApi`, and then you use that product's `productCode` and selected `options` to add it to their cart using the `CartApi`.
### Storefront Catalog + Customer Data Integration
When a logged-in shopper views a product, you can use their customer ID to call the Customer API to see if that product is on their wishlist, enabling you to render a "Saved to Wishlist" state on the product page.
***
## Troubleshooting Your Storefront Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API
interface KiboApiError {
message: string; // Error description
correlationId: string; // For support tracking
// ... other properties may be present
}
```
**Common Error Codes for Storefront Catalog:**
* **404 Not Found**: The most common error. This means the `productCode` or `categoryId` you requested does not exist, is not active, or is not part of the current site's catalog.
* **400 Bad Request**: Your `filter` or `sortBy` parameter has a syntax error. Check the API documentation for the correct syntax.
* **401 Unauthorized**: Your `appKey` is invalid or missing from the header.
***
### Common Development Issues
**Issue 1:** My products are showing the wrong price (or no price).
* **Why it happens:** The Storefront API respects all pricing rules. A product might not have a price if no price list is configured for the current site or if the customer doesn't belong to a group with a special price list.
* **How to fix it:** In the Kibo Admin, verify that your product has a price in a price list that is active and assigned to your storefront's customer segment.
* **API Reference:** The pricing information is returned directly on the `Product` object from the Storefront API.
**Issue 2:** My search for a specific term returns no results, but I know the product exists.
* **Why it happens:** Kibo's search indexing takes a few moments to update after a product is created or changed. Additionally, the fields you are searching against must be configured as searchable in the catalog settings.
* **How to fix it:** Wait a few minutes after creating a product. In Kibo Admin, go to **System > Settings > Search** and ensure the attributes you want to search by (e.g., product name, description) are enabled in the search tuning settings.
* **API Reference:** [`/api-reference/storefrontproducts/get-products`](/api-reference/storefrontproducts/get-products)
***
### Debugging Checklist
When your Storefront Catalog implementation isn't working:
1. Verify your `Configuration` object is using the public `appKey` and **not** your `sharedSecret`.
2. Check the browser's network tab to inspect the exact URL being called. Ensure the `filter` and `query` parameters are correctly formatted.
3. Make sure the product or category you are requesting is **Active** and assigned to the **Catalog** of the `siteId` you are using.
4. For search issues, check your site's search settings in Kibo Admin to ensure the relevant attributes are indexed.
5. Use the `correlationId` from any error message when contacting Kibo support.
# Subscription API
Source: https://docs.kibocommerce.com/developer-guides/subscription
Recurring orders and subscription lifecycle management
# Kibo Subscription API Developer Guide
Understand subscription architecture and concepts
Manage product subscriptions in the Admin UI
View and manage continuity orders
Understand subscription architecture and concepts
Manage product subscriptions in the Admin UI
View and manage continuity orders
## Understanding Subscription in Kibo
In Kibo, a **Subscription** is not just a product type; it's a standalone commerce entity that represents a customer's recurring purchase agreement. This is an important architectural difference from many platforms. Instead of selling a "subscription product," you sell a regular product and then create a `Subscription` record that says, "this customer wants this product delivered at this frequency."
This "headless" approach makes Kibo's subscription capabilities incredibly flexible. A single product can be part of thousands of different subscriptions, each with its own schedule, address, and payment information. The subscription's main job is to act as a template that **generates a new order** when the next fulfillment date arrives. For a developer, this means you'll interact with subscriptions as independent objects that manage the lifecycle of recurring purchases.
***
## How This Domain Fits Into Kibo
The Subscription domain is deeply integrated with the core commerce lifecycle, acting as an automated order-creation engine.
* **Customer**: A subscription is always owned by a `CustomerAccount`. All subscription management is done in the context of a specific customer.
* **Catalog**: Subscriptions contain one or more products from your catalog.
* **Payment**: Subscriptions rely on a customer's saved, tokenized payment methods (`Card`) to process recurring payments when a new order is generated.
* **Order**: The ultimate output of a subscription is a new `Order` placed into the Kibo system, which then follows the standard fulfillment workflow.
***
## Prerequisites
* Kibo API credentials with Commerce permissions.
* A customer account with a saved payment method for testing.
* Node.js 16+ with TypeScript.
* Familiarity with REST APIs and `async/await`.
***
## What You'll Learn
After completing this guide, you'll understand:
* How Kibo structures **Subscription** data and its lifecycle (based on official API specs).
* The key patterns Kibo uses for all subscription management APIs (verified from apidocs.kibocommerce.com).
* Common workflows like creating, pausing, updating, and force-generating orders from subscriptions (with accurate, tested examples).
* How to avoid the most common beginner mistakes.
* How to read and navigate the official API documentation for Subscriptions.
***
***
## Kibo Subscription Fundamentals
### How Kibo Organizes Subscription Data
Kibo's Subscription data is centered around the `Subscription` object, which acts as the master record for a recurring purchase.
* **`Subscription`**: The main object.
* `id`: The unique identifier for the subscription.
* `customerAccountId`: The ID of the customer who owns the subscription.
* `status`: The current state of the subscription. The most common values are `ACTIVE`, `PAUSED`, and `CANCELLED`.
* `frequency`: An object defining the delivery schedule (e.g., `{ "value": 2, "unit": "Week" }`). Valid units are `Day`, `Week`, `Month`, `Year`.
* `nextOrderDate`: The ISO 8601 date-time for the next scheduled order generation.
* `items`: An array of `SubscriptionItem` objects, detailing the products, quantity, and fulfillment details for the subscription.
### Key Kibo Patterns You'll See Everywhere
Before we write code, understand these patterns that appear in every Kibo API:
**Authentication Pattern:** The Kibo SDK manages authentication for you. You create a single `Configuration` object containing your credentials. This object is then passed to the constructor of the `SubscriptionApi` client, which will handle the OAuth 2.0 token exchange for every API call.
**Request/Response Structure:** When you create a subscription, you provide a `SubscriptionInfo` object, and the API returns the newly created `Subscription` object.
```json theme={null}
// Actual response schema from getting a Subscription
{
"id": "123ab45c678d90ef12ab34cd",
"siteId": 21345,
"tenantId": 12345,
"customerAccountId": 1001,
"status": "ACTIVE",
"frequency": {
"value": 1,
"unit": "Month"
},
"nextOrderDate": "2025-11-14T12:00:00Z",
"items": [
{
"product": {
"productCode": "COFFEE-BLEND-12OZ",
"name": "Morning Roast Coffee"
},
"quantity": 2
}
]
}
```
**Error Handling Approach:** If an API call fails, the SDK throws a structured error. For subscriptions, a common error is `VALIDATION_ERROR` if you try to create a subscription with an invalid frequency unit or for a product that is not configured to be subscribable.
**API Documentation Reference:** Throughout this guide, we'll reference specific endpoints. Find complete specs under the "Commerce" section at: `/developer-guides/subscription`
***
### Common Subscription Workflows
Kibo developers typically work with Subscriptions in these scenarios:
1. **Subscription Creation**: A customer chooses a "Subscribe & Save" option during checkout, and you create a new subscription record for them.
2. **Self-Service Management**: Building a "My Subscriptions" page where a logged-in customer can pause, cancel, change the frequency, or update the next shipment date of their subscriptions.
3. **Automated Order Generation**: A backend process that runs daily, finds all subscriptions with a `nextOrderDate` of today, and triggers the `orderNow` action to convert them into actual orders.
Let's explore each pattern step by step.
***
***
## Creating a Subscription: The Kibo Way
### When You Need This
This is the starting point for any recurring revenue flow. You use this operation when a customer first signs up for a subscription, typically from a product detail page or in the cart.
### API Documentation Reference
* **Endpoint:** `POST /api/commerce/subscriptions/`
* **Method:** `POST`
* **SDK Method:** `createSubscription`
* **API Docs:** [Creates Subscription](/api-reference/subscription/creates-subscription)
### Understanding the Kibo Approach
Kibo's API for creating a subscription requires you to provide all the necessary information upfront in a `SubscriptionInfo` object. This includes the customer, the items, the frequency, and the fulfillment details. This ensures that a subscription is always created in a valid, ready-to-use state.
### Code Structure Walkthrough
```typescript theme={null}
// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the Subscription resource.
// 3. **Data Preparation**: Construct the 'SubscriptionInfo' request body according to the API schema.
// 4. **API Call**: Use the 'SubscriptionApi' client to call the 'createSubscription' method.
```
#### Step-by-Step Implementation
**Step 1: Setting Up the Foundation**
```ts theme={null}
// Essential imports for Subscription operations.
// The SDK client is found under the 'Commerce' group.
import { Configuration } from "@kibocommerce/rest-sdk";
import { SubscriptionApi } from "@kibocommerce/rest-sdk/clients/Commerce";
import { SubscriptionInfo } from "@kibocommerce/rest-sdk/models/Commerce";
// Configuration setup - this single object is reused for all API clients.
const configuration = new Configuration({
tenantId: process.env.KIBO_TENANT_ID,
siteId: process.env.KIBO_SITE_ID,
clientId: process.env.KIBO_CLIENT_ID,
sharedSecret: process.env.KIBO_SHARED_SECRET,
authHost: process.env.KIBO_AUTH_HOST,
});
```
**Step 2: The Core Implementation**
```ts theme={null}
// Complete working example that ACTUALLY WORKS with the Kibo API
// This function creates a new subscription for a given customer.
async function createNewSubscription(customerId: number) {
// 1. Instantiate a dedicated client for the Subscription API.
const subscriptionApi = new SubscriptionApi(configuration);
// 2. Prepare the request body.
// This must match the 'SubscriptionInfo' schema from the API docs.
const payload: SubscriptionInfo = {
customerAccountId: 1000,
email: "bobkibo@test.com",
nextOrderDate: "2024-04-03T16:26:42.270Z",
status": "Active",
isImport": false,
reactivationDate": "2025-03-03T16:26:42.270Z",
isTaxExempt: "false",
currencyCode: "USD",
frequency: {
value: 1,
unit: "Month", // Valid units: Day, Week, Month, Year
},
items: [
{
// You must provide enough product information to identify the exact SKU.
product: {
productCode: "COFFEE-BLEND-12OZ",
isTaxable: "false",
price: {
price: "100.00"
}
variationProductCode: "COFFEE-BLEND-12OZ-GROUND", // If it's a configurable product
},
quantity: 1,
fulfillmentMethod: "Ship"
},
],
// You also provide payment and shipping info for the first order.
fulfillmentInfo: {
fulfillmentContact:{
firstName: "Bob",
lastNameOrSurname: "Kibo",
phoneNumbers": {
home: "1231231234",
mobile: "",
work: ""
},
address: {
address1: "5909 Via Loma",
address2: "",
address3: "",
address4: "",
cityOrTown: "El Paso",
stateOrProvince: "TX",
postalOrZipCode: "79912",
countryCode: "US",
addressType: "Residential",
isValidated: false
}
},
shippingMethodCode: "flat-rate",
shippingMethodName: "Flat Rate"
},
payment: {
// This payment method ID should be a saved card on the customer's account.
paymentType: "CreditCard",
paymentWorkFlow: "Mozu",
status: "New",
isRecurring: "false",
amountRequested: 30,
billingInfo: {
payemntType: "CreditCard",
billingContact: {
email: "bobkibo@test.com",
firstName: "Bob",
lastNameOrSurname": "Kibo",
phoneNumbers": {
home: "1231231234",
mobile: "",
work: ""
},
address: {
address1: "5909 Via Loma",
address2: "",
address3: "",
address4: "",
cityOrTown: "El Paso",
stateOrProvince: "TX",
postalOrZipCode: "79912",
countryCode: "US",
addressType: "Residential",
isValidated: false
},
},
card: {
paymentServiceCardId: "",
isUsedRecurring: ""
isUsedRecurring": false,
nameOnCard": "Bob Smith",
isCardInfoSaved: false,
isTokenized: false,
paymentOrCardType": "VISA",
cardNumberPartOrMask": "************1111",
expireMonth": 1,
expireYear": 2025
}
}
}
};
console.log(`Attempting to create subscription for customer ID: ${customerId}`);
try {
const newSubscription = await subscriptionApi.createSubscription({
subscriptionInfo: payload,
});
console.log("Success: New subscription created with ID:", newSubscription.id);
return newSubscription;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage with a real Customer ID from your Kibo tenant
// createNewSubscription(1001);
```
### What Just Happened? (Code Explanation)
* The **setup phase** created the `Configuration` object.
* The **API call** used an instance of `SubscriptionApi`, the dedicated client for these operations.
* The **payload** was a detailed `SubscriptionInfo` object. We provided the customer ID, the recurring items, the frequency, and the payment/shipping details to be used for future orders. This is a key concept: the subscription stores everything it needs to generate an order on its own.
* The **response handling** uses a `try...catch` block. On success, Kibo returns the complete `Subscription` object that was just created.
### Common Beginner Mistakes
**Mistake 1:** Using an invalid `unit` for the frequency.
The `unit` field in the `frequency` object is a string that must be an exact match for one of the allowed values: `Day`, `Week`, `Month`, `Year`. Using `Months` or `monthly` will result in a `VALIDATION_ERROR`.
**Mistake 2:** Not providing valid payment and shipping contact IDs.
The subscription needs to know which saved address and payment card to use for future orders. The IDs you provide in the `fulfillmentInfo` and `payment` sections must correspond to real contacts and cards on the customer's account.
***
***
## Multiple Real-World Examples
Here are 5 complete, production-ready examples covering the most common `Subscription` management tasks.
### Example 1: Update a Subscription's Frequency and Next Order Date
This is a common self-service feature: allowing a customer to get their next order sooner or change their delivery schedule.
* **API Docs:** [Update Subscription](/api-reference/subscription/update-subscription)
```ts theme={null}
// ... imports and configuration setup ...
import { SubscriptionApi } from "@kibocommerce/rest-sdk/clients/Commerce";
import { Subscription } from "@kibocommerce/rest-sdk/models/Commerce";
async function updateSubscriptionSchedule(subscriptionId: string) {
const subscriptionApi = new SubscriptionApi(configuration);
console.log(`Updating schedule for subscription ID: ${subscriptionId}`);
try {
// 1. GET the latest version of the subscription object.
const currentSubscription = await subscriptionApi.getSubscription({ subscriptionId });
// 2. PREPARE the updated payload. You must send the full object back.
const updatedPayload: Subscription = {
...currentSubscription,
frequency: { value: 2, unit: "Week" }, // Change to every 2 weeks
nextOrderDate: "2025-10-21T12:00:00Z", // Push next order to next Tuesday
};
// 3. PUT the modified object back.
const updatedSubscription = await subscriptionApi.updateSubscription({
subscriptionId: subscriptionId,
subscription: updatedPayload,
});
console.log("Success: Subscription updated.");
console.log("New Frequency:", updatedSubscription.frequency);
console.log("New Next Order Date:", updatedSubscription.nextOrderDate);
return updatedSubscription;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// updateSubscriptionSchedule("123ab45c678d90ef12ab34cd");
```
### Example 2: Pause a Subscription
Temporarily stop a subscription without canceling it.
* **API Docs:** [Perform Subscription Action](/api-reference/subscription/perform-subscription-action)
```ts theme={null}
// ... imports and configuration setup ...
import { SubscriptionApi } from "@kibocommerce/rest-sdk/clients/Commerce";
import { SubscriptionStatus } from "@kibocommerce/rest-sdk/models/Commerce";
async function pauseSubscription(subscriptionId: string) {
const subscriptionApi = new SubscriptionApi(configuration);
console.log(`Pausing subscription ID: ${subscriptionId}`);
const payload: SubscriptionStatus = { status: "PAUSED" };
try {
const updatedSubscription = await subscriptionApi.updateSubscriptionStatus({
subscriptionId: subscriptionId,
subscriptionStatus: payload,
});
console.log(`Success: Subscription status is now: ${updatedSubscription.status}`);
return updatedSubscription;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// pauseSubscription("123ab45c678d90ef12ab34cd");
```
### Example 3: Resume or Cancel a Subscription
The same endpoint used to pause can also be used to resume or permanently cancel a subscription.
```ts theme={null}
// ... imports and configuration setup ...
import { SubscriptionApi } from "@kibocommerce/rest-sdk/clients/Commerce";
import { SubscriptionStatus, Subscription } from "@kibocommerce/rest-sdk/models/Commerce";
async function setSubscriptionStatus(subscriptionId: string, newStatus: "ACTIVE" | "CANCELLED"): Promise {
const subscriptionApi = new SubscriptionApi(configuration);
console.log(`Setting status of subscription ${subscriptionId} to: ${newStatus}`);
const payload: SubscriptionStatus = { status: newStatus };
try {
const updatedSubscription = await subscriptionApi.updateSubscriptionStatus({
subscriptionId: subscriptionId,
subscriptionStatus: payload,
});
console.log(`Success: Subscription status is now: ${updatedSubscription.status}`);
return updatedSubscription;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage to Resume:
// setSubscriptionStatus("123ab45c678d90ef12ab34cd", "ACTIVE");
// Usage to Cancel:
// setSubscriptionStatus("123ab45c678d90ef12ab34cd", "CANCELLED");
```
### Example 4: Force an Immediate Order ("Order Now")
This feature allows a customer to trigger their subscription shipment immediately instead of waiting for the `nextOrderDate`.
* **API Docs:** [Order Now](/api-reference/subscription/order-now)
```ts theme={null}
// ... imports and configuration setup ...
import { SubscriptionApi } from "@kibocommerce/rest-sdk/clients/Commerce";
async function triggerImmediateOrder(subscriptionId: string) {
const subscriptionApi = new SubscriptionApi(configuration);
console.log(`Triggering 'Order Now' for subscription ID: ${subscriptionId}`);
try {
// This action has no request body.
const newOrder = await subscriptionApi.orderNow({ subscriptionId: subscriptionId });
console.log(`Success: New Order created with ID: ${newOrder.id}`);
console.log(` The subscription's nextOrderDate has been automatically updated.`);
return newOrder;
} catch (error: any) {
console.error("API Error:", JSON.stringify(error, null, 2));
}
}
// Usage
// triggerImmediateOrder("123ab45c678d90ef12ab34cd");
```
***
***
## Troubleshooting Your Subscription Implementation
### Reading Kibo Error Messages
```typescript theme={null}
// Actual error structure from Kibo API documentation
interface KiboApiError {
body: {
message: string;
errorCode: string; // e.g., "VALIDATION_ERROR"
correlationId: string;
}
}
```
**Common Error Codes for Subscriptions:**
* `ITEM_NOT_FOUND`: The `subscriptionId`, `customerAccountId`, or a contact/card ID you provided does not exist.
* `VALIDATION_ERROR`: The request body is invalid. Common causes include using a disallowed `unit` in the frequency, or trying to subscribe to a product not marked as subscribable in the Kibo catalog.
* `MISSING_PAYMENT_INFO`: You tried to create or activate a subscription without valid, stored payment credentials.
### Common Development Issues
**Issue 1:** The `updateSubscription` call is deleting fields I didn't touch.
* **Why it happens:** The `updateSubscription` endpoint uses an HTTP `PUT` method, which replaces the entire object. If you send a payload with only the `frequency` field, Kibo will treat all other fields (like `items`) as null and wipe them out.
* **How to fix it:** You must follow the **Read-Modify-Write** pattern. First, `GET` the subscription. Then, modify the properties on that retrieved object in your code. Finally, `PUT` the entire, modified object back to the API.
* **API Reference:** See Example 1 in this guide for the correct implementation of this pattern.
# Action (After)
Source: https://docs.kibocommerce.com/pages/action-after
**Related API:** This extension modifies the [Perform Payment Action](/api-reference/order/perform-payment-action) operation.
This action occurs after a certain interaction is performed on a payment. It runs after both the `embedded.commerce.payments.action.before` and the `embedded.commerce.payments.performPaymentInteraction` actions. The main difference between these three actions is the methods each has access to and whether they occur before or after the payment interaction. The relevant payment interactions that this action responds to are:
* AuthAndCapture
* Authorize
* Capture
* Create
* Credit
* Decline
* RequestCheck
* Rollback
* Void
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.payments.action.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Payment
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**
This action corresponds to the microservice that performs payment actions.
## Get
### get.payment
Returns the payment transaction.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.payment();
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### get.paymentAction
Returns a primitive list of strings naming the available payment actions.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.paymentAction();
```
Response:
```
[
{}
]
```
## Exec
### exec.setActionAmount
Set a requested payment amount for the transaction.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------- |
| amount | number | The requested amount you want to set for the payment. |
Example:
```
context.exec.setActionAmount(37.00);
```
Response:
```
[
{}
]
```
Returns a payment action. For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setPaymentData
Set custom payment data (usually billing information associated with a billing service that might only send an auth token).
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------------- |
| key | string | Key used to identify the payment data. |
| value | object | Custom data originated by the billing service. |
Example:
```
context.exec.setPaymentData("paypal",existingPayment.billingInfo.data.paypal);
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removePaymentData
Remove custom payment data from a payment.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------- |
| key | string | Key used to identify the payment data. |
Example:
```
context.exec.removePaymentData("paypal");
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setActionPreAuthFlag
Enable pre-authorization for an order payment. Pre-authorization authorizes a small dollar amount (e.g. \$1) in order to check the authorization response for errors (incorrect CVV, etc.) before the full amount is authorized. This feature provides a cleaner method for authorizing large-value orders.
To enable this feature, contact your Kibo representative. At this moment, Cybersource is the only payment gateway that supports this feature.
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------ |
| isPreAuth | Boolean | Enables pre-authorization when true. |
Example:
```
context.exec.setActionPreAuthFlag(true);
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setBillingInfo
Set the billing info object for a payment.
| Parameter | Type | Description |
| ----------- | ------ | ---------------------------------------------------------------------------------------------- |
| billingInfo | object | The `billingInfo` object for the [payment resource](/api-overviews/openapi_commerce_overview). |
Example:
```
context.exec.setBillingInfo(billingInfo);
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Action (Before)
Source: https://docs.kibocommerce.com/pages/action-before
**Related API:** This extension modifies the [Perform Payment Action](/api-reference/order/perform-payment-action) operation.
This action occurs before a certain interaction is performed on a payment. It runs before both the `embedded.commerce.payments.performPaymentInteraction` and the `embedded.commerce.payments.action.after` actions. The main difference between these three actions is the methods each has access to and whether they occur before or after the payment interaction. The relevant payment interactions that this action responds to are:
* AuthAndCapture
* Authorize
* Capture
* Create
* Credit
* Decline
* RequestCheck
* Rollback
* Void
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.payments.action.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Payment
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that performs payment actions.
## Get
### get.payment
Returns the payment transaction.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.payment();
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### get.paymentAction
Returns a primitive list of strings naming the available payment actions.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.paymentAction();
```
Response:
```
[
{}
]
```
## Exec
### exec.setActionAmount
Set a requested payment amount for the transaction.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------- |
| amount | number | The requested amount you want to set for the payment. |
Example:
```
context.exec.setActionAmount(37.00);
```
Response:
```
[
{}
]
```
Returns a payment action. For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setPaymentData
Set custom payment data (usually billing information associated with a billing service that might only send an auth token).
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------------- |
| key | string | Key used to identify the payment data. |
| value | object | Custom data originated by the billing service. |
Example:
```
context.exec.setPaymentData("paypal",existingPayment.billingInfo.data.paypal);
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removePaymentData
Remove custom payment data from a payment.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------- |
| key | string | Key used to identify the payment data. |
Example:
```
context.exec.removePaymentData("paypal");
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setActionPreAuthFlag
Enable pre-authorization for an order payment. Pre-authorization authorizes a small dollar amount (e.g. \$1) in order to check the authorization response for errors (incorrect CVV, etc.) before the full amount is authorized. This feature provides a cleaner method for authorizing large-value orders.
To enable this feature, contact your Kibo representative. At this moment, Cybersource is the only payment gateway that supports this feature.
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------ |
| isPreAuth | Boolean | Enables pre-authorization when true. |
Example:
```
context.exec.setActionPreAuthFlag(true);
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setBillingInfo
Set the billing info object for a payment.
| Parameter | Type | Description |
| ----------- | ------ | -------------------------------------------------- |
| billingInfo | object | The `billingInfo` object for the payment resource. |
Example:
```
context.exec.setBillingInfo(billingInfo);
```
Response:
```
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Action Management JSON Editor
Source: https://docs.kibocommerce.com/pages/action-management-json-editor
The below image demonstrates how the Action Management JSON Editor empowers users to exert precise control over actions through JSON code.
Within Admin, the Action Management JSON Editor allows you to control actions using JSON code. With the Action Management JSON Editor you can:
* Enable or disable the functions bound to actions installed on the sandbox.
* Specify settings, such as timeout and exception behavior, for individual actions.
* Provide custom information to individual actions and to the application that contains the actions.
* Specify logging behaviors associated with actions.
To open the Action Management JSON Editor:
1. Log in to Dev Center.
2. View a sandbox.
3. In Admin, go to **System** > **Customization** > **API Extensions.**
## JSON Structure
With the Action Management JSON Editor, you specify which actions you have installed to a sandbox, the context each action applies to, and the settings an action uses in each context (i.e., the application key, the function you want to execute, and the custom configuration data you want to provide the action). You also specify the custom configuration data available to all actions in the application and the log level that actions use in the application.
The following code block and table demonstrate the options you can configure with the Action Management JSON Editor.
```
{
"actions": [
{
"actionId": "embedded.commerce.carts.deleteCart.before",
"contexts": [
{
"context": 21074,
"customFunctions": [
{
"applicationKey": "yourApplicationKey",
"functionId": "functionName",
"enabled": true,
"timeoutMilliseconds": 5000,
"exceptionBehavior": "fault",
"logLevel": "Info",
"configuration": {
"yourCustomField": "value"
}
}
...
]
}
...
]
}
...
],
"configurations": [
{
"applicationKey": "yourApplicationKey",
"configuration": {
"yourCustomField": "value"
}
}
...
],
"defaultLogLevel": "Info"
}
```
| Option | Description |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultLogLevel` | Specifies which types of application logs display in Dev Center, based on priority level. Possible values mirror Apache's log4net: `All`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`, and `Off`. When deploying an API Extensions application to production, set this value to `Error` to avoid performance penalties. |
| actions | An array of actions. |
| `actionId` | Identifies a specific action. This ID matches the naming conventions in the `assets/functions.json` file. |
| actions\[ contexts ] | The per-site settings that apply to an individual action. |
| `context` | (Optional) The siteId for the site you want to apply the nested settings to. You can omit this field if you want to apply the same settings to an action across all your sites. |
| actions\[ contexts\[ customFunctions ] ] | An array of custom functions tied to an action. Some actions can run only one function, but other functions can run multiple functions. |
| `applicationKey` | The application key of the API Extensions application. |
| `functionId` | The name of the custom function tied to the action, per the naming conventions set in the manifest files located in the `assets/src` directory. |
| `enabled` | (Optional) A Boolean that controls whether the function is enabled or disabled. The default is `true`. |
| `timeoutMilliseconds` | (Optional) The number of milliseconds the function is allowed to run before the platform terminates it. The default is `5000` milliseconds. The maximum allowed value is `25000` milliseconds — this is the platform's hard execution ceiling. Setting this to `25000` does not make a slow action faster; it only extends the window during which a slow action can block the storefront. For storefront HTTP actions on high-traffic pages, set this to the smallest value that accommodates the action's expected external call latency plus overhead, not the maximum. See [Calling External APIs Safely](/pages/programming-patterns#calling-external-apis-safely) for guidance on budgeting time across outbound calls. |
| `exceptionBehavior` | (Optional) The behavior to take when an unhandled error is encountered, either `fault` or `continue`. The default is `fault`.
`fault` propagates the error to the end-user request, which can return an error response to the shopper. `continue` swallows the error and lets the request proceed as if the action had not run. Use `continue` for non-critical enrichment actions where storefront availability is more important than extension correctness. Use `fault` for `before` actions where the extension output is required for the request to proceed correctly. |
| `logLevel` | (Optional) Specifies which types of function-specific logs display in Dev Center, based on priority level. Possible values mirror Apache's log4net: `All`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`, and `Off`. When deploying an API Extensions application to production, set this value to `Error` to avoid performance penalties. |
| actions\[ contexts\[ customFunctions\[ configuration ] ] ] | Custom function-level settings that you can create. If you create custom settings with the same names as custom settings created at the application level, these settings take precedence over the application-level configurations. |
| `yourCustomField` | Custom object data. |
| configurations | Custom settings that apply to all actions in the API Extensions application. |
| `applicationKey` | The application key of the API Extensions application. |
| configurations\[ configuration ] | Custom application-level settings that you can create. If you create custom settings with the same names as custom settings created at the function level, these settings are overwritten by the function-level configurations. |
| `yourCustomField` | Custom object data. |
## Verify Enabled Functions Exist in the Deployed Application
If an `actionId` is configured with `"enabled": true` and a `functionId` that does not exist as a named export in the deployed application package, the platform logs an error of the form `The App has no export named ` on every request that triggers the action. The action never runs successfully but still consumes runtime resources on each affected request.
Before enabling an action:
* Confirm that the `functionId` value matches a named export in the application's built `assets`.
* Disable any `actionId` entries whose corresponding function is not yet deployed by setting `"enabled": false`.
* When removing a function from an application, also remove or disable the corresponding `actionId` entry in the JSON editor.
# Actions (After)
Source: https://docs.kibocommerce.com/pages/actions-after
**Related API:** This extension modifies the [Create Returns](/api-reference/return/create-returns) operation.
This action occurs after a return action is performed. Changes made to the return in this action persist in Kibo.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.return.actions.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Return
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that creates returns.
## Get
### get.rma
Retrieves the current return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.rma();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"contact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"id": "string",
"items": [
{
"bundledProducts": [
{
"productCode": "string",
"quantity": "int"
}
],
"id": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderItemId": "string",
"orderItemOptionAttributeFQN": "string",
"orderLineId": "int",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"deltaPrice": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"priceListCode": "string",
"priceListEntryMode": "string",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productLossAmount": "decimal",
"productLossTaxAmount": "decimal",
"quantityReceived": "int",
"quantityReplaced": "int",
"quantityRestockable": "int",
"quantityShipped": "int",
"reasons": [
{
"quantity": "int",
"reason": "string"
}
],
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNotRequired": "bool",
"returnType": "string",
"shippingLossAmount": "decimal",
"shippingLossTaxAmount": "decimal",
"totalWithoutWeightedShippingAndHandling": "decimal",
"totalWithWeightedShippingAndHandling": "decimal"
}
],
"locationCode": "string",
"lossTotal": "decimal",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"originalOrderId": "string",
"originalOrderNumber": "int",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"optionAttributeFQN": "string",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"check": {
"checkNumber": "string"
},
"data": "string",
"externalTransactionId": "string",
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"paymentWorkflow": "string",
"purchaseOrder": {
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
],
"paymentTerm": {
"code": "string",
"description": "string"
},
"purchaseOrderNumber": "string"
},
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"data": "string",
"externalTransactionId": "string",
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"status": "string"
}
],
"productLossTaxTotal": "decimal",
"productLossTotal": "decimal",
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNumber": "int",
"returnOrderId": "string",
"returnType": "string",
"rmaDeadline": "DateTime",
"shippingLossTaxTotal": "decimal",
"shippingLossTotal": "decimal",
"siteId": "int",
"status": "string",
"tenantId": "int",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
### get.returnAction
Retrieves the current return action.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.returnAction();
```
Response:
Returns an available return action.
## Exec
### exec.addReturnItem
Adds an item to the RMA.
| Parameter | Type | Description |
| ---------- | ------ | ------------------------- |
| returnItem | object | A return item API object. |
Example:
```
context.exec.addReturnItem(returnItemA);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"contact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"id": "string",
"items": [
{
"bundledProducts": [
{
"productCode": "string",
"quantity": "int"
}
],
"id": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderItemId": "string",
"orderItemOptionAttributeFQN": "string",
"orderLineId": "int",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"deltaPrice": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"priceListCode": "string",
"priceListEntryMode": "string",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productLossAmount": "decimal",
"productLossTaxAmount": "decimal",
"quantityReceived": "int",
"quantityReplaced": "int",
"quantityRestockable": "int",
"quantityShipped": "int",
"reasons": [
{
"quantity": "int",
"reason": "string"
}
],
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNotRequired": "bool",
"returnType": "string",
"shippingLossAmount": "decimal",
"shippingLossTaxAmount": "decimal",
"totalWithoutWeightedShippingAndHandling": "decimal",
"totalWithWeightedShippingAndHandling": "decimal"
}
],
"locationCode": "string",
"lossTotal": "decimal",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"originalOrderId": "string",
"originalOrderNumber": "int",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"optionAttributeFQN": "string",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"check": {
"checkNumber": "string"
},
"data": "string",
"externalTransactionId": "string",
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"paymentWorkflow": "string",
"purchaseOrder": {
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
],
"paymentTerm": {
"code": "string",
"description": "string"
},
"purchaseOrderNumber": "string"
},
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"data": "string",
"externalTransactionId": "string",
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"status": "string"
}
],
"productLossTaxTotal": "decimal",
"productLossTotal": "decimal",
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNumber": "int",
"returnOrderId": "string",
"returnType": "string",
"rmaDeadline": "DateTime",
"shippingLossTaxTotal": "decimal",
"shippingLossTotal": "decimal",
"siteId": "int",
"status": "string",
"tenantId": "int",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
### exec.authorizeReturn
Authorizes the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.authorizeReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Authorized",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.cancelReturn
Cancels the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.cancelReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Cancelled",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.closeReturn
Closes the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.closeReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Closed",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.rejectReturn
Rejects the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.rejectReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Rejected",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.setRMADeadline
Sets the deadline for the shopper to ship the items in the RMA to the merchant.
| Parameter | Type | Description |
| ----------- | ---- | --------------------- |
| rmaDeadline | Date | A date in UTC format. |
Example:
```
context.exec.setRMADeadline('2017-01-01T08:00:00.000Z');
```
Response:
No response.
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Actions (Before)
Source: https://docs.kibocommerce.com/pages/actions-before
**Related API:** This extension modifies the [Create Returns](/api-reference/return/create-returns) operation.
This action occurs before a return action is performed. Changes made to the return in this action persist in Kibo.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.return.actions.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Return
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that creates returns.
## Get
### get.rma
Retrieves the current return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.rma();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"contact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"id": "string",
"items": [
{
"bundledProducts": [
{
"productCode": "string",
"quantity": "int"
}
],
"id": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderItemId": "string",
"orderItemOptionAttributeFQN": "string",
"orderLineId": "int",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"deltaPrice": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"priceListCode": "string",
"priceListEntryMode": "string",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productLossAmount": "decimal",
"productLossTaxAmount": "decimal",
"quantityReceived": "int",
"quantityReplaced": "int",
"quantityRestockable": "int",
"quantityShipped": "int",
"reasons": [
{
"quantity": "int",
"reason": "string"
}
],
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNotRequired": "bool",
"returnType": "string",
"shippingLossAmount": "decimal",
"shippingLossTaxAmount": "decimal",
"totalWithoutWeightedShippingAndHandling": "decimal",
"totalWithWeightedShippingAndHandling": "decimal"
}
],
"locationCode": "string",
"lossTotal": "decimal",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"originalOrderId": "string",
"originalOrderNumber": "int",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"optionAttributeFQN": "string",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"check": {
"checkNumber": "string"
},
"data": "string",
"externalTransactionId": "string",
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"paymentWorkflow": "string",
"purchaseOrder": {
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
],
"paymentTerm": {
"code": "string",
"description": "string"
},
"purchaseOrderNumber": "string"
},
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"data": "string",
"externalTransactionId": "string",
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"status": "string"
}
],
"productLossTaxTotal": "decimal",
"productLossTotal": "decimal",
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNumber": "int",
"returnOrderId": "string",
"returnType": "string",
"rmaDeadline": "DateTime",
"shippingLossTaxTotal": "decimal",
"shippingLossTotal": "decimal",
"siteId": "int",
"status": "string",
"tenantId": "int",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
### get.returnAction
Retrieves the current return action.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.returnAction();
```
Response:
Returns an available return action.
## Exec
### exec.addReturnItem
Adds an item to the RMA.
| Parameter | Type | Description |
| ---------- | ------ | ------------------------- |
| returnItem | object | A return item API object. |
Example:
```
context.exec.addReturnItem(returnItemA);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"contact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"id": "string",
"items": [
{
"bundledProducts": [
{
"productCode": "string",
"quantity": "int"
}
],
"id": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderItemId": "string",
"orderItemOptionAttributeFQN": "string",
"orderLineId": "int",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"deltaPrice": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"priceListCode": "string",
"priceListEntryMode": "string",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productLossAmount": "decimal",
"productLossTaxAmount": "decimal",
"quantityReceived": "int",
"quantityReplaced": "int",
"quantityRestockable": "int",
"quantityShipped": "int",
"reasons": [
{
"quantity": "int",
"reason": "string"
}
],
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNotRequired": "bool",
"returnType": "string",
"shippingLossAmount": "decimal",
"shippingLossTaxAmount": "decimal",
"totalWithoutWeightedShippingAndHandling": "decimal",
"totalWithWeightedShippingAndHandling": "decimal"
}
],
"locationCode": "string",
"lossTotal": "decimal",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"originalOrderId": "string",
"originalOrderNumber": "int",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"optionAttributeFQN": "string",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"check": {
"checkNumber": "string"
},
"data": "string",
"externalTransactionId": "string",
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"paymentWorkflow": "string",
"purchaseOrder": {
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
],
"paymentTerm": {
"code": "string",
"description": "string"
},
"purchaseOrderNumber": "string"
},
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"data": "string",
"externalTransactionId": "string",
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"status": "string"
}
],
"productLossTaxTotal": "decimal",
"productLossTotal": "decimal",
"receiveStatus": "string",
"refundAmount": "decimal",
"refundStatus": "string",
"replaceStatus": "string",
"returnNumber": "int",
"returnOrderId": "string",
"returnType": "string",
"rmaDeadline": "DateTime",
"shippingLossTaxTotal": "decimal",
"shippingLossTotal": "decimal",
"siteId": "int",
"status": "string",
"tenantId": "int",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
### exec.authorizeReturn
Authorizes the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.authorizeReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Authorized",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.cancelReturn
Cancels the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.cancelReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Cancelled",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.closeReturn
Closes the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.closeReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Closed",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.rejectReturn
Rejects the return.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.exec.rejectReturn();
```
Response:
```
{
"id": null,
"returnNumber": null,
"returnType": "Refund",
"originalOrderId": "abc123456789",
"originalOrderNumber": null,
"returnOrderId": null,
"availableActions": [],
"status": null,
"receiveStatus": null,
"refundStatus": null,
"replaceStatus": null,
"items": [
{
"orderLineId": 1,
"productCode": "product-1",
"shipmentNumber": 0123,
"shipmentItemId": 1,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
},
{
"orderLineId": 2,
"productCode": "product-2",
"shipmentNumber": 0123,
"shipmentItemId": 2,
"reasons": [
{
"reason": "Damaged",
"quantity": 1
}
],
"returnReason": "Damaged",
"returnType": "Refund",
"orderItemOptionAttributeFQN": "",
"excludeProductExtras": false
}
],
"payments": [
{
"id": "",
"paymentServiceTransactionId": "",
"paymentType": "CreditCard",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "CreditCard",
"billingContact": {
"email": "example.customer@email.com",
"firstName": "Example",
"middleNameOrInitial": "",
"lastNameOrSurname": "Customer",
"phoneNumbers": {
"home": "1234567895",
"mobile": "1234567895",
"work": ""
},
"address": {
"address1": "123 Example Rd",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "TX",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"card": {
"isUsedRecurring": false,
"nameOnCard": "Example Customer",
"isCardInfoSaved": false,
"paymentOrCardType": "VISA",
"cardNumberPartOrMask": "1234567890",
"isTokenized": true,
"expireMonth": 1,
"expireYear": 2026
},
"auditInfo": {
"updateDate": "2024-09-17T17:54:21.027Z",
"createDate": "2024-09-17T17:53:24.598Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "Rejected",
"subPayments": [],
"interactions": [
{
"gatewayInteractionId": 987654321,
"paymentId": "abcde12345",
"currencyCode": "USD",
"interactionType": "Authorization",
"status": "Authorized",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayTransactionId": "12345",
"gatewayAuthCode": "NoOp",
"gatewayAVSCodes": "Y",
"gatewayCVV2Codes": "P",
"gatewayResponseCode": "1",
"gatewayResponseText": "This transaction has been approved.",
"gatewayResponseData": [
{
"key": "AuthorizationRequestId",
"value": "1234567890"
},
{
"key": "AuthorizationRequestToken",
"value": "ABC123"
},
{
"key": "currencyCode",
"value": "USD"
}
],
"amount": 15,
"interactionDate": "2024-09-17T17:54:21.098Z"
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 15
}
],
"refundAmount": null,
"productLossAmount": null,
"shippingLossAmount": null,
"totalLossAmount": null,
"productTotal": null,
"rmaDeadline": null,
"createDate": null,
"updateDate": null,
"isUnified": false
}
```
For information about the properties in the response, refer to the [REST API Help](/api-reference/return/perform-return-action).
### exec.setRMADeadline
Sets the deadline for the shopper to ship the items in the RMA to the merchant.
| Parameter | Type | Description |
| ----------- | ---- | --------------------- |
| rmaDeadline | Date | A date in UTC format. |
Example:
```
context.exec.setRMADeadline('2017-01-01T08:00:00.000Z');
```
Response:
No response.
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add a Core Field
Source: https://docs.kibocommerce.com/pages/add-a-core-field
1. To add a new entry to the list of available fields, click **Add** above the list.\
Once you've clicked Add, a popup will appear with a drop-down menu where you can choose schema type, Core Field or Custom Attribute.
2. Select the Schema Type and then click **Next**.\\
3. Choose a **Core Field Type**, either product or category.\\
Depending on your catalog, you may elect to create a schema that uses both product and category field names. For example, a clothing retailer who chooses Product > ShortDescription will show only individual product listings in their search results for the term "jacket." By also choosing category as a Core Field Type, however, searches can also include results such as "Women's Jackets" or "Long Jackets" in addition to a listing of individual jackets.
### Available Fields
| Product | Category |
| --------------------------------------------------- | -------------------- |
| Code | Code |
| Child Code | Name |
| Name | Description |
| Short Description | Meta Tag Keywords |
| Full Description | Meta Tag Title |
| UPC | Meta Tag Description |
| Mfg Part Number | SEO Slug |
| Category Names | Image URL |
| Meta Tag Keywords | |
| Meta Tag Title | |
| Meta Tag Description | |
| Product Type Name | |
| SEO Slug | |
| Image URL | |
| Margin | |
| First Available Date | |
| Sales Rank (Short Term, Medium Term, and Long Term) | |
4. Select a field from the drop-down menu. This list is mapped to data in your uploaded catalog.\\
5. Select a type from the drop-down menu. These are various analyzers for the field.\\
### Example Analyzers
| Analyzer | Definition |
| ----------------------------- | -------------------------------------------- |
| exact\_match | The search term must be an exact match |
| exact\_match\_type\_ahead | Exact matches only for type ahead |
| lenient | Allows synonyms and stemming |
| lenient\_type\_ahead | Lenient for type ahead |
| lenient\_phrases | Lenient with phrase boosting |
| lenient\_phrases\_type\_ahead | Lenient with phrase boosting for type ahead |
| return\_only | Used for having non-standard fields returned |
| code\_exact | Used for product codes |
| code\_lenient | Split on dashes and dots |
| code\_lenient\_type\_ahead | Code lenient for type ahead |
6. Once you have made this final selection, click **Add**. The popup window will close, and you will see your new entry in the list.\\
7. To remove a list entry, click **Delete** at the end of the row.
## Saving Changes
Any changes made to the Schema Editor will enable the **Save** button.
Once you have saved any changes, you have two options.
* To have your changes reflected in your site, click **Publish Now**.
* If you have made and saved changes in error (but not yet published), then you may click **Revert** to go back the prior saved changes. This will *not* revert to a former published version unless there have been no other saved changes.
# Add Account (After)
Source: https://docs.kibocommerce.com/pages/add-account-after
**Related API:** This extension modifies the [Add Account](/api-reference/customeraccount/add-account) operation.
This action manipulates the HTTP request or response after the AddAccount operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.accounts.addAccount.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/addAccount](/api-reference/customeraccount/add-account) operation.
**HTTP Request**
POST `api/commerce/customer/accounts/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Account and Login (After)
Source: https://docs.kibocommerce.com/pages/add-account-and-login-after
**Related API:** This extension modifies the [Add Account And Login](/api-reference/customeraccount/add-account-and-login) operation.
This action manipulates the HTTP request or response after the AddAccountAndLogin operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.accounts.addAccountAndLogin.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/addAccountAndLogin](/api-reference/customeraccount/add-account-and-login) operation.
**HTTP Request**
POST `api/commerce/customer/accounts/Add-Account-And-Login?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Account and Login (Before)
Source: https://docs.kibocommerce.com/pages/add-account-and-login-before
**Related API:** This extension modifies the [Add Account And Login](/api-reference/customeraccount/add-account-and-login) operation.
This action manipulates the HTTP request or response before the AddAccountAndLogin operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.accounts.addAccountAndLogin.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/addAccountAndLogin](/api-reference/customeraccount/add-account-and-login) operation.
**HTTP Request**
POST `api/commerce/customer/accounts/Add-Account-And-Login?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
**Delegated Authorization**\
The API operation that this action interacts with uses delegated authorization to verify that the caller has access to the requested API resource. If you use context.response.end() to exit the function early, you must manually specify the authorization of the caller to avoid an authorization error. To specify that the caller is authorized, use context.exec.setAuthorized(true). To specify the caller is not authorized, use context.exec.setAuthorized(false).
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Account (Before)
Source: https://docs.kibocommerce.com/pages/add-account-before
**Related API:** This extension modifies the [Add Account](/api-reference/customeraccount/add-account) operation.
This action manipulates the HTTP request or response before the AddAccount operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.accounts.addAccount.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/addAccount](/api-reference/customeraccount/add-account) operation.
**HTTP Request**
POST `api/commerce/customer/accounts/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
**Delegated Authorization**\
The API operation that this action interacts with uses delegated authorization to verify that the caller has access to the requested API resource. If you use context.response.end() to exit the function early, you must manually specify the authorization of the caller to avoid an authorization error. To specify that the caller is authorized, use context.exec.setAuthorized(true). To specify the caller is not authorized, use context.exec.setAuthorized(false).
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Category (After)
Source: https://docs.kibocommerce.com/pages/add-category-after
**Related API:** This extension modifies the [Add Category](/api-reference/categories/add-category) operation.
This action manipulates the HTTP response after the AddCategory operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.catalog.admin.categories.addCategory.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/catalog/admin/categories/AddCategory](/api-reference/categories/add-category) operation.
**HTTP Request**
POST `api/commerce/catalog/admin/categories/?incrementSequence={incrementSequence}&useProvidedId={useProvidedId}&responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo Commerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Category (Before)
Source: https://docs.kibocommerce.com/pages/add-category-before
**Related API:** This extension modifies the [Add Category](/api-reference/categories/add-category) operation.
This action manipulates the HTTP request or response before the AddCategory operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.catalog.admin.categories.addCategory.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/catalog/admin/categories/AddCategory](/api-reference/categories/add-category) operation.
**HTTP Request**
POST `api/commerce/catalog/admin/categories/?incrementSequence={incrementSequence}&useProvidedId={useProvidedId}&responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Credit (After)
Source: https://docs.kibocommerce.com/pages/add-credit-after
**Related API:** This extension modifies the [Add Credit](/api-reference/credit/add-credit) operation.
This action manipulates the HTTP request or response after the AddCredit operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.addCredit.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/addCredit](/api-reference/credit/add-credit) operation.
**HTTP Request**
POST `api/commerce/customer/credits/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Credit (Before)
Source: https://docs.kibocommerce.com/pages/add-credit-before
**Related API:** This extension modifies the [Add Credit](/api-reference/credit/add-credit) operation.
This action manipulates the HTTP request or response before the AddCredit operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.addCredit.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/addCredit](/api-reference/credit/add-credit) operation.
**HTTP Request**
POST `api/commerce/customer/credits/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Custom Attributes
Source: https://docs.kibocommerce.com/pages/add-custom-attributes
1. From the list, click **Add**.
2. Choose **Custom Attribute** from the Schema Type drop-down menu and then click **Next**.\\
3. Search for the field you need by typing and then selecting from the available choices. Because these are more numerous than Core Fields, there is no drop-down to scroll to your selection.\\
4. Choose the Type and then click **Add**. The popup will close, and the new entry will be visible in the list.\\
Learn how to create and configure product attributes
### Saving Changes
Any changes made to the Schema Editor will enable the **Save** button.
Once you have saved any changes, you have two options.
* To have your changes reflected in your site, click **Publish Now**.
* If you have made and saved changes in error (but not yet published), then you may click **Revert** to go back the prior saved changes. This will *not* revert to a former published version unless there have been no other saved changes.
# Add Destination (After)
Source: https://docs.kibocommerce.com/pages/add-destination-after
**Related API:** This extension modifies the [Add Destination](/api-reference/checkout/add-destination) operation.
This action manipulates the HTTP request or response after the addDestination operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.checkouts.addDestination.after |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo")
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Destination (Before)
Source: https://docs.kibocommerce.com/pages/add-destination-before
**Related API:** This extension modifies the [Add Destination](/api-reference/checkout/add-destination) operation.
This action manipulates the HTTP request or response before the addDestination operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.checkouts.addDestination.before |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Item (After)
Source: https://docs.kibocommerce.com/pages/add-item-after
**Related API:** This extension modifies the [Add Item To Cart](/api-reference/cart/add-item-to-cart) operation.
This action occurs after an item is added to a cart. Changes made to the cart or cart items in this action do not persist in Kibo eCommerce.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.carts.addItem.after |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: Cart Item
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**
This action corresponds to the microservice that adds an item to a cart.
## Get
### get.cart
Obtains a response that includes information about the current cart.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cart();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### get.cartItem
Obtains a response that includes information about the current cart item. Only available for actions specific to cart items.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cartItem();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setData
Sets custom key/value data on the current cart.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| key | string | Key of the data to set on the cart. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the specified cart.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from the cart. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------- |
| key | string | Key of the data to set on the cart item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the cart item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the cart item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from a cart item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemAllocation
Sets soft allocation information on a cart item.
| Parameter | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the cart item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for a cart item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItem
Removes an item from the cart.
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| itemId | string | Id of the item to remove. |
Example:
```
context.exec.removeItem("123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Item (Before)
Source: https://docs.kibocommerce.com/pages/add-item-before
**Related API:** This extension modifies the [Add Item To Cart](/api-reference/cart/add-item-to-cart) operation.
This action occurs before an item is added to a cart. Changes made to the cart or cart items in this action persist in Kibo eCommerce.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.carts.addItem.before |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: Cart Item
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**
This action corresponds to the microservice that adds an item to a cart.
## Get
### get.cart
Obtains a response that includes information about the current cart.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cart();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### get.cartItem
Obtains a response that includes information about the current cart item. Only available for actions specific to cart items.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cartItem();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setData
Sets custom key/value data on the current cart.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| key | string | Key of the data to set on the cart. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the specified cart.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from the cart. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------- |
| key | string | Key of the data to set on the cart item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the cart item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the cart item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from a cart item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemAllocation
Sets soft allocation information on a cart item.
| Parameter | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the cart item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for a cart item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItem
Removes an item from the cart.
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| itemId | string | Id of the item to remove. |
Example:
```
context.exec.removeItem("123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Item (HTTP After)
Source: https://docs.kibocommerce.com/pages/add-item-http-after
**Related API:** This extension modifies the [Create Order Item](/api-reference/order/create-order-item) operation.
This action manipulates the HTTP request or response after the Add Item operation occurs in Kibo. Changes made to the order or order items in this action persist in Kibo.
Kibo supports both Embedded and HTTP versions of this API Extension. The [embedded version](/pages/orders-add-item-embedded-after "Add Item (Embedded After)") allows manipulating specific fields during the execution, while the HTTP version allows modifying the full request and response on the API.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.orders.addItem.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Create Order Item](/api-reference/order/create-order-item) operation.
**HTTP Request**
POST `api/commerce/orders/{orderId}/items`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Item (HTTP Before)
Source: https://docs.kibocommerce.com/pages/add-item-http-before
**Related API:** This extension modifies the [Create Order Item](/api-reference/order/create-order-item) operation.
This action manipulates the HTTP request or response before the Add Item operation occurs in Kibo. Changes made to the order or order items in this action persist in Kibo.
Kibo supports both Embedded and HTTP versions of this API Extension. The [embedded version](/pages/orders-add-item-embedded-before "Add Item (Embedded Before)") allows manipulating specific fields during the execution, while the HTTP version allows modifying the full request and response on the API.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.orders.addItem.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Create Order Item](/api-reference/order/create-order-item) operation.
**HTTP Request**
POST `api/commerce/orders/{orderId}/items`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Payments to Orders
Source: https://docs.kibocommerce.com/pages/add-payments-to-orders
Use the **Payments** tab of order details to view and add the customer’s payment information. Shoppers can pay with a credit card, check, gift card, or store credit. If you process a payment outside of the platform, such as through a third-party like PayPal or at a brick-and-mortar location, you can associate the payment details using the manual credit card option.
See how to manage payments on orders
You can only add payment methods that have been enabled for the site. You can view the enabled payment methods at **System** > **Settings** > **Payment Types**. Refer to [Payment Types](/pages/payment-types) for more information.
## Add Payment Method
When adding a new payment method to an existing order, you will be able to either add a new credit card or apply another payment to an existing credit card that was already used on the order.
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to add a payment to.
3. Click the **Payments** tab of the order details.
4. Use the **Add Payment** drop-down menu to select a payment method. You can use any payment method that's enabled on the applicable site. For purchase orders, refer to [Purchase Orders](/pages/purchase-orders) for more information.
### Add New Credit Card
Click **Add Payment** or **Credit Card (Manual)** to open a dialogue box that lists all billing information fields as shown below. They must all be populated before the payment can be created. If the details of a new credit need to be added:
1. Check **New Credit Card** in the Add Payment dialogue window.
2. Enter the payment information for all fields. Those marked with an asterisk are required.
3. Click **Save** to authorize the transaction.
### Add Existing Credit Card
However, if a credit card already exists for the order then the dialogue box will offer an **Order Credit Cards** option that will allow the new payment to reference the existing card information in the order. Use this option to quickly create a new payment method in a case where the same card and billing information is being charged again.
1. Check **Order Credit Cards** in the Add Payment dialogue window.
2. Select an credit card from the **Existing Gift Cards on Order** drop-down.
3. Set the **Amount** to charge to the card.
4. Click **Save** to authorize the transaction.
# Add Transaction (After)
Source: https://docs.kibocommerce.com/pages/add-transaction-after
**Related API:** This extension modifies the [Add Transaction](/api-reference/credit/add-transaction) operation.
This action manipulates the HTTP request or response after the AddTransaction operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.addTransaction.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/transactions/addTransaction](/api-reference/credit/add-transaction) operation.
**HTTP Request**
POST `api/commerce/customer/credits/transactions/{code}/transactions?responseFields={responseFields}`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Add Transaction (Before)
Source: https://docs.kibocommerce.com/pages/add-transaction-before
**Related API:** This extension modifies the [Add Transaction](/api-reference/credit/add-transaction) operation.
This action manipulates the HTTP request or response before the AddTransaction operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.addTransaction.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/transactions/addTransaction](/api-reference/credit/add-transaction) operation.
**HTTP Request**
POST `api/commerce/customer/credits/transactions/{code}/transactions?responseFields={responseFields}`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Address Validation (After)
Source: https://docs.kibocommerce.com/pages/address-validation-after
**Related API:** This extension modifies the [Validate Address](/api-reference/addressvalidation/validate-address) operation.
This action manipulates the HTTP request or response after the ValidateAddress operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.address.validation.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/addressvalidation](/api-reference/addressvalidation/validate-address) operation.
**HTTP Request**
POST `api/commerce/customer/addressvalidation/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Address Validation (Before)
Source: https://docs.kibocommerce.com/pages/address-validation-before
**Related API:** This extension modifies the [Validate Address](/api-reference/addressvalidation/validate-address) operation.
This action manipulates the HTTP request or response before the ValidateAddress operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.address.validation.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/addressvalidation](/api-reference/addressvalidation/validate-address) operation.
**HTTP Request**
POST `api/commerce/customer/addressvalidation/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Address Validator
Source: https://docs.kibocommerce.com/pages/address-validator
The address validator is an application capability, in which you implement a REST endpoint that accepts a request and returns a response for the given capabilities. This validates that street and postal addresses exist.
## Add Address Validator
Follow the below steps to add an address validator:
1. In Dev Center, navigate to **Develop** > **Applications > Packages > Capabilities.**
2. Click **Add Capability**.
3. Search for **Address Validator** in the **Add Capability** modal and click **Ok.**\\
4. Add a URL for a web service that you host externally (or an API Extension [http.storefront.routes](/pages/storefront-routes) function if you want it hosted in Kibo).
5. Select the validator country from the list of countries.
By default, Kibo uses USPS as the validator. As long as your service returns addresses in the below formats you can create your own address validator using any other service (FedEx, Google, etc).
### Validate Address API
Your service must accept an [addressvalidation](/api-reference/addressvalidation/validate-address) request. Use the below template to create your API request:
```
{
address: {
address1: string | null
address2: string | null
address3: string | null
address4: string | null
cityOrTown: string | null
stateOrProvince: string | null
postalOrZipCode: string | null
countryCode: string | null
addressType: string | null
isValidated: boolean | null
}
}
```
and must reply with a response in this form:
```
{
addressCandidates: [{
address1: string | null
address2: string | null
address3: string | null
address4: string | null
cityOrTown: string | null
stateOrProvince: string | null
postalOrZipCode: string | null
countryCode: string | null
addressType: string | null
isValidated: boolean | null
}]
}
```
Like the tax integrations, you can also implement [Address Validation (Before)](/pages/address-validation-before) and [Address Validation (After)](/pages/address-validation-after).
## Installing and Testing
Once you have the service hosted at a given URL (and tested with Postman to make sure the responses are coming out as expected), you can install it on a tenant.
Follow the below steps for testing.
1. After the application is installed, go to **Applications** **Page** and click on the **Application.**
2. Click the toggle to “Enabled”. This will enable your address validator.
3. You can test the validator using the storefront theme, or by making API calls to the [Address Validation API](/api-reference/addressvalidation/validate-address).
For a reference of all available platform capability types, see [Application Capabilities](/pages/applications-1a6c791-introduction#add-a-capability).
# Administration
Source: https://docs.kibocommerce.com/pages/administration
User management allows you to add users and assign roles for staff in your organization, grant solution partners or existing users access to your sandbox(es), and add users to your Dev Center projects.
See the Admin User API documentation for programmatic access
Learn how to set up Fulfiller user permissions
See how to configure user roles and permissions
You should consider what [role](#roles-and-permissions) a user needs before inviting them to your Dev Account. Before you can add users to sandboxes or projects, you must invite them to your Dev Account. Only the Dev Account Owner, Project Manager, or Lead Developer roles can invite users. To see a list of users that have access to your Dev Account and what role they have role, click the drop-down arrow beside the name of your Dev Account in the upper-right corner and select **Users**.
## Invite a User
To invite a user to your Dev Account:
1. Log in to Dev Center.
2. Click the drop-down arrow beside the name of your DevAccount in the upper-right corner and click **Users** > **Invite Users**.
3. Enter the user’s email address.
4. Select a role from the drop-down menu.
5. Click **Save**.
Inviting users sends an email to the specified recipient with a confirmation link. The invitation remains in a pending status until the recipient confirms or declines the invitation.
## Add User to Sandbox
To grant a user access to a sandbox:
1. Log in to Dev Center.
2. Click **Sandboxes**.
3. Double-click a sandbox.
4. Click the **Details** tab.
5. Click **Add Sandbox User**.
6. Select a user from the list and click **OK**.
7. Click **Save**.
## Add User to Project
To add a user to a project:
1. Log in to Dev Center.
2. Click **Projects**.
3. Double-click a project.
4. Click the **Add Team Member**.
5. Select a user from the list and click **OK**.
6. Click **Save**.
## Roles and Permissions
A role is a collection of permissions that defines what a user can do in Dev Center. A user can have different roles in multiple Dev Accounts, but can only perform the behaviors of the role associated with that specific Dev Account. For example, in Dev Account A, if you define Steven as a Lead Developer, but in Dev Account B, you define Steven as a Marketer, he cannot perform the marketing role in Dev Account A. Behaviors within a role are predefined, so users cannot add or remove behaviors from a role.
Click one of the following headings to see a matrix of roles and permissions in Dev Center:
* \_group\_Dev Accounts
| | Dev Account Owner | Project Manager | Lead Developer | Developer | Marketer |
| -------------------------- | ----------------- | --------------- | -------------- | --------- | -------- |
| Invite users | ✔ | ✔ | ✔ | | |
| Remove users | ✔ | ✔ | ✔ | | |
| Change user roles | ✔ | ✔ | ✔ | | |
| Change user developer type | ✔ | | ✔ | | |
| Modify contact info | ✔ | ✔ | | | |
* *content\_copy* Applications
| | Dev Account Owner | Project Manager | Lead Developer | Developer | Marketer |
| -------------------------------- | ----------------- | --------------- | -------------- | --------- | -------- |
| Create new | ✔ | ✔ | ✔ | ✔ | |
| Create release notes | ✔ | ✔ | ✔ | ✔ | |
| Modify metadata | ✔ | ✔ | ✔ | ✔ | ✔ |
| Submit for certification | ✔ | ✔ | ✔ | | |
| Upload application files | ✔ | ✔ | ✔ | ✔ | |
| Download files | ✔ | ✔ | ✔ | ✔ | ✔ |
| Clone packages | ✔ | ✔ | ✔ | ✔ | ✔ |
| Create new packages | ✔ | ✔ | ✔ | ✔ | |
| Delete packages (except Release) | ✔ | ✔ | ✔ | ✔ | ✔ |
| Configure behaviors | ✔ | ✔ | ✔ | ✔ | ✔ |
| Install on sandboxes | ✔ | ✔ | ✔ | ✔ | |
| Install on production | ✔ | ✔ | ✔ | | |
* *library\_books* Themes
| | Dev Account Owner | Project Manager | Lead Developer | Developer | Marketer |
| -------------------------------- | ----------------- | --------------- | -------------- | --------- | -------- |
| Create new | ✔ | ✔ | ✔ | ✔ | |
| Create release notes | ✔ | ✔ | ✔ | ✔ | |
| Modify metadata | ✔ | ✔ | ✔ | ✔ | ✔ |
| Publish | ✔ | ✔ | ✔ | ✔ | |
| Certify | ✔ | | | | |
| Upload files | ✔ | ✔ | ✔ | ✔ | |
| Download files | ✔ | ✔ | ✔ | ✔ | ✔ |
| Delete files | ✔ | ✔ | ✔ | ✔ | |
| Clone packages | ✔ | ✔ | ✔ | ✔ | ✔ |
| Create new packages | ✔ | ✔ | ✔ | ✔ | |
| Delete packages (except Release) | ✔ | ✔ | ✔ | ✔ | ✔ |
| Install on sandboxes | ✔ | ✔ | ✔ | ✔ | |
| Install on production | ✔ | | ✔ | | |
* *work* Projects
| | Dev Account Owner | Project Manager | Lead Developer | Developer | Marketer |
| ------------ | ----------------- | --------------- | -------------- | --------- | -------- |
| Create new | ✔ | ✔ | ✔ | ✔ | |
| Add users | ✔ | ✔ | ✔ | ✔ | |
| Remove users | ✔ | ✔ | ✔ | | |
| Modify | ✔ | ✔ | ✔ | ✔ | |
| Delete | ✔ | ✔ | | | |
* *widgets* Sandboxes
| | Dev Account Owner | Project Manager | Lead Developer | Developer | Marketer |
| ---------------------- | ----------------- | --------------- | -------------- | --------- | -------- |
| Create new | ✔ | ✔ | ✔ | ✔ | |
| Add users | ✔ | ✔ | ✔ | ✔ | |
| Remove users | ✔ | ✔ | | | |
| Modify | ✔ | ✔ | ✔ | ✔ | |
| Create master catalogs | ✔ | ✔ | ✔ | ✔ | |
| View (access Admin) | ✔ | ✔ | ✔ | ✔ | |
# Adyen Application
Source: https://docs.kibocommerce.com/pages/adyen-application
![Adyen logo]() |
| Platforms: KCCP eCommerce and eCommerce+OMS |
[Adyen](https://www.adyen.com/) is a digital payment platform allowing you to process payments online, in-person, and cross channel. Kibo's Adyen Integration application enables you to easily add Adyen's payment functionality to your existing eCommerce payment options.
## Setup Overview
The following steps are required before you can use Adyen on your site(s):
1. Contact [Kibo Support](https://help.kibocommerce.com/) and request for the Adyen application to be installed on your tenant.
2. Kibo will install the application and configure your payment gateway adapter.
3. Create an Adyen gateway on your Payment Settings page.
## Enable the App
After configuration, you can go to **System** > **Customization** > **Applications** in the Admin UI and confirm that the Adyen Integration application is listed and enabled. You can disable it here if ever needed.
## Configure Payment Gateway
Create a new payment gateway for Adyen:
1. Go to **System** > **Settings** > **Payment Gateways**.
2. Click **Create New Payment Gateway**.
3. In the Payment Gateway drop-down menu, select the Adyen app.
4. Provide your **Secret API Key**.
5. Click **Save**.
# Allocation Rebalancer
Source: https://docs.kibocommerce.com/pages/allocation-rebalancer
The Allocation Rebalancer is an event-driven inventory rebalancing capability within the Kibo B2B Wholesale OMS that detects supply and demand changes and automatically reprioritizes future shipments and backorder queues in response. In wholesale distribution, inventory conditions change constantly — purchase orders are delayed, quantities are cut, and orders are cancelled. Without automated rebalancing, these changes go unaddressed until the fulfillment team discovers the shortfall at pick time.
The Allocation Rebalancer closes this gap by detecting supply and demand change events at the Product-location level and executing a sequential rebalancing flow that re-secures inventory for the right shipments in the right priority order.
**Note:** The Allocation Rebalancer operates on **hard-allocated shipments** — future shipments and backorder shipments. For soft-allocated reservations on Call-Off Orders, see the[Reservation Rebalancer](/pages/reservation-rebalancer).
## **How the Allocation Rebalancer Works**
The Allocation Rebalancer processes two types of change events:
**Supply Change Events**
| **Event** | **Description** | **Impacts** |
| :------------------- | :----------------------------------------------------------------------- | :--------------------------------------- |
| **PO Delayed** | A purchase order's expected arrival date is pushed beyond the time fence | Future Shipments Queue |
| **PO Short-Shipped** | A purchase order arrives with fewer units than expected | Future Shipments Queue |
| **PO Cancelled** | A purchase order is cancelled entirely | Future Shipments Queue → Backorder Queue |
**Demand Change Events**
| **Event** | **Description** | **Impacts** |
| :--------------------- | :------------------------------------------------------------------------ | :-------------- |
| **Order Cancelled** | An order is cancelled, freeing previously allocated inventory | Backorder Queue |
| **Order Line Reduced** | An order line quantity is reduced, freeing previously allocated inventory | Backorder Queue |
**Note:** Demand Up events (new orders placed, quantities increased) are not tracked by the Allocation Rebalancer. New orders follow the standard order placement flow and result in new future or backorder shipments as appropriate.
**Note:** All references to purchase order changes in the Kibo platform translate to changes on **Future Inventory Records** — `On Inventory` records keyed by UPC, expected delivery date, and destination location. Kibo OMS does not generate purchase orders directly; PO generation is handled in middleware between your ERP and the OMS.
### **Rebalancing Flow**
When a supply or demand change event is detected, the Allocation Rebalancer executes the following sequential flow:
**Step 1 — Capture and Accumulate Events.** Change events are detected and stored. To prevent excessive processing from rapid successive events (for example, a purchase order receipt posting many line items individually), events are accumulated within a configurable debounce window (default: 60 seconds). All events for the same UPC-location within the window are collapsed into a single re-evaluation before the flow proceeds.
**Step 2 — Identify Impacted Future Shipments.** The system identifies all future shipments allocated against the affected future inventory record at the location. Only shipments in **Future** status are eligible. Shipments in **Ready** status are never touched.
**Step 3 — Prioritize Future Shipments.** The [Future Shipment Rules](/pages/future-shipment-rules) run against the impacted future shipments to assign each a priority rank. Shipments matching higher-priority rules are protected first during reallocation.
**Step 4 — Reallocate Future Shipments.** The system attempts to re-secure inventory for each impacted future shipment (processed in priority order) from alternate future inventory records within the configured time fence, by calling Order Routing. If reallocation cannot be preserved for a shipment, it is de-allocated and moved to the after-action queue (Backorder, Customer Care, or Cancel) as determined by Order Routing configuration. When supply decreases, the lowest-priority shipments lose their allocation first.
**Step 5 — Prioritize Backorder Queue.** The [Backorder Shipment Rules](/pages/backorder-shipment-rules) run against the **full** backorder queue — not only the newly affected shipments — to re-rank all backorder shipments against the revised inventory position.
**Step 6 — Release Backorders.** Backorder shipments are released in priority order. Shipments that can be fulfilled from available inventory are released into the fulfillment pipeline. Shipments that cannot be satisfied remain on backorder.
**Note:** If a change event produces no impacted future shipments (for example, a demand event such as an order cancellation), Steps 2–4 are skipped and the flow proceeds directly to Step 5.
**EDD on Re-pegged and Released Shipments**
Every shipment produced by the Allocation Rebalancer — whether re-pegged to an alternate PO, moved to backorder, released from backorder to a new future or ready shipment, or split — has its EDD automatically recalculated from the new location and date. A shipment moved to backorder has its EDD cleared, as no delivery can be promised until inventory is secured. A backorder shipment subsequently released by the Allocation Rebalancer receives a freshly calculated EDD from the newly allocated location and date.
This recalculation is part of the existing EDD behavior for future inventory changes — the Allocation Rebalancer is one of the triggering pathways. See [EDD Recalculation on Future Inventory Changes](/pages/estimated-delivery-dates#edd-recalculation-on-future-inventory-changes) on the Estimated Delivery Dates page for the full scenario matrix.
## **Trigger Mode**
An admin can configure how the rebalancing flow is initiated at the site level:
| **Mode** | **Behavior** |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fully Automated** | The system automatically executes the full sequential rebalance flow at configured intervals without waiting for user action. The **Run Rebalancer** button is hidden in the UI. |
| **Manual Only** | The rebalancer executes only when a user clicks **Run Rebalancer** in the Balancer Run Audit UI. |
To configure the trigger mode:
1. Go to **Main** > **System** > **Settings** > **Site**
2. Select the **B2B** tab.
3. Under **Inventory Balancing & Reservations** , set the **Trigger Mode** to **Fully Automated** or **Manual Only**.
4. Make Sure Allocation Rebalancer is Enabled
5. Click **Save**.
**Note:** The Allocation Rebalancer, Reservation Rebalancer, and Reservation Rules job are orchestrated as part of a single site-level scheduling configuration. See [Orchestrator Settings](/pages/general-settings#inventory-balancing-&-reservations) for details on sequencing and enabling or disabling individual components.
## **Time Fence**
The time fence determines the window of future inventory that the rebalancer considers when reallocating future shipments or releasing backorders. It is calculated symmetrically around the shipment's requested ship date:
* `Start of Time Fence = requestedShipDate − timeFenceDays`
* `End of Time Fence = requestedShipDate + timeFenceDays`
Only inventory available within this window is eligible for reallocation.
A purchase order change that falls outside the time fence triggers rebalancing. A change that arrives within the time fence (early or late) does not require rebalancing, as the supply still meets the shipment's timing requirements.
## **Segmentation**
If your tenant uses inventory segmentation, the Allocation Rebalancer respects segment tags during reallocation and backorder release. Inventory is only allocated from within the designated segment for each shipment.
## **Prerequisites**
Before using the Allocation Rebalancer, ensure the following:
* The **B2B Wholesale OMS** feature is enabled for your tenant. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this capability.
* Supply Demand UI(new Inventory UI) should be enabled for your tenant. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this capability.
* At least one **Future Shipment Rule** is configured and enabled. See [Future Shipment Rules](/pages/future-shipment-rules).
* At least one **Backorder Shipment Rule** is configured and enabled. See [Backorder Shipment Rules](/pages/backorder-shipment-rules).
* The **Trigger Mode** is configured at the site level.
* You have **Admin** or **Super Admin** role permissions, or a role with Allocation Rebalancer access.
## **Rebalancer Run Audit**
Every rebalancing run produces a full audit trail accessible on the **Rebalancer Run Audit** page. The audit trail is the primary tool for reviewing what changed in a given run, understanding why specific shipments were prioritized, and tracing outcomes back to the triggering supply or demand event.
To open the Rebalancer Run Audit:
1. Go to **Main** > **Fulfillment** > **Allocation Rebalancer**.
2. The **Rebalancer Run Audit** page opens with the **Allocation Rebalancer** tab selected by default.
3. Select a **Site** from the site selector to filter runs for that site.
### **Run Modes**
If the site is configured for **Manual Only** trigger mode, a **Run Rebalancer** button is visible in the header. Click it to manually initiate a rebalancing run. Use the dropdown to choose:
* **Run Rebalancer** — Runs both the Allocation Rebalancer and Reservation Rebalancer together.
* **Run Allocation Rebalancer** — Runs only the Allocation Rebalancer.
If the site is configured for **Fully Automated** mode, this button is hidden. Runs are auto-initiated on the configured schedule and listed in the run table as they complete.
### **Run List**
The Run List is the default landing view within the Rebalancer Run Audit page. It displays a paginated list of all rebalancing runs for the selected site, ordered newest first. A live row count is shown above the table — for example, *"5 runs · newest first"* — and is always backend-computed.
#### **Search & Filters**
| **Control** | **Values** | **Behavior** |
| :----------- | :------------------------------------------ | :--------------------------------------------------------------------------------------- |
| **Search** | Free text | Server-side match on Code, Location, Customer, or date across the run's tracked changes. |
| **Status** | All statuses / Completed / Partial / Failed | Server-side filter. |
| **Run Mode** | All / Automated / Manual | Server-side filter. |
| **Reset** | — | Clears all active filters and restores the full newest-first run list. |
#### **Data Table Columns**
| **Column** | **Description** |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Run** | The unique Run ID and the date/timestamp the run was initiated. |
| **Summary** | A one-line, human-readable description of what the run processed — for example, *"2 supply changes · 14 future shipments evaluated · 8 backorders released."* |
| **Run Mode** | Indicates whether the run was user-initiated (**Manual**) or system-initiated (**Automated**). For Manual runs, the trigger reference is shown (for example, `PO-4522`). For Automated runs, displays *"Automated."* |
| **Tracked** | The total count of supply and demand change events captured and tracked in this run. |
| **Evaluated · F / B** | A split count of the shipments evaluated during the run. **F** = number of Future Shipments impacted by the tracked events. **B** = number of Backorder shipments in the backorder queue at the time of the run. |
| **Results · F / B** | A split count of the shipments produced as final outputs of the run. **F** = total Future Shipments as results. **B** = total Backorder Shipments as results. Results can exceed Evaluated counts when the run produces newly created split or re-pegged shipments. |
| **Status** | A badge indicating the run outcome: **Completed**, **Partial**, or **Failed**. |
#### **Run Status Values**
| **Status** | **Meaning** |
| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Completed** | The full rebalancing flow executed without interruption. All events were processed, future shipments were evaluated and reallocated, and the backorder queue was prioritized and released as applicable. |
| **Partial** | The run was interrupted before completing all steps. Some data was processed and is visible in the Run Detail tabs — what you see reflects the subset of work completed before the halt. The status badge in both the Run List and Run Detail header clearly reflects Partial. |
| **Failed** | The run encountered a fault and could not complete. A fault reason consistent with backend fault states (`SKIPPED` / `FAULTED` / `ABORTED`) is surfaced in the Run Detail view. Whatever subset of data was processed before the failure is visible in the Run Detail tabs. |
### **Run Detail**
Click any run in the Run List to open its detail view. The Run Detail page provides a full breakdown of what the rebalancer evaluated and what outcomes it produced for that specific run.
#### **Header**
The Run Detail header displays key metadata for the selected run at a glance:
| **Element** | **Description** |
| :--------------------- | :------------------------------------------------------------------------------------------- |
| **Run ID + Timestamp** | Unique identifier and date/time the run was initiated. |
| **Status badge** | Completed, Partial, or Failed — matches the badge shown in the Run List. |
| **Trigger** | The event type and reference that initiated the run (for example, "PO date slip / PO-4522"). |
| **Summary** | A one-line plain-English description of what the run did. |
| **Metric tiles** | Changes tracked; Evaluated shipments (Future/Backorder split); Status. |
**Note:** If a run has a **Partial** or **Failed** status, the header badge prominently reflects this. All three tabs still render whatever subset of data was processed before the run halted — data is never silently shown as Completed. A Failed run additionally surfaces a fault reason consistent with backend fault states (`SKIPPED` / `FAULTED` / `ABORTED`).
#### **Tab Bar**
The Run Detail page contains three tabs, each with a count badge showing the number of records in that tab:
* **Supply/Demand Changes** *(default landing tab)*
* **Shipments · Future**
* **Shipments · Backorder**
#### **Supply/Demand Changes Tab**
The Supply/Demand Changes tab is the starting point for understanding *why* a rebalancing run was triggered. It lists every tracked change event detected during the run — supply decreases (PO date slips, PO quantity drops) and demand decreases (cancellations) — and lets you trace forward to see exactly which shipments were impacted.
##### **Search & Filters**
| **Control** | **Values** |
| :-------------------- | :--------------------------------------------------------- |
| **Search** | Free text — ProductCode, PO number (External ID), Location |
| **Change Type** | All change types / Supply / Demand |
| **Sub-type (Supply)** | All (Supply) / PO date slip / PO quantity drop |
| **Sub-type (Demand)** | All (Demand) / Cancellation |
| **Reset** | Clears all filters on this tab |
##### **Table Columns**
| **Column** | **Description** |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Change** | Change type and sub-type chip (for example, Supply — PO date slip). |
| **Entity** | Three fields identifying the affected future inventory record: **PO number** (the External ID of the future inventory record); **UPC** (the product UPC on the record); **Location** (the destination location on the record). |
| **Delta** | What changed, expressed as before → after. For example: PO date moved from April 5 to April 19, or quantity changed from 1,000 to 700. |
| **Detected** | The date and time the system detected the change event. |
**Note:** The **PO number** displayed in the Entity column is the External ID of the future inventory record — not a Kibo-native PO number. Kibo OMS does not generate purchase orders. Clients are responsible for interfacing the correct External ID value for each future inventory record so that it maps back to their PO reference in their ERP or middleware system.
##### **Supply Down Event Sub-types**
| **UI Label** | **What It Means** |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PO date slip** | The PO is arriving later than expected and its new date falls outside the time fence — *or* the PO is arriving earlier than expected and its early date also falls outside the (negative) time fence. |
| **PO quantity drop** | The PO's expected quantity has been reduced. |
##### **Demand Down Events**
| **UI Label** | **What It Means** |
| :--------------- | :------------------------------------------------------------------------------------------------ |
| **Cancellation** | An order cancellation or order line quantity reduction that freed previously allocated inventory. |
##### **Selection & Cross-Tab Pre-filter**
Selecting a row (single-select) shows a banner at the top of the table:
> *"1 change selected · open Shipments · Future or Backorder to see impacted shipments."*
The selected change pre-filters both **Shipments · Future** and **Shipments · Backorder** to display only the shipments whose affected shipment IDs include this event. Select "Clear change filter" or uncheck the row to restore both tabs to the unfiltered view.
**Note:** Selecting a **Demand (Cancellation)** event and then switching to **Shipments · Future** displays an empty state — not an error. Demand events never impact future shipments. The same event *does* feed the **Shipments · Backorder** tab.
#### **Shipments · Future Tab**
The Shipments · Future tab shows every future shipment the rebalancer considered during the run. Use this tab to understand which shipments were evaluated, what priority they were assigned, and what happened to each one.
The tab supports two views, toggled at the top of the tab:
* **Evaluated** *(default)* — The original shipments assessed during the run and their individual outcomes.
* **Results** — The final state of every shipment touched by the run, including newly created shipments produced by splits, re-pegs, or backorder moves.
##### **Search & Filters**
Free-text search by **Shipment #**, **Item**, **Location**, or **Account**.
##### **Evaluated View — Columns**
| **Column** | **Description** |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Shipment # / Order #** | The shipment ID and its associated order number. Only original shipments considered for rebalancing appear here — newly created split or reassigned shipments appear in Results only. Shipments whose PO delay stayed within the time fence never appear here at all (they were not impacted and required no evaluation). |
| **Line Items** | All line items in the shipment (not only the impacted lines). Displays up to three products inline; if there are more, a **+N** overflow indicator is shown. Also displays the total unit count across all line items. |
| **Location** | The location name the shipment is assigned to. |
| **Account** | The buyer account name. |
| **Requested Ship Date** | The requested ship date on the shipment. |
| **Ship Window** | The time fence window (requested ship date ± time fence days) used for inventory search during the run. |
| **Priority** | The rank assigned to this shipment by the Future Shipment Rules. Hover over the rank to see a tooltip explaining which rule assigned it and why. Shipments with no matching rule show null priority. |
| **Evaluation Outcome** | The outcome determined for this shipment during the run. See the outcome values table below. |
##### **Evaluated Outcome Values**
| **Evaluation Outcome** | **Meaning** |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No change** | The shipment was impacted by the PO change but retained its original allocation — a suitable alternate inventory source was found within the time fence. |
| **Pegged to another PO (Full)** | The entire shipment was re-allocated to a single alternate PO. All line items moved together. |
| **Moved to Backorder (Full)** | The entire shipment could not be reallocated and moved to the backorder queue. No alternate PO could satisfy any line item. |
| **Partially Reallocated** | A mixed outcome across lines. Click the row to open the Shipment Detail Panel for line-level breakdown. Possible combinations: some lines remained on the original shipment and some were pegged to other POs; some lines remained and some were backordered; or a combination of all three — some remained, some re-pegged, some backordered. |
##### **Results View — Columns**
The Results view shows the final state of every future shipment touched by the run, including newly created shipments from splits, re-pegs, or backorder moves that are not visible in the Evaluated view.
| **Column** | **Description** |
| :----------------------- | :-------------------------------------------------------------------------------------------------------- |
| **Shipment # / Order #** | Includes both original shipments and any newly created shipments resulting from the run (tagged **NEW**). |
| **Line Items** | Same display pattern as Evaluated view. |
| **Location** | Location name. |
| **Account** | Buyer account name. |
| **Requested Ship Date** | Requested ship date. |
| **Ship Window** | Time fence window. |
| **Result Type** | The final classification for this shipment record. See result type values below. |
##### **Results View — Result Type Values**
| **Result Type** | **Meaning** |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------- |
| **No change** | The shipment retained its original allocation with no modification. |
| **Backorder (New)** | A new backorder shipment was created as a result of the run — the original shipment could not be fully reallocated. |
| **Pegged to a PO (New)** | A newly created future shipment resulting from a re-peg, reassignment, or split. |
| **Partially Reallocated** | The original shipment retained some lines after a split — other lines were moved to backorder or re-pegged to other POs. |
#### **Shipments · Backorder Tab**
The Shipments · Backorder tab shows the full backorder queue evaluated during the run. Unlike the Shipments · Future tab — which only shows shipments newly impacted by the triggering event — this tab always shows the **entire** tenant backorder queue, because the Backorder Shipment Rules re-rank all backorders together against the revised inventory position on every run.
The same **Evaluated / Results** toggle pattern applies.
##### **Search & Filters**
Free-text search by **Shipment #**, **Item**, **Location**, or **Account**.
***
##### **Evaluated View — Columns**
| **Column** | **Description** |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Priority** | The rank assigned by the Backorder Shipment Rules for this run. Hover to view a tooltip showing which rule assigned the rank and why. Null-priority shipments are shown at the bottom. |
| **Shipment # / Order #** | Shipment ID and associated order number. |
| **Line Items** | All line items in the shipment. Displays up to three products inline; overflow shown as **+N**. Total unit count shown. |
| **Location** | Location name. |
| **Account** | Buyer account name. |
| **Requested Ship Date** | Requested ship date on the shipment. |
| **Ship Window** | Time fence window (requested ship date ± time fence days from the matched Backorder Shipment Rule). |
| **Evaluation Outcome** | The outcome for this backorder shipment during the run. See outcome values below. |
##### **Evaluated Outcome Values**
| **Evaluation Outcome** | **Meaning** |
| :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pegged to a PO (Full)** | The entire backorder shipment was fully pegged to an incoming PO / future inventory record. |
| **Released as Ready (Full)** | The entire backorder shipment was fully released using available on-hand inventory and moved to Ready status. |
| **Remain in Backorder with Partial Release** | Some lines were released (either pegged to a PO or released as ready), while others remain in backorder. This can result from a line-item split or a quantity split. |
| **No change** | The shipment remained fully in backorder — no inventory was available to fulfill it during this run. |
##### **Results View — Columns**
| **Column** | **Description** |
| :----------------------- | :-------------------------------------------------------------------------- |
| **Priority** | Priority rank assigned during this run. |
| **Shipment # / Order #** | Includes both original backorder shipments and any newly created shipments. |
| **Line Items** | Same display as Evaluated view. |
| **Location** | Location name. |
| **Account** | Buyer account name. |
| **Requested Ship Date** | Requested ship date. |
| **Ship Window** | Time fence window. |
| **Result Type** | Final classification for this shipment. See result type values below. |
##### **Results View — Result Type Values**
| **Result Type** | **Meaning** |
| :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **Pegged to a PO (New)** | A newly created future shipment was produced by releasing this backorder shipment against an incoming PO. |
| **Ready Shipment (New)** | A newly created Ready shipment produced by releasing this backorder against current on-hand inventory. |
| **Remain in Backorder with Partial Release** | Some lines were released, producing new shipments; remaining lines stay in backorder. Can result from a line-item or quantity split. |
| **No change** | The shipment remained fully in backorder with no inventory allocated during this run. |
***
### **Shipment Detail Panel**
Clicking any row in **Shipments · Future** or **Shipments · Backorder** opens the Shipment Detail Panel — a side drawer that provides a full breakdown of a single shipment's evaluation context, outcome, and line-level detail. The panel is read-only.
The panel layout and fields are consistent across both tabs, with minor differences in outcome terminology between future and backorder contexts.
#### **Panel Header**
| **Element** | **Description** |
| :------------------------- | :------------------------------------------ |
| **Shipment #** | Shipment identifier. |
| **Order #** | Associated order number. |
| **Line count** | Total number of line items in the shipment. |
| **Location** | The location the shipment is assigned to. |
| **Allocation state badge** | Current allocation state of the shipment. |
#### **Overview Tab**
The Overview tab provides a summary of the shipment's evaluation context and outcome, organized into four blocks:
##### **Status Block**
| **Field** | **Description** |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Affected chip** | A chip indicating the shipment was affected by the rebalancing run. |
| **Reason-code chip** | A machine-readable reason code describing what happened to the shipment during the run (for example, `re-peg-on-slip`, `moved-to-backorder`, `gain-on-release`). The text is data-driven from the Rule Snapshot API — never hardcoded. |
| **Plain-English explanation** | A one-line description of the outcome in plain language, generated from the reason code. |
##### **Identity & Current State Block**
| **Field** | **Description** |
| :--------------------- | :----------------------------------------------------------------------- |
| **Order number** | The sales order number associated with this shipment. |
| **Location** | The fulfillment location. |
| **Customer / Account** | The buyer account name. |
| **Ship window** | The time fence window (requested ship date ± time fence days). |
| **Allocation state** | The current allocation state of the shipment (Future, Backorder, Ready). |
| **Fulfillment type** | The fulfillment type (for example, Direct Ship, Delivery). |
| **Line items** | Total number of line items. |
| **Total units** | Sum of all unit quantities across line items. |
##### **Outcome Block**
Shows the original shipment and every shipment that resulted from the run:
| **Entry** | **Description** |
| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **THIS** | The original demand shipment evaluated by the run, with its unit quantity. |
| **NEW** | Every resulting shipment created from this shipment during the run (re-pegged shipments, backorder shipments, ready shipments), each tagged with NEW and its unit quantity. |
For shipments that were not split — for example, a shipment fully re-pegged as a whole or fully moved to backorder — the Outcome block still shows a one-line summary rather than an empty state. For example: *"Original demand #1163 · 420 units — Fully re-pegged into one shipment"* or *"Moved to Backorder (Fully)."*
##### **Triggered by These Changes Block**
Lists every supply or demand change event that caused this shipment to be evaluated during the run:
| **Field** | **Description** |
| :----------------------- | :------------------------------------------------------------------------ |
| **Change type** | Supply or demand change (for example, PO date slip, Cancellation). |
| **PO / Order reference** | The External ID of the future inventory record or the order number. |
| **Location** | The location of the affected inventory. |
| **Before → After** | The delta — what changed (date moved, quantity reduced, order cancelled). |
**Note:** For shipments on the **Shipments · Backorder** tab, the Triggered by these changes block can include both Supply events (PO date slip, PO quantity drop) and Demand events (Cancellation) — unlike the Future tab where only Supply events apply.
***
#### **Lines Tab**
The Lines tab provides a line-by-line breakdown of every item in the shipment, including the supply source assigned to each line.
##### **Lines Tab Columns**
| **Column** | **Description** |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Line #** | The line item number within the shipment. |
| **Line Item ID** | The product UPC or SKU identifier. |
| **Supply Source** | The PO reference (External ID) of the future inventory record the line is pegged to. For backorder shipments released from on-hand inventory, this shows the on-hand inventory record. |
| **Supply Date** | The expected delivery date of the pegged PO — the date the supply is expected to arrive at the location. |
##### **Summary Chips**
Summary chips at the top of the Lines table (for example, "2 re-pegged," "2 unchanged," "126 units re-pegged") also act as clickable filters. Clicking a chip filters the Lines table to show only the lines matching that outcome category.
# API Best Practices
Source: https://docs.kibocommerce.com/pages/api-best-practices
Kibo recommends some best practices when interfacing with the Kibo Composable Commerce Platform (KCCP) APIs to improve system efficiency and minimize potential problems such as server load and slow performance. Your tenant should be set up to follow these guidelines for the best KCCP experience.
This guide explains the request rate limiting that is enforced by the platform as well as additional best practices for interacting with the APIs.
## Rate Limiting
You should self-manage your own tenant to avoid overburdening the KCCP system and negatively impacting performance for all other users. This is enforced by Kibo's rate limiting rules, which will reject requests from any tenants that are submitting too many requests to certain API routes within a given time frame.
In the sandbox environment, all tenants are grouped together under the same rate limits. If one tenant reaches the limit, then requests on all sandboxes will be rejected. However, tenants are rate limited separately in production environments. If one production tenant reaches a limit, then the restriction will only affect that specific tenant. Rate limits for staging and pre-prod environments also apply per tenant just like production tenants. Rate limits for sandbox, pre-prod, performance testing, and production do not affect each other and are counted separately.
### HTTP Response
The maximum limit can vary depending on the route and is distributed across your entire tenant at any given time. When this limit is reached, subsequent requests will be rejected with an HTTP 429 "Too Many Requests" status code:
```
HTTP/1.1 429 Too Many Requests
Date: Fri, 3 May 2022 00:19:56 GMT
Content-Length: 0
Connection: keep-alive
Server: nginx/1.15.8
Retry-After: 60
x-vol-correlation: faac10ae0c224fa089bf6b1fe6305c5a
```
At this point you should wait before submitting any more requests because the system will reject them until the time has elapsed. The time you should wait is indicated in the response header:
| Response Header | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Retry-After | The remaining rejection time, or the amount of seconds you should wait before placing another request. Values will be 60, 900, 1800, 2700, or 3600 which correspond to 1 minute, 15 minutes, 30 minutes, 45 minutes, and 60 minutes. |
### Acceptable Request Rate
You can determine an acceptable rate of requests by finding the rule that best matches the API route and dividing the rule's *limit* by the *time period*. All applications or client code that make a request to an API route with a matching rule must self-manage their request rate to stay at or below the limit to avoid receiving an HTTP 429 error.
For example, if a rule for an API has a limit of 100 requests per minute (RPM) and 2,000 requests per hour (RPH) then the maximum number of requests allowed is 100 per minute and 2000 per hour.
If your requests are being rejected by KCCP, then your application or client code must wait for the restriction time to expire (per the Retry-After header) and then lower the rate of requests to avoid hitting the limit again.
#### Minute vs. Hourly Limiting
Limits on a given rule are applied per minute and per hour. A single request to the KCCP system will count against both the minute and hourly limit for the matching rule. For the examples below, assume the rule is an API with limits of 100 requests per minute (RPM) and 2,000 requests per hour (RPH).
Minute limits count the number of requests in a single minute. If 120 requests are made in 60 seconds, then the system will begin restricting requests on the 101st attempt and return HTTP 429 responses for all further requests until the wait time has expired. Once the next minute begins, the per-minute limit is reset and requests will be accepted unless the rate limit is reached again.
Hourly limits operate on a rolling 60-minute window, which is broken down into four 15-minute buckets. Starting from the first request, the system counts the number of requests in 15-minute buckets. For example, if 100 requests per minute (RPM) come in for 20 minutes then the system will reject any further requests for up to 45 minutes since the entire hourly limit was used. For another example, if exactly 30 requests per minute (RPM) come in during the first 45 minutes of an hour but the final 15 minutes increase to 100 RPM, then the system will reject further requests for up to 15 minutes once the rate limit is reached. After this time expires, requests will be accepted again unless they continue to exceed the rate limit. After being rejected once, the hourly limit will be applied in continuous 15-minute increments until the limit is no longer exceeded within the last 60 minutes.
#### Burst vs. Sustained Requests
Burst requests are allowed within the rate limits, but keep in mind that you cannot sustain the maximum per-minute rate if the hourly rate does not allow it.
For example, if the rule for an API has limits of 100 requests per minute (RPM) and 2,000 requests per hour (RPH) then the system will allow bursts of up to 100 RPM until the hourly rate limit is reached. In this example, an application or client code could send 100 RPM for up to 20 minutes before being restricted for up to 60 minutes. Since the total hourly rate limit only supports up to 20 minutes of burst spread over the entire hour, it's important not to use the entire hourly rate limit too quickly.
The ability to burst requests may vary by rule, so review both the minute and hourly rate limits before choosing the request rate your application or client code will send.
### Determining Your Rate Limits
View the exact rate limits for your tenants and their current statuses per API route in the [Dev Center](/pages/dev-center-and-your-local-environment), under **Api** > **Limits**. This page displays one table for all sandboxes associated with your developer account and additional tables for each production tenant. If you are currently operating within the rate limit for a particular API route, then "OK" will be displayed in green. If you exceed the limit and requests are currently being restricted, then "Throttled" will be displayed in red instead.
If there are no rate limits applied to your developer account, then all sandbox will be "Under Limit" and the production tenant table(s) will say "No rate limits are assigned for this tenant."
Reference the tables below for more details about the rate limits in different environments.
### Non-Peak Hours
Certain hours of the day have higher limits in production to support processing jobs and updates when the load is low. For example, requests to Catalog Admin under the /api/commerce/catalog/admin/\* route have higher limits overnight during non-peak hours and lower limits during the daytime or peak hours.
If you are running bulk inventory operations such as large-scale deletions, scheduling them during non-peak hours maximizes your available rate limit budget. See [Bulk Inventory Deletion](/pages/bulk-inventory-deletion) for a complete guide to self-throttling and batch sizing for inventory delete operations.
US non-peak hours are 5:00 UTC—11:00 UTC (0:00 CDT—6:00 CDT, 23:00 CST—5:00 CST).
EU non-peak hours are 22:00 UTC—4:00 UTC (0:00 CEST—6:00 CEST, 23:00 CET—5:00 CET).
Non-peak hours are calculated in UTC so it is highly recommended to schedule any jobs in UTC and not a local time zone. This will prevent Daylight Saving Time from moving the start and end time.
### Rate Limits by Environment
The tables in this section indicate the routes that are currently rate limited per environment. Reference them to determine how to use the Kibo Composable Commerce Platform APIs while staying within the rate limits.
There may be limits to the physical infrastructure that may restrict the maximum number of requests that can be sent to a given endpoint. Kibo reserves the right to apply additional or different rate limits to ensure platform stability in the case of unreasonable or abusive API activity.
#### Sandbox
Sandbox rules are applied per developer account and will count requests to all sandboxes. Rate limits will also apply to all sandboxes under the developer account.
| Route | HTTP Methods | RPM | RPH | Notes |
| -------------------------------------------- | ----------------- | --- | ----------------------- | ------------------------------------------------------------------------------------------------- |
| /api/platform/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | This does not include dev/app authtickets as they don’t currently support rate limiting. |
| /api/platform/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count. |
| /api/commerce/catalog/admin/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | - |
| /api/commerce/catalog/admin/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count. |
| /api/commerce/inventory/v5/inventory/refresh | POST | 50 | 200 (3.33 average RPM) | This API adds to a shared queue so it is limited to avoid backing up the queue for all sandboxes. |
| /api/commerce/inventory/v5/inventory/adjust | POST | 50 | 200 (3.33 average RPM) | This API adds to a shared queue so it is limited to avoid backing up the queue for all sandboxes. |
| /api/commerce/inventory/\* | - | 500 | 10000 (166 average RPM) | Excludes any more specific rules. |
| /api/commerce/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | Excludes any more specific rules. |
| /api/commerce/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count and any more specific rules. |
| /api/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | Excludes any more specific rules. |
| /api/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count and any more specific rules. |
| /\* | - | 500 | 10000 (166 average RPM) | Storefront and general catch-all rule. Excludes any more specific rules. |
#### Pre-Prod
Pre-Prod currently has very similar rules and rate limits as sandbox. However, pre-prod rules are applied per tenant so one pre-prod tenant will not affect another pre-prod tenant
| Route | HTTP Methods | RPM | RPH | Notes |
| ------------------------------ | ----------------- | --- | ----------------------- | ---------------------------------------------------------------------------------------- |
| /api/platform/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | This does not include dev/app authtickets as they don’t currently support rate limiting. |
| /api/platform/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count. |
| /api/commerce/catalog/admin/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | - |
| /api/commerce/catalog/admin/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count. |
| /api/commerce/inventory/\* | - | 500 | 10000 (166 average RPM) | Excludes any more specific rules. |
| /api/commerce/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM) | Excludes any more specific rules. |
| /api/commerce/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count and any more specific rules. |
| /api/\* | POST, PUT, DELETE | 500 | 10000 (166 average RPM | Excludes any more specific rules. |
| /api/\* | - | 500 | 10000 (166 average RPM) | Excludes POST, PUT, DELETE rule count and any more specific rules. |
| /\* | - | 500 | 10000 (166 average RPM) | Storefront and general catch-all rule. Excludes any more specific rules. |
#### Performance Testing
The Performance Testing environment has a very simple set of rules. When inactive, the limits are very low to not impact any other clients actively using the environment. Please stay within the rate limits and do not do any performance testing or a large number of requests if you are not currently scheduled to use the performance test environment.
| Route | HTTP Methods | RPM | RPH | Notes |
| ---------------------------------- | ------------------------------------------------------------------------ | ------------ | --- | ----- |
| /api/\* | - | Default: 100 | | |
| Active: 10000 | Default: 2000 (33.33 average RPM) | | | |
| Active: 600000 (10000 average RPM) | API catch-all rule. | | | |
| /\* | - | Default: 100 | | |
| Active: 10000 | Default: 2000 (33.33 average RPM) | | | |
| Active: 600000 (10000 average RPM) | Storefront and general catch-all rule. Excludes any more specific rules. | | | |
#### Production
Production tenants are not rate limited. However, to ensure overall platform stability Kibo may apply rate limit rules to a production tenant to limit unreasonable or abusive API activity.
## Other Best Practices
Although rate limiting is important, there are additional best practices that can help improve the overall performance of your tenant.
### Use Import Export APIs and Analytic Reporting
Leverage the [Import/Export APIs](/api-overviews/openapi_importexport_overview) for any large-scale transactional data read/write activities. For historical data, leverage the [analytic reporting system](/pages/reporting-overview). The individual REST APIs are intended to support transactional activity and/or asynchronous data synchronization.
### Use Bulk APIs
If a bulk API is available, such as for querying or updating inventory, then it is best to use that API instead of submitting individual requests for one item at a time.
Some bulk APIs have their own restrictions about the amount of data that should be submitted with one request. For example, the Inventory Adjust API only accepts up to 1,000 items per call while the Inventory Refresh API can accept up to 12,000. However, Kibo recommends making refresh calls with 3,000 items for optimal performance. These limitations are indicated in the [API documentation](/api-overviews/openapi_overview_overview) or [API-specific context guides](/api-overviews/getting-started) where applicable for a specific API.
### Use the Right Service
Don't call internal APIs from your Arc actions or applications that aren't designed for it. For example, the [Catalog Storefront APIs](/api-overviews/openapi_catalog_storefront_overview) are designed to support the heavy load of the storefront but the [Catalog Administration APIs](/api-overviews/openapi_catalog_admin_overview) are not. You should use the appropriate service for your situation when interacting with their Product APIs to ensure a better response time and avoid failures.
### Delay Before Retrying
If the responses are not returning the HTTP 200 OK status code (such as HTTP 500 or [another error instead](/pages/status-codes)), you should add some delay before attempting the request again. Consider using exponential backoff or another strategy instead of retrying immediately.
### Limit Response Data
Use the response fields to limit the amount of data returned by API calls, especially when performing queries such as searching for products. Query-string parameters such as page and pageSize (up to a maximum of 200 records per request) can be used to retrieve large amounts of data in digestible chunks. These parameters are always defined in the API documentation for a call that supports them, such as the example [Get Products](/api-reference/products/get-products) call.
You can also compress the response data to improve API performance when returning large payloads. Kibo supports the following compression formats:
* [Brotli](https://github.com/google/brotli)
* [Gzip](https://www.gnu.org/software/gzip/manual/)
* Default compression
Send the Accept-Encoding HTTP header with the preferred compression type(s) to enable it for the API response, such as `Accept-Encoding: br, gzip, deflate`. After receiving the response, decompress it to access the full data.
### Use Fewer Filters
Though limiting and filtering the response data is useful, it can also be harmful to implement too much complex filter logic. When calling any API with a set of filters, take care to not include too many conditions. While a small set of filters is useful to fine-tune the result set, using a larger number such as 100 "AND" conditions will negatively impact the performance of the query.
## Inform Kibo of Expected Traffic
If you have planned promotional activities that may result in a significant increase to server traffic and/or API requests in a short period of time (such as television campaigns, publicity events and sponsorships, email marketing campaigns, or widely advertised sales), Kibo recommends the following best practices:
* Do not send out a major email or text campaign to everyone in a large audience at the exact same time. Instead, space your emails and texts out over a period of time (1-2 hours).
* Send your emails and texts at a time that does not already have high traffic. For instance, most sites see a steady increase in traffic from 7am to 11am Central, so we would recommend that you do not send out an email campaign to several million customers at 8:30am.
* Please read and understand the rest of our best practices for API processes above.
Doing the above will ensure the system can best scale on its own to meet your needs and avoid potential problems. In the event that a large spike or increase in traffic or API requests cannot be avoided, please notify [Kibo Support](https://help.kibocommerce.com/). Include the planned promotional activities, their date/time and duration, and the expected impact such as:
* The reach of the campaign
* The percentage increase of traffic expected from your site
* The expected order volume increase compared to the baseline for your tenant
Support will work with the developer teams to ensure Kibo has the resources in place to support the increase in traffic to your tenant without being surprised by unexpected system load and negatively affecting performance. Note that scaling resources will occur only for your tenant, not on a site-by-site or regional basis.
# API Extension Examples
Source: https://docs.kibocommerce.com/pages/api-extension-examples
Use the examples in this topic as a reference point for developing your own custom functionality using API Extensions.
## Customer Normalization
This API Extension application limits unnecessary accounts from being created for the same shopper. When a shopper checks out on your site, API Extensions check whether the shopper's email address is already associated with an existing customer account, and then handles the shopper's account based on the following scenarios:
When a shopper decides to check out as a guest:
* If their email address is not associated with an existing customer account, a new anonymous account is created.
* If their email address is associated with an existing anonymous customer account, the new order is associated with the existing anonymous account.
* If their email address is associated with an existing registered shopping account, then a new anonymous customer account is created with all the previously existing customer attributes of the existing registered account.
When a shopper decides to check out as a registered shopper:
* If their email address is not associated with an existing customer account, a new registered account is created.
* If their email address is associated with an existing anonymous customer account, the new order is associated with the existing anonymous account, but the anonymous account is converted into a registered shopper account.
* If their email address is associated with an existing registered shopping account, then the shopper is logged into the existing registered account.
### Notable Files in the API Extension Assets
The assets for the customer normalization application are [available on GitHub](https://github.com/Mozu/customer-normalization). The following table lists the notable files that make the application work. You can customize these files to suit your needs.
| File Name | Description |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [cnAddAccountAndLoginBefore.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/domains/commerce.customer/cnAddAccountAndLoginBefore) | |
| [cnAddAccountBefore.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/domains/commerce.customer/cnAddAccountBefore) | |
| [cnUpdateAccountBefore.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/domains/commerce.customer/cnUpdateAccountBefore) | These files execute API Extension functions before registered or anonymous customer accounts are created or updated. |
| [customerservice.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/domains/customerservice) | This file contains the main functions of the application. These functions define what the application does in response to the different customer account scenarios. |
| [embedded.platform.applications.install.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/domains/platform.applications/embedded.platform.applications.install) | This file provides the installation configuration for the application. |
| [commerce.customer.manifest.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/commerce.customer.manifest) | |
| [platform.applications.manifest.js](https://github.com/Mozu/customer-normalization/blob/master/assets/src/platform.applications.manifest) | These manifest files define the relationships between API Extension actions, the functions they execute, and their configured name. |
### Installation
Create an application in Dev Center to house the customer normalization assets:
1. In your Dev Center Console, click **Develop** > **Applications**.
2. Click **Create Application**.
3. Specify whatever name you wish and click **Save**. You should now see your application in the Applications grid.
4. Double-click your new application to view it.
5. Note the **Application Key**. You will need this value to authenticate your customer normalization assets.
Configure and install the customer normalization assets:
1. Clone or download the `customer-normalization` repository [available on GitHub](https://github.com/Mozu/customer-normalization). If you want to allow customers to checkout as a guest using an email address that is associated with a registered user, set the `enableAnonymousAndRegistered` variable to `true` in all files that use the variable. By default, the files that use this variable are `assets/src/domains/platform.applications/embedded.platform.applications.install.js` and `assets/src/domains/customerservice.js`.
2. In the root directory of the cloned assets, create a file called `mozu.config.json`. Specify your application configuration data within this file, as shown in the following code block, replacing the placeholder values with your application-specific values.
```
{
"baseUrl": "https://t00000.sandbox.mozu.com",
"developerAccountId": 1234,
"developerAccount": {
"emailAddress": "you@email.com"
},
"workingApplicationKey": "yourApplicationKey"
}
```
3. In the root directory, open a command prompt and run `npm install` to install project dependencies.
4. After dependencies install successfully, enter `grunt` to upload the assets to your Dev Center application.
5. Return to Dev Center to view your application.
6. To confirm that the assets uploaded successfully, navigate to the **Packages** tab and click **Assets**.
7. Install the application to the sandbox of your choice.
## Add New Customers to a New Customers Segment
This function uses an HTTP action to add all new customers to a new customers segment.
To use this example:
1. In Admin, use the Customers module to create a new customer segment called "New Customers".
2. Use the Yeoman Generator to scaffold an application that includes the `http.commerce.customer.accounts.addAccountandLogin.after` action.
3. Code the `http.commerce.customer.accounts.addAccountandLogin.after.js`file as shown in the following code block:
```
var _ = require('underscore');
var CustomerSegmentFactory = require('mozu-node-sdk/clients/commerce/customer/customerSegment');
module.exports = function (context, callback) {
var customerSegmentResource = CustomerSegmentFactory(context.apiContext);
customerSegmentResource.context['user-claims'] = null;
//console.info("Hello from Add Account and Login!");
//console.info("Request...");
//console.info(context.request.body);
//console.info("Response...");
//console.info(context.response.body);
//console.info(context.response.body.customerAccount);
var account = context.response.body.customerAccount;
customerSegmentResource.getSegments({ filter: "name eq 'New Customers'" })
.then(function (segmentCollection) {
if (_.first(segmentCollection.items)) {
var newCustomerSegment = _.first(segmentCollection.items);
var accountId = [account.id];
return customerSegmentResource.addSegmentAccounts({id: newCustomerSegment.id}, {body: accountId});
}
})
.then(function() {
//console.info("Successfully added " + account.firstName + " " + account.lastName + " to the New Customers segment.");
callback();
})
.catch(function(err) {
console.error(err);
callback();
});
};
```
4. Run `grunt` to upload the assets.
5. Install the application to your sandbox.
Ideas to expand on this function include applying discounts to the New Customers segment, automatically removing customers from the segment after a specified period of time, or only adding customers to the segment if they opt in to receive promotional material during the checkout process.
## Limit Cart Items of the Same Product Type
This function uses an embedded action to limit how many items of the same product type can be added to the cart. The product type to be limited is read from configuration data set in the Action Management JSON Editor. Whenever an item cannot be added to the cart, the function logs an error message to the `data` array on the cart object.
To use this example:
1. Use the Yeoman Generator to scaffold an application that includes the `embedded.commerce.carts.addItem.before` action.
2. Code the `embedded.commerce.carts.addItem.before.js`file as shown in the following code block:
```
var _ = require('underscore');
module.exports = function (context, callback) {
var cart = context.get.cart();
var cartItem = context.get.cartItem();
var cartProductTypes = [];
var oneTypePerCart = context.configuration.oneTypePerCart;
console.info(cart);
console.info(cartItem);
if(cart.items.length > 1) {
for(var i = 0; i < cart.items.length; i++) {
//console.info("Cart Item #" + (i + 1));
//console.info(cart.items[i].product.name);
//console.info(cart.items[i].product.productType);
if (cartItem.id !== cart.items[i].id) {
cartProductTypes.push(cart.items[i].product.productType);
}
}
}
var cartItemProductType = cartItem.product.productType;
//console.info("Cart Item To Add:");
//console.info(cartItem.product.name);
//console.info(cartItemProductType);
if(cartItemProductType == oneTypePerCart && _.contains(cartProductTypes, cartItemProductType)) {
//console.info("Removing cart item...");
var itemsToRemove = [];
_.each(cart.items, function(item) {
if(item.product.productType == cartItemProductType) {
itemsToRemove.push(item);
}
});
try{
if(itemsToRemove.length > 0) {
var itemToRemove = _.first(itemsToRemove);
var errorMessage = itemToRemove.product.name + " has been removed from your cart. You can have only one item of the type " + oneTypePerCart + " in your cart at a time.";
context.exec.removeItem(itemToRemove.id);
//console.info("Removed the following item: ");
//console.info(itemToRemove.product.name);
context.exec.setData("removedItemMessage", errorMessage);
context.exec.setData("removedItemId", itemToRemove.product.productCode);
}
} catch(err) {
console.error(err);
}
}
callback();
};
```
3. In Admin, go to **System** > **Customization** > **API Extensions** to open the Action Management JSON Editor.
4. Add configuration data to specify which product type should be limited to only one item per cart. For example, the following code block designates the `"Hazardous"` product type as the type to limit.
```
{
"actions": [
{
"actionId": "embedded.commerce.carts.addItem.before",
"contexts": [
{
"customFunctions": [
{
"applicationKey": "yourApplicationKey",
"functionId": "embedded.commerce.carts.addItem.before",
"enabled": true
}
]
}
]
},
],
"configurations": [
{
"applicationKey": "yourApplicationKey",
"configuration": {
"oneTypePerCart": "Hazardous"
}
}
],
"defaultLogLevel": "info"
}
```
The preceding example shows the `oneTypePerCart` configuration data at the application-level, which makes it accessible to every action in your application. If you want to limit the configuration data to one action (for a clearer organization or to reuse variable names with different values, for example), you can place the data within the appropriate `customFunctions` array. For more information about the JSON configuration options, refer to the [Action Management JSON Editor](/pages/action-management-json-editor) topic.
5. Run `grunt` to upload the assets.
6. Install the application to your sandbox.
Ideas to expand on this function include limiting specific product combinations in the cart (instead of product types), allowing Admin users to specify prohibited combinations in the Action Management JSON Editor, and leveraging your theme to expose the message in the cart data during the checkout process so that shoppers know why they can't add a particular item.
## Validate Purchase Orders During the Checkout Process
This function uses an embedded action to augment the purchase order feature. With this function, you can communicate with your ERP system to validate a purchase order in the following ways:
* Set the payment term based on the shopper's shipping address and PO number.
* Display an error to the shopper if they enter an invalid PO number.
* If a customer account is not in good standing, display an error to the shopper informing them that they cannot use purchase orders as a payment option.
To use this example:
1. [Enable purchase orders](/pages/purchase-orders) as a payment type on your site and then enable the ability for specific customers to use purchase orders during checkout.
2. Use the Yeoman Generator to scaffold an application that includes the `embedded.commerce.payments.action.before` action.
3. Code the `embedded.commerce.payments.action.before.js`file as shown in the following code block. The sample code provided below uses hard-coded values to validate different scenarios. When creating a production application, you would expand on this code to communicate with your ERP system in order to retrieve the correct payment term, validate if a purchase order number is valid, and determine whether a customer account is in good standing.
```
var OrderResourceFactory = require('mozu-node-sdk/clients/commerce/order');
var CustomerResourceFactory = require('mozu-node-sdk/clients/commerce/customer/accounts/customerPurchaseOrderAccount');
module.exports = function(context, callback) {
var purchaseOrderNumber = context.get.payment().billingInfo.purchaseOrder.purchaseOrderNumber;
var payment = context.get.payment();
var orderId = context.get.payment().orderId;
var orderResource = OrderResourceFactory(context.apiContext);
var customerPurchaseOrderAccountResource = CustomerResourceFactory(context.apiContext);
/***** Set the payment term based on the shipping address and PO# *****/
orderResource.getOrder({ orderId: orderId})
.then(function (order) {
var address = order.fulfillmentInfo.fulfillmentContact.address;
// console.info('address :', address);
// In this example the conditions are hard-coded, but you can expand on the code to communicate with your ERP system
if(address.postalOrZipCode == '78750' && purchaseOrderNumber == '123456')
{
var paymentTerm = {
"Code": "30-days",
"Description" : "30 Days"
};
context.exec.setPaymentTerm(paymentTerm);
// console.info('payment after :', context.get.payment());
}
})
.then(function() {
callback();
})
.catch(function(err) {
console.error(err);
callback();
});
/***** Verify that the purchase order is valid *****/
var expectedPurchaseOrderNumber = 123456; // In a real-life scenario, you can check the PO# against your ERP or similar system
if(expectedPurchaseOrderNumber != purchaseOrderNumber)
// Displays an error message to the user on the checkout page
throw new Error('Invalid purchase order number!');
/****** Check whether the customer account is in good or bad standing ********/
var isCustomerFlagged = true; // In a real-life scenario, you can check the account against your ERP or similar system
if(isCustomerFlagged)
// Displays an error message to the user on the checkout page
throw new Error('Your purchase order account is not in good standing. Please use another payment method.');
};
```
4. Run `grunt` to upload the assets.
5. Install the application to your sandbox.
## Set a Tax Response While Short-Circuiting the API Call
This example demonstrates how you can use API Extensions to skip an API call and provide your own response information. Specifically, it does so to calculate tax using a custom function for Minnesota shoppers, while using the default call for everyone else.
To use this example:
1. Ensure you have configured tax settings for your site.
2. Use the Yeoman Generator to scaffold an application that includes the `http.commerce.catalog.storefront.tax.estimateTaxes.before.js` action.
3. Code the `http.commerce.catalog.storefront.tax.estimateTaxes.before.js`file as shown in the following code block:
```
module.exports = function(context, callback) {
//console.info("Start: storefront.tax.estimateTaxes.before");
var taxOrderInfo = context.request.body;
//console.info("request: %j", context.request);
//console.info("request.body: %j", taxOrderInfo);
//console.info("response: %j", context.response);
//console.info("Order #: " + taxOrderInfo.OrderNumber);
// If the condition is met, end the call to skip prevent calling the built-in Mozu route which would otherwise overwrite the custom response.
if (taxOrderInfo.TaxContext.DestinationAddress.StateOrProvince === 'MN') {
calculateMnTax(taxOrderInfo, function (responseBody){
//console.info("%j", responseBody);
context.response.body = responseBody;
context.response.end();
//console.info("Special MN Taxing for this state! Tax State: " + taxOrderInfo.TaxContext.DestinationAddress.StateOrProvince);
callback();
});
} else {
// If the destination is not MN, calculate tax using the default tax engine.
//console.info("Using default Taxing for this state! Tax State: " + taxOrderInfo.TaxContext.DestinationAddress.StateOrProvince);
callback();
}
};
function calculateMnTax(taxOrderInfo, callback) {
var responseBody = {
"itemTaxContexts" : [],
"shippingTax" : 0.00,
"handlingFeeTax" : 0.00,
"orderTax" : 0.00
};
// Make sure to get current tax in order to add it to the total.
var orderTotalTax = 0.0;
// for each
if (taxOrderInfo.LineItems && taxOrderInfo.LineItems.length > 0) {
var itemTaxAmount = 0.00;
for (var i = 0; i < taxOrderInfo.LineItems.length; i++) {
var lineItem = taxOrderInfo.LineItems[i];
//console.info("LineItemPrice: " + lineItem.LineItemPrice);
// Only apply special tax to Minnesota shoppers. Skip tax-exempt
if (!taxOrderInfo.TaxContext.TaxExemptId && lineItem.IsTaxable) {
itemTaxAmount = lineItem.LineItemPrice * 0.10275;
//console.info("Adding a item tax Amount of: " + itemTaxAmount);
} else {
//console.info("Tax exempt customer (or item). TaxID: " + taxOrderInfo.TaxContext.TaxExemptId);
}
responseBody.itemTaxContexts.push({
"id" : lineItem.Id,
"productCode" : lineItem.ProductCode,
"quantity" : lineItem.Quantity,
"tax" : itemTaxAmount.toFixed(2),
"shippingTax" : 0.0
});
orderTotalTax += itemTaxAmount;
}
responseBody.orderTax = orderTotalTax.toFixed(2);
//console.info("End: storefront.tax.estimateTaxes.before. Total Tax = " + orderTotalTax);
}
callback(responseBody);
}
```
## Add Custom Tax Data to an Order
This example demonstrates how to add custom tax data (a random amount for purposes of the example) to orders and order items.
To use this example:
1. Use the Yeoman Generator to scaffold an application that includes the `http.commerce.catalog.storefront.tax.estimateTaxes.after` action.
2. Code the `http.commerce.catalog.storefront.tax.estimateTaxes.after.js`file as shown in the following code block:
```
module.exports = function(context, callback) {
function readAndUpdateTax(target) {
var customTax = Math.random() * 10;
target.CustomTax = parseFloat(customTax.toFixed(2));
}
context.response.body.taxData = context.response.body.taxData || {};
readAndUpdateTax(context.response.body.taxData);
context.response.body.itemTaxContexts.forEach(function(item) {
item.taxData = item.taxData || {};
readAndUpdateTax(item.taxData);
});
callback();
};
```
## Shorten the Duration of Hot Authentication
This example demonstrates how to shorten the duration of hot authentication down to 15 minutes. By default, if shoppers do not log out of the system, they remain under hot authentication for 24 hours (even if they close their browsers). After this period, shoppers enter warm authentication, which means their cart status is saved, but they must re-enter their credentials to check out or access their My Account page. If you wish for shoppers to enter warm authentication quicker than 24 hours, use API Extensions to delete the refresh tokens from their accounts.
To use this example:
1. Use the Yeoman Generator to scaffold an application that includes the `http.commerce.customer.authTickets.createUserAuthTicket.after` action.
2. Code the `http.commerce.customer.authTickets.createUserAuthTicket.after.js`file as shown in the following code block:
```
module.exports = function(context, callback) {
var accessTokens = context.response.body;
accessTokens.refreshToken = "";
context.response.body = accessTokens;
// console.log(context.response.body);
callback();
};
```
## Add/Update Custom Reasons
This API Extension application allows you to customize appeasement and cancellation reasons so that an appropriate list of business reasons will be listed.
Below are steps to create and configure the cancellation reason API Extension on any tenant.
### Installation
Here are the installation steps:
1. Create an application in Dev Center.
* In your Dev Center Console, click **Develop** > **Applications**.
* Click **Create Application**.
* Specify any name you wish and click **Save**. You should now see your application in the Applications grid.
* Double-click your new application to view it.
* Please note the Application Key. You will require this value for authenticating your customer normalization assets.
2. Create an API Extension application for the [`http.commerce.orders.cancellationReasons.after action`](/pages/cancellation-reasons-after)
3. Update the Mozu.config file with the appropriate application key, baseUrl, and developer account details. The sample Mozu.Config for an example site should look like the one below.
```
{
"baseUrl": "[https://example.com](https://example.com/)",
"developerAccountId": 2159,
"developerAccount": {
"emailAddress": "[admin@kibocommerce.com](mailto:admin@kibocommerce.com)"
},
"workingApplicationKey": "dev_center_application_for_cancellation_reason_key(Ex. a0842dd.CustomRefundReasons.1.0.0.Release)",
}
```
4. Add or Update cancellation reasons. The API cancellation is in `context.response.body.items`.
* To append reasons, add your custom reason to `context.response.body.items`. For Example, the below code should add ‘ArrivedTooLate’ reason to API response.
```
var response = context.response.body;
response.items.push({
"reasonCode": "ArrivedTooLate",
"name": "Arrived too late",
"needsMoreInfo": false,
"categories": []
});
```
* To override the API reasons and use different ones, clear the API response and assign a new list of reasons to `context.response.body.items`. For example, the code below should override the API response and provide a completely custom set of cancellation reasons.
```
var response = context.response.body;
response.items = [
{
"reasonCode": "ArrivedTooLate",
"name": "Arrived too late",
"needsMoreInfo": false,
"categories": []
},
{
"reasonCode": "CustomerChangedMind",
"name": "Customer changed mind",
"needsMoreInfo": false,
"categories": []
},
{
"reasonCode": "DamagedOrDefective",
"name": "Damaged or defective",
"needsMoreInfo": false,
"categories": []
}];
```
5. Save the API Extension application and upload it by firing the grunt command. It should upload the application to your DevCenter application.
6. Install the application to the desired tenant.
7. Login into the target tenant from step 6.
8. Navigate to the Applications page (**System** > **Customization** > **Applications**).
9. Search for the cancellation reason application and enable it.
10. Navigate to the Action Management page (**System** > **Customization** > **API Extension Application**) and check if it has an entry for your cancellation reason application, and ensure that it is enabled. The entry should look like the code snippet below. If you don't find any entry, add a script similar to the one below and save it.
```
{
"actionId": "http.commerce.orders.cancellationReasons.after",
"contexts": [
{
"customFunctions": [
{
"applicationKey": "dev_center_application_for_cancellation_reason_key(Ex. a0842dd.CustomRefundReasons.1.0.0.Release)",
"functionId": "http.commerce.orders.cancellationReasons.after",
"enabled": true,
"timeoutMilliseconds": 25000
}
]
}
]
}
```
11. When you invoke the Order, Shipment, or related APIs, it should list the custom reasons from the API Extension application.
# App Support Levels
Source: https://docs.kibocommerce.com/pages/app-support-levels
These classifications describe the level of support Kibo provides for an application.
## Proprietary
* Kibo provides full support for these applications.
* Kibo is solely responsible for the development of these applications.
## Open Source
* Kibo provides full support for these applications assuming no part of the application has been modified (source code, theme, widgets, API Extensions, etc.) and contact [Kibo Support](https://help.kibocommerce.com/) to install these applications.
* The source code for these applications is freely available on GitHub through the Kibo Open Source Model.
Kibo encourages third-party developers to modify these applications so as to provide improvements, add functionality, or fix existing bugs. However, Kibo cannot provide support for modified applications given that the code design is no longer under its control.
* If you make a modification that you want Kibo to support in future releases of the application, you can request that Kibo incorporate your changes into the core application. Kibo will review your changes with the following criteria in mind:
* **Code review**: Is the modification stable, tested, and complete?
* **Feature Enhancement review**: Is the improvement to an existing feature general to all use cases or is it specific to a particular Kibo community member?
* **New Feature review**: Is the new feature useful to other members of the Kibo community?
* **Bug Fix review**: Is the issue being fixed an issue for all members of the Kibo community?
# Apple Pay Configuration
Source: https://docs.kibocommerce.com/pages/apple-pay-configuration
Apple Pay is a digital wallet that can be implemented for eCommerce through [Payment Extensibility](/pages/payment-extensibility). It allows customers to store their credit card information and provide that information to mobile and web eCommerce stores. When Apple Pay is used to retrieve payment information for an order, the customer receives a confirmation notification on their phone to approve the request.
## Validate Website
You must provide your merchant website details to Apple in order to validate your implementation of Apple Pay.
1. Log into your Apple Pay developer account.
2. Go to **Certificates, Identifiers and Profiles**.
3. Click on **Merchant IDs**.
4. Select the Merchant ID for the URL that needs to be validated.
5. Go to the **Merchant Domains** section.
6. Click **Add Domain**.
7. Copy the sandbox or production URL and paste into the "Your domain name" field.
8. Download the `apple-developer-merchantid-domain-association.txt file`
9. Log into your sandbox or production eCommerce instance.
10. Go to **Main** > **Content** > **Files**.
11. Upload the `apple-developer-merchantid-domain-association.txt` file.
12. After the file is uploaded, click on the menu option to get the URL.
13. Copy the URL from the CMS to end – ex : `cms/files/914bdca4-46b0-4684-a375-5c50e87c6f41`
14. Go to **Main** > **Redirects**.
15. Add a redirect and enable rewrite.
* **Source:** `.well-known/apple-developer-merchantid-domain-association.txt`
* **Target:** `cms/files/914bdca4-46b0-4684-a375-5c50e87c6f41`
16. Go back to the Apple Developer account screen and click **Verify**.
## Merchant Identity Certificate
This certificate identifies your merchant with Apple Pay and must be submitted in the Payment Gateway Settings menu of eCommerce.
1. Log into your Apple Pay developer account.
2. Go to **Certificates, Identifiers and Profiles**.
3. Click on **Merchant IDs**.
4. Select the Merchant ID for the URL that needs to be validated.
5. Go to the **Apple Pay Merchant Identity Certificate** section.
6. Click on **Create Certificate**.
7. Follow the instructions provide by Apple.
8. Once the certificate is created, export the P12 or PFX file from the system.
9. Convert the P12 or PFX to PEM form containing both a public and private key. You can choose to encrypt the private key with a password.
10. Copy the contents of the PEM file to the Merchant Identity Certificate field on the Apple Pay Configuration screen.
11. Enter the password if the private key is encrypted.
## Apple Pay Processing Certificate
The Apple Pay Processing Certificate is also referred to as the "Decryption Certificate" in the Payment Gateway Settings menu of eCommerce. You may provide the certificate if you want eComm to decrypt the token and pass it to the processing gateway, but it is not necessary to provide when configuring the Apple Pay adapter.
1. Log into your Apple Pay developer account.
2. Go to **Certificates, Identifiers and Profiles**.
3. Click on **Merchant** **IDs**.
4. Select the Merchant ID for the URL that needs to be validated.
5. Go to **Apple Pay Payment Processing** **Certificate**.
6. Click on **Create Certificate**.
7. If using a processing gateway such as Cybersource for processing the Apple Pay token, follow the steps provided by your processing gateway.
> **OMS-only with CyberSource:** No additional configuration is required. The system receives an authorized token from Apple Pay and uses it directly for capture.
# Apple Pay Integration
Source: https://docs.kibocommerce.com/pages/apple-pay-integration
Apple Pay is a digital wallet that can be implemented for eCommerce through [Payment Extensibility](/pages/payment-extensibility). It allows customers to store their credit card information and provide that information to mobile and web eCommerce stores. When Apple Pay is used to retrieve payment information for an order, the customer receives a confirmation notification on their phone to approve the request.
## Validate Website
You must provide your merchant website details to Apple in order to validate your implementation of Apple Pay.
1. Log into your Apple Pay developer account.
2. Go to **Certificates, Identifiers and Profiles**.
3. Click on **Merchant IDs**.
4. Select the Merchant ID for the URL that needs to be validated.
5. Go to the **Merchant Domains** section.
6. Click **Add Domain**.
7. Copy the sandbox or production URL and paste into the "Your domain name" field.
8. Download the `apple-developer-merchantid-domain-association.txt file`
9. Log into your sandbox or production eCommerce instance.
10. Go to **Main** > **Content** > **Files**.
11. Upload the `apple-developer-merchantid-domain-association.txt` file.
12. After the file is uploaded, click on the menu option to get the URL.
13. Copy the URL from the CMS to end – ex : `cms/files/914bdca4-46b0-4684-a375-5c50e87c6f41`
14. Go to **Main** > **Redirects**.
15. Add a redirect and enable rewrite.
* **Source:** `.well-known/apple-developer-merchantid-domain-association.txt`
* **Target:** `cms/files/914bdca4-46b0-4684-a375-5c50e87c6f41`
16. Go back to the Apple Developer account screen and click **Verify**.
## Merchant Identity Certificate
This certificate identifies your merchant with Apple Pay and must be submitted in the Payment Gateway Settings menu of eCommerce.
1. Log into your Apple Pay developer account.
2. Go to **Certificates, Identifiers and Profiles**.
3. Click on **Merchant IDs**.
4. Select the Merchant ID for the URL that needs to be validated.
5. Go to the **Apple Pay Merchant Identity Certificate** section.
6. Click on **Create Certificate**.
7. Follow the instructions provide by Apple.
8. Once the certificate is created, export the P12 or PFX file from the system.
9. Convert the P12 or PFX to PEM form containing both a public and private key. You can choose to encrypt the private key with a password.
10. Copy the contents of the PEM file to the Merchant Identity Certificate field on the Apple Pay Configuration screen.
11. Enter the password if the private key is encrypted.
## Apple Pay Processing Certificate
The Apple Pay Processing Certificate is also referred to as the "Decryption Certificate" in the Payment Gateway Settings menu of eCommerce. You may provide the certificate if you want eComm to decrypt the token and pass it to the processing gateway, but it is not necessary to provide when configuring the Apple Pay adapter.
1. Log into your Apple Pay developer account.
2. Go to **Certificates, Identifiers and Profiles**.
3. Click on **Merchant** **IDs**.
4. Select the Merchant ID for the URL that needs to be validated.
5. Go to **Apple Pay Payment Processing** **Certificate**.
6. Click on **Create Certificate**.
7. If using a processing gateway such as Cybersource for processing the Apple Pay token, follow the steps provided by your processing gateway.
# Application Asset Management
Source: https://docs.kibocommerce.com/pages/application-asset-management
You manage application assets in the Application Editor, which contains the following tabs.
* **Core:** This tab displays all metadata associated with your application and all the sandboxes where the application has been installed. Application metadata is shared with all packages.
* **Packages:** This tab displays configuration options specific to an application package. You can create individual packages so multiple developers can work on the same application. Package configurations are not shared between packages. You must download application files from each package and merge them using your own source control system. Refer to [Applications](/pages/applications-1a6c791-introduction) for more information about configuration options. The Release package is created by default when you create an application and cannot be deleted.
* **Release Notes:** This tab displays release notes for a selected package. You can add notes to record changes, describe development workflows, or provide instructions for working with applications.
Make sure you’ve selected the correct package before you start making changes so that you don’t overwrite another developer’s package configuration.
At the top of all Application Editor pages is a dashboard that displays important information about your application, such as:
* Status
* Version
* API version
* Application key
* Shared secret
* Active package
Kibo uses an application key and shared secret for authenticating your application. The application key is composed of four elements: `<_Dev Account namespace_>` . `<_Application ID_>` . `<_Version number_>` . `<_Release package_>`. The dashboard lets you show or hide the shared secret.
The credentials described above apply to the original (V1) security model, in which a single application key and shared secret are used everywhere. Apps that use the enhanced (V2) security model manage environment-specific credentials instead. See [Application Credentials and Security](#application-credentials-and-security) for details.
When you’re finished testing a custom application, you must submit it to Kibo for the certification process. Only certified applications can be deployed to a production tenant.
## Application Credentials and Security
**V1 security is being deprecated.** All applications will need to move to the V2 security model for enhanced security. Existing V1 applications continue to work for now, but you should plan to [upgrade to V2](#upgrade-an-application-to-v2) and rotate your credentials. New applications should adopt V2 from the start.
Kibo supports two security models for applications.
| | V1 (original) | V2 (enhanced) |
| ----------------- | -------------------------------------------- | ----------------------------------------------- |
| Credentials | One application key and shared secret | Separate credentials per environment |
| Secret visibility | Always visible in Dev Center | Shown once when generated |
| Environments | Same secret for Sandbox and Production | Sandbox and Production credentials are separate |
| Key rotation | Not supported without disrupting connections | Multiple active keys; rotate with zero downtime |
| Webhook signing | Uses the shared secret | Uses a dedicated webhook signing secret |
After an app is upgraded, its **Security Model** shows **V2** in the Application Editor dashboard, and a **Credentials** tab is added where you manage environment-specific auth keys and webhook secrets.
### Environment-Separated Credentials
In the V2 model, an application has distinct authentication keys for each environment, managed on separate tabs in the **Credentials** view:
* **Production Auth Keys** authenticate only against Production tenants.
* **Sandbox Auth Keys** authenticate only against Sandbox tenants.
Because the credentials are separate, a developer who has access to Sandbox credentials does not automatically have Production credentials. This lets you give teams the access they need without exposing production systems.
### Application Key vs. Client ID
A V2 application uses two related identifiers:
* **Application Key (App ID):** The immutable identifier for the app (for example, `kadmin1.AppTest.1.0.0.Release`). It never changes and is used for logging, reporting, and permissions.
* **Client ID:** The identifier for a specific credential. Each credential has its own Client ID that can be rotated or revoked independently. The Client ID is formed by prefixing the key's name to the Application Key, for example `NewKey.kadmin1.AppTest.1.0.0.Release`. The environment a credential belongs to is shown in its own column and by the Production and Sandbox tabs, rather than in the Client ID itself.
Usage reporting always aggregates by Application Key, regardless of which Client ID was used to authenticate.
### Upgrade an Application to V2
When you are ready to adopt the enhanced security model, use the **Upgrade to V2** action in the Enhanced Security Available banner on the application's **Core** tab.
Upgrading V1 shared credentials to V2 will permanently and irrevocably hide the V1 Shared Secret. Store your V1 credentials safely before you upgrade. The V1 credentials will continue to function. To comply with security guidelines you must migrate from V1 to V2 credentials, issue new V2 credentials for all your apps, and adopt the V2 credentials.
* Upgrading is a **one-way** operation. After an app is upgraded to V2, it cannot return to the V1 shared-secret model.
* Existing integrations keep working during the upgrade. Your current V1 application key and shared secret are migrated into the V2 structure as **Legacy** credentials, so running connections are not interrupted.
* After upgrading, the Legacy credentials are independent of one another. To complete the security improvements, rotate each one to a new, unique value. Rotating one credential does not affect the others, so you can migrate piece by piece.
To upgrade an application:
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to upgrade.
4. Reveal and note the current V1 Shared Secret, and store it via a safe method.
5. On the **Core** tab, in the Enhanced Security Available banner, click **Upgrade to V2**. This hides the V1 Shared Secret. The V1 secret is permanently and irrevocably hidden, and continues to function.
6. In the **Upgrade to V2 Credentials** dialog, review the warning that the action cannot be reversed, then click **Confirm Upgrade**.
After upgrading, open the new **Credentials** tab. Your former V1 shared secret appears as a migrated Legacy credential, marked **MIGRATED**, so existing integrations keep working while you transition.
### Generate a Credential
Each environment can have more than one active key, which is what enables zero-downtime rotation. To add a credential:
1. On the **Credentials** tab, select the **Production Auth Keys**, **Sandbox Auth Keys**, or **Webhook Secrets** tab.
2. Click **+ New Production Key** (or the equivalent button for the selected tab).
3. Enter a **Name** and an optional **Label**, then click **Create**.
The secret is displayed **one time only**. Use **Copy Secret**, **Copy Both**, or **Download as JSON** to save it securely, then click **Done**. Kibo does not store secrets in a recoverable form, so a secret cannot be shown again or retrieved later. If you lose a secret, generate a new credential to replace it.
### Rotate and Revoke Keys
Each credential in the key list shows the following details:
| Field | Description |
| ----------- | ------------------------------------------------------------------------------------------------ |
| Name | The label you assigned to identify the key's purpose (for example, "NewKey"). |
| Client ID | The full Client ID for the credential. |
| Environment | The environment the credential authenticates against (Production or Sandbox). |
| Status | Whether the credential is Active or Revoked. |
| Created | When the credential was generated. |
| Last used | When the credential last authenticated, which helps you identify keys that are no longer in use. |
Select **Show revoked credentials** to include previously revoked keys in the list.
To rotate a key with zero downtime:
1. Create a new key for the environment and save its secret.
2. Update your application or service to use the new Client ID and secret.
3. Revoke the old key once all traffic has moved to the new one.
To revoke a key, click **Revoke** in its row, optionally enter a reason, and confirm. Revoking cannot be undone, and any service still using the credential immediately loses access, so confirm the new key is in use first.
After you revoke the legacy credential, only your new, securely stored keys remain active.
### Webhook Signing Secret
V2 provides a dedicated signing secret for verifying webhooks, managed on the **Webhook Secrets** tab and separate from your authentication credentials. Each environment has its own webhook signing secret, and it can be rotated independently of your auth keys. For details on verifying webhook signatures, see [Verify Event Authenticity](/pages/application-development-best-practices#verify-event-authenticity).
## IP Filtering
IP filtering lets a Developer Account owner restrict where application credentials can authenticate from. If a key is leaked, it is useless from any network or country that is not on the allow list. You define reusable **IP Policies** at the account level and then assign them to one or more applications.
IP filtering protects application (API) credentials in Dev Center. To restrict access to Admin and storefronts by IP address instead, see [IP Restrictions](/pages/ip-restrictions).
### Account-Level Policies
An IP Policy is a named set of allow rules that you can reuse across applications. To manage policies, in Dev Center click the account name drop-down menu (top-right) and select **IP Policies**.
The IP Policies page lists your existing policies, the rules and assigned apps for each, and the actions available to manage them.
#### Create a Policy
1. Click **+ Create Policy** (or **Create Your First Policy** on an empty account).
2. Enter a **Policy Name** (required) and an optional description.
3. Under **Environment Scope**, enforcement on Production is always on. Select **Also enforce on Sandbox** if you want the policy to apply to Sandbox credentials too. This is off by default so that development from any IP is not disrupted.
4. Add at least one allow rule with **+ Add Rule**. Each rule can be one of the following types:
| Rule type | Format | Example |
| --------- | ------------------ | ----------------------------------- |
| Single IP | IPv4 or IPv6 | `203.0.113.7` |
| CIDR | IP/prefix | `203.0.113.0/24` or `2001:db8::/32` |
| IP Range | start – end | `203.0.113.10 - 203.0.113.50` |
| Country | ISO 3166-1 alpha-2 | `US` |
You can also paste a list of IPs, CIDRs, ranges, or country codes at once with **Bulk Paste**.
5. Use the **Test Tool** at the bottom of the editor to verify whether a given IP or country code would be allowed before you save.
6. Click **Save Policy**. If your current IP would be blocked by the rules you are saving, a lockout warning appears and requires explicit confirmation before saving.
#### Manage Policies
| Action | How |
| --------------------- | ----------------------------------------------------------------- |
| Edit rules | Click **Edit** on a policy row. |
| Assign to apps | Click **Assign**, select apps, then click **Assign to N apps**. |
| Set account default | Click **Set Default**, review the impact count, then confirm. |
| Clear account default | Click **Clear Default** on the default policy. |
| Delete | Click **Delete** (disabled if the policy is the account default). |
Applications with no explicit policy assignment inherit the **account default**. Setting a new default is a high-impact action, so the UI shows how many currently-open apps will start enforcing before you confirm.
### Per-App IP Filtering
On any application's edit page, click the **IP Filtering** tab in the left sidebar to see the policy in effect for that app:
* **Policy** is the effective policy name.
* **Source** is either `Explicit assignment` (set directly on this app) or `Inherited from account default`.
* **Rules** summarizes the rules (for example, "2 IP/CIDR, 1 range").
* **Scope** shows that Production is enforced and Sandbox is exempt unless the policy opts in.
* **Coverage** confirms the policy applies to all versions of the app automatically.
To assign or replace a policy, select it from the drop-down menu and click **Assign Policy** or **Replace Policy**. To remove an explicit assignment so the app falls back to the account default (or to open access), click **Remove Assignment**.
### Enforcement
* Enforcement is **immediate and a hard block** — there is no monitor-only mode.
* All credentials of every version of an assigned app are covered. There is no per-version or per-credential override.
* **Sandbox credentials** are exempt unless the policy's **Also enforce on Sandbox** option is set.
* Internal and service-to-service authentication paths are exempt from enforcement.
* Country rules apply only to traffic that transits Cloudflare, whereas IP rules apply on all paths.
### Tips
* Use the **Test Tool** before you assign a policy to production apps.
* Always review the **lockout warning** — it shows whether your current IP or country would be blocked by the rules you are saving.
* After you change the rules on an existing policy, the lockout banner indicates the check is stale until you save and re-open the editor.
## App Documentation
The [Apps & Integrations documentation](/pages/applications-1a6c791-introduction) provides a library of integrations for the Kibo Composable Commerce Platform, including applications developed by both Kibo and third parties to extend the functionality of your site and evaluate the capabilities of solution partners to enhance the functionality of your storefront.
If you already have a Dev Center account, you can install licensed applications on a sandbox by selecting them in the Dev Center. You can also install them from another Developer Account to which you’ve been granted access. Refer to [Install an Application](#install_an_application) for more information.
Note that:
* Some applications require [API Extensions](/pages/what-you-can-do-with-api-extensions "What You Can Do With API Extensions"). You cannot install these applications if your tenant doesn't have API Extensions enabled.
* Some Kibo-developed applications and integrations need to be configured after installation. Refer to the application's documentation for more information.
* Contact [Kibo Support](https://help.kibocommerce.com/) for assistance installing and configuring apps as needed.
## Collaborative Application Development
Dev Center lets you work collaboratively to create applications. Kibo uses the concept of "file-based applications" which means you can download a file-based representation of the application definition to work on collaboratively with your team using your own source control process.
There are two types of packages:
**Release packages**: Release packages contain all the files the developer intends to upload when submitting a theme for final certification.
**Development packages**: Adding a development package lets you have your own unique workspace with your own details, behaviors, events, attributes, and capabilities. If you want to share package elements between packages, you can clone a package.
Here is how this works:
1. Download the Release Package set of files and managed these file locally using a source control system.
2. Create packages on the Packages tab for each developer.
3. Divide the files and assign individual packages between developers within the same Dev account. Each package represents an individual work space where a developer can upload and download his files as needed for application development.
4. Each developer works on the assigned files individually within the developer's package.
5. When the developer finishes, the developer works with the local source control system to merge his work into the source control system.
6. Upload the files that compose the Release Package back into Dev Center.
7. Because this is a fluid process, work continues in this fashion until the application is complete.
## Create an Application
You must give an application a unique name and ID.
1. Log in to Dev Center.
2. Click **Develop** > **Applications** > **Create Application**.
3. Enter a unique application name and ID.
4. Click **Save**.
## Configure Package Details
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to configure.
4. Click the **Packages** tab.
5. If your application includes a graphical interface that the client must user to configure the application, enter the URL in the **Configuration URL** text box.
6. Provide a description of the application’s purpose in the **Package Description** text box.
7. Click **Save**.
Depending on what you want your application to do, additional configuration may be required:
* Select application behaviors
* Subscribe to an event
* Import application attributes
* Create and configure capabilities
### Create a New Package
Whether you create a package to work on an application using the Dev Center user interface or to create a collaborate developer environment, a new package lets you work on an application without affecting the Release package.
A new package does not contain any package details from the Release Package. If you want to create a new package that contains previously created details, behaviors, events, attributes, and capabilities, you need to clone the package. Complete the following procedure to create a new package.
1. Log in to Dev Center
2. Click **Develop** > **Applications**.
3. Double-click the application you want to open.
4. Click the **Packages** tab.
5. Click **New**.
6. Enter a name for the package.
7. Click **Save**.
The new package is listed in the **Active Package** drop-down menu. Always verify you are working in the right package.
### Clone a Package
To copy the details, behaviors, events, attributes, and capabilities of another package:
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to open.
4. Click the **Packages** tab.
5. Select the package you want to clone from the **Active Package** drop-down menu.
6. Click **Clone**.
7. Enter a name for the package.
8. Click **Save**.
The new package is listed in the **Active Package** drop-down menu.
### Rename a Package
You can rename any package, except for the Release Package.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to rename.
4. Click the **Packages** tab.
5. Select the package you want to rename from the **Active Package** drop-down menu.
6. Click **Rename**.
7. Rename the package.
8. Click **Save**.
The renamed package is listed in the **Active Package** drop-down menu.
### Delete a Package
You can delete any package, except for the Release Package.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to delete.
4. Click the **Packages** tab.
5. Select the package you want to delete from the **Active Package** drop-down menu.
6. Click **Delete**.
The package is no longer listed in the **Active Package** drop-down menu.
## Select Application Behaviors
[Behaviors](/pages/application-behaviors "Application Behaviors") represent the functions of your application.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to configure.
4. Click the **Packages** tab.
5. Select the package you want to configure from the **Active Package** drop-down menu.
6. Click the **Behaviors** tab
7. Click **Select Behaviors**.
8. Select a **Behavior category**.
9. Select a **Behavior name**.
10. Repeat for as many behavior categories as necessary.
11. Click **Save**.
The selected behaviors appear in the Behaviors area of the Application Editor. The authentication ticket encrypts the set of application behaviors in the access token.
## Subscribe to an Event
When you configure an endpoint, you can subscribe to one or many events. To view these endpoints after configuration, expand the endpoint from the Events grid on the Events tab. To understand events and why you may want to configure them, refer to [Event Subscription](/pages/event-subscription).
To configure an application endpoint and subscribe to events in Dev Center to receive push notifications:
Only applications in the "In Development" state can be configured.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application to which you want to add an event subscription.
4. Click the **Packages** tab.
5. Select the package you want to configure from the **Active Package** drop-down menu.
6. Click the **Events** tab.
7. Click **Add Event Subscription**.
8. In the Add Event Subscription dialog box, do the following actions:
1. In the **Endpoint** text box, enter the URL to which push notifications of the event will post.
2. In the **Event category** list, select a category.
3. In the **Event** list, select an event.
4. Repeat for as many event categories as necessary.
5. Click **Save**.
9. Test the event to verify push notifications are sent to the associated endpoint.
When the subscribed event occurs, a notification is sent to the specified endpoint.
## Remove a Registered Event
To remove a registered event from a subscribing application in Dev Center:
Only applications in the "In Development" state can be configured.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to configure.
4. Select the package you want to configure from the **Active Package** drop-down menu.
5. Click the **Events** tab
6. Select the event you want to delete and then right-click and select **Delete**.
7. Click **Save**.
The subscribed event no longer appears in the grid.
## Import Application Attributes
As you develop your application, you might discover that you require a customer, order, or product attribute for your application's implementation to work. For example, if you are developing a tax capability, you might require each product in a site's catalog to have a defined "tax code" attribute. After you create the custom attributes necessary for your application in your development tenant, you can import them into your application configuration in Dev Center.
When a client installs the application, the installation automatically configures all attributes associated with the application so that the client does not have to recreate them in Admin For example, if an application includes a Boolean product property attribute called "Taxable" and a customer attribute called "Tax exempt," after installing the application, the attribute definitions appear in Admin
When an attribute is configured in Admin and the application which contains the attribute is installed in a sandbox, you can import existing attributes into an application using Dev Center. The Attribute tab lets you import attributes from a sandbox and display the attribute values in the Attributes grid.
| Label | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Attribute name | The attribute name created in Admin |
| Attribute FQN | Either `<_namespace_>`\~`<_attribute name_>` or `<_Dev Account Namespace_>`*`<_Namespace value_>`*`<_Attribute name_>`. |
| Entity | The entity is the attribute category, which is Product, Customer, or Order. |
| Input type | When you create an input type in Admin during the attribute creation process, you can select from List, Text box, Text area, Yes/No, Date. |
| Data type | When you create an input type in Admin during the attribute creation process, you can select from text, number. dateTime, or string. |
| Attribute value | This displays the attribute value set up in Admin when the attribute was configured. These values vary depending on the selected input and data types. |
| Actions | Use the Gear icon to select a Delete action. |
When you import attributes from a sandbox, the sandbox you select has an impact on what displays in the form. If you change the selected sandbox, then the attributes that were previously listed are lost. When you select "Import," it always overwrites whatever is currently in the application with whatever you choose in this task. The attribute namespace lets you configure either a unique namespace or lets you share a namespace with other applications or attributes. When you use the same attribute namespace, you share data. Complete the following procedure to import the customer, order, and product attributes required for your application into the application's configuration.
Attributes must have unique names. Importing attributes with names that match attribute names that already exist in your application will fail. Depending on what release you are using, your options may vary.
You must define the attributes in Admin and you must have a configured sandbox that includes attributes that you can import.
To import application attributes:
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application where you want to import attributes.
4. Click the **Packages** tab.
5. Select the package you want to configure from the **Active Package** drop-down menu.
6. Click the **Attributes** tab.
7. Enter a namespace in the **Attribute Namespace** text box.
8. Click **Import from Sandbox**.
9. In the Import from Sandbox dialog box:
1. Click **Select Sandbox**.
2. Select a sandbox and click **OK**.
3. Select a category from the **Attribute Category** drop-down menu.
4. Select the attributes to import from the Attributes list.
10. Click **Import**.
The attributes imported from the tenant display in the Application editor under Attributes. Previously, if you imported attributes the Attribute FQN would consist of the `<_namespace_>` \~`<_attribute name_>`. Now, applications use `<_Dev Account namespace_>`*`<_namespace value_>`*`<_attribute name_>`.
## Download Application Files
If you want to manage your application development using files rather than the Application Editor, you can download and configure the following files:
* attributes.xml
* behaviors.xml
* capabilities.xml
* core.xml
* events.xml
* packageconfig.xml
To download application files:
1. Log in to Dev Center.
2. Click **Develop** > **Application**.
3. Double-click the application you want to download.
4. Click the **Packages** tab.
5. Select the package you want to download from the **Active Package** drop-down menu.
6. Click **More** > **Download**.
## Manage Capabilities
In Dev Center, you can configure a capability, determine the types of functionality it performs, and configure the endpoints that let Kibo send requests to the capability. The capability configuration process begins after you have created an application and configured the Configuration URL in the Packages tab . When the capability is installed, the merchant can select the countries to enable from the list of supported countries, based on the merchant's implementation. You can edit a capability at anytime by double-clicking it on the Capability configurations grid.
### Create a Capability
In this task, you configure the type of capability and the endpoints to which the capability sends requests.
You must have created an application and configured the Configuration URL prior to configuring the capability.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application in which you want to configure a capability.
4. Click the **Packages** tab.
5. Select the package you want to configure from the **Active Package** drop-down menu.
6. Click the **Capabilities** tab,
7. Click **Add Capability**.
8. Select a capability from the drop-down menu and click **OK**.
9. In the specific capability dialog box, enter the endpoint for the capability in the **`` endpoint URL** text box.
10. Configure other capability options (if required).
11. Click **Save**.
This automatically creates the first version of your capability.
### Remove a Capability
To remove a capability:
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application that contains the capability you want to remove.
4. Click the **Packages** tab.
5. Select the package you want to configure from the **Active Package** drop-down menu.
6. Click the **Capabilities** tab.
7. Right-click the capability you want to remove and select **Remove**.
The capability no longer displays in the Capability list on the Capability tab.
### Install a Capability
To install a capability in a sandbox:
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application that contains the capability you want to install in a sandbox.
4. Click **Install**.
5. Select a sandbox from the list and click **OK**.
Installing the capability in a sandbox lets you configure, initialize, and enable the capability the same way a merchant would after installing it in their tenant or site environment.
### Select Active Settings
Complete the following procedure to select the active capability settings from a subset of values supported by the capability.
1. Log in to Dev Center.
2. Click **Sandboxes**.
3. Right-click the sandbox in which you installed the capability and click **View**.
4. In Admin, click **Settings** > **Applications**.
5. Expand the capability type category and click the capability.
6. For each country, shipping carrier, or credit type you want to enable for the capability (depending on its capability mode), select the item to highlight it. If it is highlighted in blue, it is active.
7. Click **Save**.
### Configure a Capability
Complete the following procedure to access the capability configuration page you defined in Dev Center and configure the capability settings. The configuration URL must be defined in Dev Center.
1. In Admin, for the capability, click **Configure**.
2. Define the settings for the capability and click **Save**.
### Initialize a Capability
Complete the following procedure to initialize a capability with active settings and configuration.
1. Log in to Dev Center.
2. Click **Sandboxes**.
3. Right-click the sandbox where you installed the capability and select **View**.
4. In Admin, click **Settings** > **Applications**.
5. Click the application that contains the capability you want to initialize.
6. Click **Configuration**.
7. Use the custom code provided by the third-party capability provider to initialize your capability. When the capability initializes, the Enable App button activates.
8. Click **Enable App**.
Your capability is initialized and your application is enabled for use.
### Enable a Capability
To enable the capability to perform functionality for the installed sandbox tenant or site, complete the following procedure. If the **Enable App** button is grayed out, you must first [initialize](#initialize-a-capability) your application.
1. In Admin, click **Settings** > **Applications** and click the application.
2. Verify the application Initialized status is set to "Yes".
3. Click **Enable App**.
After completing this procedure, the capability is ready to use.
## Upload File-Based Applications
You can create and define an application using the Dev Center user interface, or you can [download](#download-application-files) a file-based representation of the application definition, edit the files in your local development environment, and upload them to Dev Center.
When you are ready to upload application files, you must:
* Ensure you include *core.xml* and *packageconfig.xml* in every upload.
* Create a zipped package of your files.
* Include only one package. If not, your upload fails and you are prompted to fix your package.
* Match the package to which you are uploading.
* Ensure the package to which you want to upload currently exists.
The upload process ensures that the XML syntax is valid. If the XML is not valid, the upload fails and displays an error. If the validation and upload succeeds, the new settings are displayed in Packages.
You can upload applications using XML files.
You must have a compressed archive of at least one file plus *core.xml* and *packageconfig.xml* ready to upload for this task.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application to which you want to upload files.
4. Click the **Packages** tab.
5. Select the package you want to upload files to from the **Active Package** drop-down menu.
6. Click **More** > **Upload**.
7. In the file manager, browse to the compressed archive that includes your files.
8. Click **OK**.
9. Click **Upload**.
Your application details are now part of the package to which you uploaded the compressed archive.
## Create a Change Note
As you make changes to your application or theme, it’s a good idea to note the changes you make or any special instructions for working with application.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application to which you want to add a change note.
4. Click the **Packages** tab.
5. Select the package to which you want to add a change note from the **Active Package** drop-down menu.
6. Click the **Release Notes** tab.
7. Click **Create Change Note**.
8. Enter comments about the change you made.
9. Click **Save**.
Each note displays the change comment, lists the account that made the change, and displays the date the change was made.
## Create a New Version of a Certified Application
When you create an application for the first time in Dev Center, this is the first available version of the application. When coding is finished, you submit the application version for certification. If the application passes certification, it can be promoted to a production environment (in the case of tenant-specific custom applications).
After you certify an application, you can create a new version. Kibo allows for semantic versioning (Major.Minor.Revision). How you version your application is up to your in-house versioning practices. New versions must use a unique number. Complete the following procedure to create a new version. Versioning is not automatic, it is a manual process.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Right-click the application you want to version and select **Create new version**.
4. In the Application editor, enter the new version number.
5. Click **Save**.
You now have a new version of your application that is in the “In development” state and must be resubmitted for certification.
## Install an Application
There’s more than one way to install an application on a sandbox. The most common way is to select from a list of applications in your Developer Account, but you can also install some licensed applications directly from another Developer Account to which you’ve been granted access.
To select an application to install from your Developer Account:
1. Click **Develop** > **Applications**.
2. Double-click the application you want to install.
3. Click **Install**.
4. Select the sandbox where you want to install the application and click **OK**.
5. Click **Sandboxes**.
6. Select your sandbox.
7. Click **View Sandbox**.
8. In Admin, to enable your application, click **Settings** > **Applications**.
9. In the Applications page, verify the your application appears in the list.
10. Double-click the application.
11. Click **Enable App**.
Your application is now installed and enabled.
To select a licensed application from another Developer Account:
1. Log in to Dev Center.
2. Click **Sandboxes**.
3. Double-click the sandbox where you want to install an application.
4. Click the **Installed Assets** tab.
5. Click **Install App**.
6. Select an account from the **Developer Account** drop-down menu.
7. Select the application you want to install and click **OK**.
8. Select your sandbox.
9. Click **View Sandbox**.
10. In Admin, to enable your application, click **Settings** > **Applications**.
11. In the Applications page, verify the your application appears in the list.
12. Double-click the application.
13. Click **Enable App**.
Your application is now installed and enabled.
## Submit an Application for Certification
When you finish developing your application and have completed the store profile, you can submit your application to the certification process. Once you submit your application for certification, the team reviews and certifies that it meets the criteria.
When you submit your application, the application version is locked. You cannot modify this version once you submit it. If you have questions about the certification process, please consult with your Account Executive or your Partner Manager.
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to submit for certification.
4. Click **More** > **Submit for certification**.
5. Click **Submit for Certification**.
The application moves into the “Pending certification” state. The following diagram represents the application certification lifecycle:
| Status | Description |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| In Development | This is the initial status of all applications or themes. Applications and themes remain in this state until they are submitted for certification. While an application is in this status, define the application name or application version name, define pricing and licensing, and code and test applications and themes in a development store. |
| Pending Certification | Applications and themes enter this status after being submitted for certification, and remain in this state until the review and certification process is complete and the application or theme is accepted or rejected. After you submit, the version of the application or theme submitted is locked as well as the namespace associated with it. |
| As the code complexity and number of applications and themes to certify increases, so does the amount of time required to complete the review and certification process. You cannot change any code or perform any actions for the application or theme while it is in this status. During this process, someone from Kibo will contact you to go over the process and to inform you whether your application or theme is certified. The end result of the certification process is either Certified or back to In Development. Once certified, your application or theme can be installed in the production tenant. | |
| Certified | This status appears when Kibo certifies the application or theme. Depending on your implementation, the application may be ready for release into the app or theme store or ready to promote to a production environment if it is a custom application or theme. While an application or theme is in this state, you can only define pricing. |
| Deleted | This status appears after you [delete an application](#delete-an-application). A deleted application is no longer available to install on any sandbox or production tenant, and any attempt to authenticate against it is rejected. Existing installations stop working once the application is deleted. |
## Delete an Application
When you no longer need an application, you can delete it from Dev Center. Deleting an application moves it to the **Deleted** status, after which:
* The application is no longer available to install on any sandbox or production tenant.
* Any attempt to authenticate against the application is rejected, so existing integrations that rely on its credentials stop working.
Because deletion affects any tenant where the application is currently installed, confirm the application is no longer in use before you delete it.
To delete an application:
1. Log in to Dev Center.
2. Click **Develop** > **Applications**.
3. Double-click the application you want to delete.
4. Click **More** > **Delete application**.
After you confirm, the application moves to the **Deleted** status.
# Application Behaviors
Source: https://docs.kibocommerce.com/pages/application-behaviors
Behaviors determine which operations an application can perform on the platform after it’s installed on a tenant. These are usually read/write and related actions for objects such as products or orders.
See how to configure application capabilities and behaviors
You can retrieve the behaviors for any application via API with the [Get Package Behaviors API](/api-reference/package/get-package-behaviors).
As of July 2024, applications must have the appropriate behaviors to access inventory-related APIs in some environments. These are **Inventory Read** (to retrieve inventory data), **Inventory Modify** (to create or update inventory data), and **Inventory Delete** (to explicitly remove inventory data). These are required for all sandbox environments. Existing applications developed before July 2024 do not require these behaviors for production environments, but newer applications do require them.
## Best Practices
It’s important to keep the following things in mind when registering behaviors with an application:
* Behaviors are designed to protect user security by limiting application access
* Only register behaviors your application needs to access the appropriate objects or APIs
* Registering all possible behaviors for an application may prevent Kibo from approving your application when you submit it for certification
* The behaviors you register with your application are encrypted in the access token used to pass information between your application and the API. If you register or remove behaviors, you must generate a new authorization ticket.
* Whenever you make changes to application behaviors or event subscriptions, you must [re-install](/pages/application-asset-management#install-an-application) the application on your sandbox and [re-enable](/pages/application-asset-management#enable-a-capability) it in Dev Center in order for the changes to work.
## Assign Behaviors
To assign behaviors to applications:
1. Go to **Develop** > **Applications** in the Dev Center.
2. Click the appropriate application you want to update.
3. Click **Packages**.
4. On the **Behaviors** tab, click **Select Behaviors**.
5. Under **Behavior category**, select the topic that the behavior falls under.
6. Under **Behavior name**, enable the checkboxes for specific behaviors.
7. Click **Save**.
## Behavior Reference
All behaviors are associated with a numerical ID. Some are also used by the Kibo Admin. This list defines behaviors that are available to both applications and Admin users:
| Behavior ID | Behavior Category | Behavior | Description |
| -------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 305 | Audit Log | Audit Log Read | View an [audit log](/api-overviews/getting-started) |
| 270 | B2B Account | B2B Account Create | Create a B2B account |
| 271 | B2B Account | B2B Account Update | Delete a B2B account |
| 272 | B2B Account | B2B Account Delete | View a B2B account |
| 273 | B2B Account | B2B Account Read | Make changes to a B2B account |
| 69 | Cart | Cart Read | View a shopper's cart |
| 71 | Cart | Cart Update | Make changes to a shopper's cart |
| 72 | Cart | Cart Delete | Delete a shopper's cart |
| 170 | Channel | Channel Read | View existing channel details |
| 171 | Channel | Channel Create | Create new channels |
| 172 | Channel | Channel Update | Change existing channel details |
| 173 | Channel | Channel Delete | Delete existing channels |
| 175 | Channel | ChannelGroup Read | View existing channel group details |
| 176 | Channel | ChannelGroup Create | Create new channel groups |
| 177 | Channel | ChannelGroup Update | Change existing channel group details |
| 178 | Channel | ChannelGroup Delete | Delete existing channel groups |
| 179 | Credit | Credit Read | View existing store credit details |
| 180 | Credit | Credit Update | Change existing store credit details |
| 181 | Credit | Credit Delete | Delete existing store credit |
| 182 | Credit | Credit Create | Create new store credit for customers |
| 247 | Currency | Create Currency | Create a new currency |
| 248 | Currency | Read Currency | View currency details |
| 249 | Currency | Update Currency | Update currency details |
| 250 | Currency | Delete Currency | Delete a currency |
| 41 | Customer | Customer Read | View existing customer account details |
| 42 | Customer | Customer Update | Change existing customer account details |
| 43 | Customer | Customer Delete | Delete existing customer accounts |
| 44 | Customer | Customer Create | Create new customer accounts |
| 60 | Customer | Purchase Order Read | View purchase order details |
| 61 | Customer | Purchase Order Create | Create a new purchase order |
| 62 | Customer | Purchase Order Update | Update a purchase order |
| 193 | Customer | Stock Notification Read | View stock notification details |
| 194 | Customer | Stock Notification Update | Change stock notification details |
| 195 | Customer | Stock Notification Delete | Delete stock notifications |
| 196 | Customer | Stock Notification Create | Create stock notifications |
| 223 | Customer | Customer Password Update | Reset existing customer account passwords |
| 290 | | | |
| Customer | Customer Impersonate | Impersonate a customer | |
| 311 | Customer Rule | Customer Rule Read | View customer rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") and [Return Rules](/pages/return-rules "Return Rules") |
| 312 | Customer Rule | Customer Rule Create | Create new customer rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") and [Return Rules](/pages/return-rules "Return Rules") |
| 313 | Customer Rule | Customer Rule Update | Edit customer rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") and [Return Rules](/pages/return-rules "Return Rules") |
| 314 | Customer Rule | Customer Rule Delete | Delete existing customer rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") and [Return Rules](/pages/return-rules "Return Rules") |
| 24 | Discount | Discount Read | View discount details |
| 25 | Discount | Discount Create | Create new discounts |
| 26 | Discount | Discount Update | Change discount details |
| 27 | Discount | Discount Delete | Delete existing discounts |
| 106 | Extensibility | Extensibility Read | View extension details |
| 107 | Extensibility | Extensibility Create | Create extensions |
| 108 | Extensibility | Extensibility Update | Update extension details |
| 109 | Extensibility | Extensibility Delete | Delete extensions |
| 204 | InstalledApplication | Read installed applications | View the installed applications |
| 205 | InstalledApplication | Update installed applications | Change installed applications |
| 183 | Location | Location Create | Create new locations |
| 184 | Location | Location Update | Change existing location details |
| 185 | Location | Location Delete | Delete existing locations |
| 186 | Location | Location Read | View existing location details |
| 73 | Order | Order Read | View the details of an order |
| 74 | Order | Order Create | Create a new order |
| 75 | Order | Order Update - All | Update all order elements (includes Order Update - Items, Pricing, Discounts, Attributes, and Manual Adjustments) |
| 76 | Order | Order Delete | Delete an existing order |
| 77 | Order | Order Fulfill | Fulfill an order |
| 78 | Order | Order Cancel | Cancel an order |
| 79 | Order | Order Apply Payment | Apply a payment to an order |
| 187 | Order | Order Ship | Ship an order |
| 242 | Order | Order Update - Items | Change only the details of order items and their quantities in addition to accept and cancel orders, resend order emails, edit internal notes on the order, and print order templates |
| 243 | Order | Order Update - Pricing | Change only the pricing information related to an order in addition to accept and cancel orders, resend order emails, edit internal notes on the order, and print order templates |
| 244 | Order | Order Update - Discounts | Change only the discount information of an order in addition to accept and cancel orders, resend order emails, edit internal notes on the order, and print order templates |
| 245 | Order | Order Update - Attributes | Change only the attributes on an order in addition to accept and cancel orders, resend order emails, edit internal notes on the order, and print order templates |
| 246 | Order | Order Update - Manual Adjustments | Change only the order subtotal and the shipping cost of an order in addition to accept and cancel orders, resend order emails, edit internal notes on the order, and print order templates |
| 251 | Order | Order Routing | Access order routing |
| 292 | Order | Override Order Update Restriction | If an order has been set to restrict editing or cancellation, this behavior will override those flags and allow the user to edit and cancel the order |
| 306 | Order | Manual Order Release | Allows B2B orders in Pending Shipment status to be released manually via the Admin UI **ADD LINK** |
| 65 | Payment | Payment Read | View the payment details for an order |
| 66 | Payment | Payment Create | Create a payment for an order |
| 67 | Payment | Payment Update | Change the payment details for an order |
| 68 | Payment | Payment Delete | Delete a payment for an order |
| 105 | Payment | Read Payment Settings | View the payment settings |
| 297 | Payment | Installment Item Manage | Update a payment [installment](/pages/subscription-installments "Subscription Installments") |
| 298 | Payment | Installment Item Read | View payment [installments](/pages/subscription-installments "Subscription Installments") |
| 299 | Payment | Recycling Item Manage | Update a [recycling](/pages/recycle-subscription-payments "Recycle Subscription Payments") payment |
| 300 | Payment | Recycling Item Read | View [recycling](/pages/recycle-subscription-payments "Recycle Subscription Payments") payments |
| 238 | Price List | Create Price List | Create a new price list |
| 239 | Price List | Read Price List | View an existing price list |
| 240 | Price List | Update Price List | Change price list details |
| 241 | Price List | Delete Price List | Delete a price list |
| 1 | Product | Product Create | Create new products |
| 2 | Product | Product Update | Change product details |
| 3 | Product | Product Delete | Delete products |
| 4 | Product | Product Read | View product details |
| 9 | Product | Publish Product Changes | Discard or publish staged changes to products |
| 16 | Product | Product Category Read | View product category details |
| 17 | Product | Product Category Create | Create new product categories |
| 18 | Product | Product Category Delete | Delete product categories |
| 19 | Product | Product Category Update | Change product category details |
| 167 | Product | Change Product Publishing Mode | Change the publishing mode for product changes in the Publishing module |
| 208 | Product | Delete Inventory | Delete inventory |
| 209 | Product | Modify Inventory | Change inventory details |
| 210 | Product | Read Inventory | View inventory details |
| 220 | Product | Product Code Change | Change product codes |
| 291 | Product | Product Type Change | Change product types |
| 307 | Product Rule | Product Rule Read | View product rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules"), [Return Rules](/pages/return-rules "Return Rules"), and [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 308 | Product Rule | Product Rule Create | Create new product rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules"), [Return Rules](/pages/return-rules "Return Rules"), and [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 309 | Product Rule | Product Rule Update | Edit product rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules"), [Return Rules](/pages/return-rules "Return Rules"), and [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 310 | Product Rule | Product Rule Delete | Delete existing product rules in [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules"), [Return Rules](/pages/return-rules "Return Rules"), and [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 229 | Publish Sets | Create Publish Set Definition | Create new publish sets |
| 230 | Publish Sets | Read Publish Set Definition | View existing publish sets |
| 231 | Publish Sets | Update Publish Set Definition | Change existing publish sets |
| 232 | Publish Sets | Delete Publish Set Definition | Delete publish sets |
| 233 | Publish Sets | Publish Publish Set Definition | Publish existing publish sets |
| 324 | Purchase Limit Rule | Purchase Limit Rule Read | View [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") |
| 325 | Purchase Limit Rule | | |
| Purchase Limit Rule Create | Create new [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") | | |
| 326 | Purchase Limit Rule | | |
| Purchase Limit Rule Update | Edit [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") | | |
| 327 | Purchase Limit Rule | | |
| Purchase Limit Rule Delete | Delete existing [Purchase Limit Rules](/pages/purchase-limit-rules "Purchase Limit Rules") | | |
| 274 | Quote | Quote Create | Create a B2B quote |
| 275 | Quote | Quote Update | Update a B2B quote |
| 276 | Quote | Quote Delete | Delete a B2B quote |
| 277 | Quote | Quote Read | View B2B quotes |
| 320 | Return Rule | Return Rule Read | View [Return Rules](/pages/return-rules "Return Rules") |
| 321 | Return Rule | Return Rule Create | Create new [Return Rules](/pages/return-rules "Return Rules") |
| 322 | Return Rule | Return Rule Update | Edit [Return Rules](/pages/return-rules "Return Rules") |
| 323 | Return Rule | Return Rule Delete | Delete existing [Return Rules](/pages/return-rules "Return Rules") |
| 315 | Safety Stock Rule | Safety Stock Rule Read | View [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 316 | Safety Stock Rule | Safety Stock Rule Create | Create new [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 317 | Safety Stock Rule | Safety Stock Rule Update | Edit [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 318 | Safety Stock Rule | Safety Stock Rule Delete | Delete existing [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 319 | Safety Stock Rule | Safety Stock Rule Run | Run [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules") |
| 234 | Search | Create Product Ranking Definition | Create new product ranking rules |
| 235 | Search | Read Product Ranking Definition | View existing product ranking rules |
| 236 | Search | Update Product Ranking Definition | Change existing product ranking rules |
| 237 | Search | Delete Product Ranking Definition | Delete product ranking rules |
| 254 | Search | Search Configuration Create | Create a new search configuration |
| 255 | Search | Search Configuration Read | View search configuration details |
| 256 | Search | Search Configuration Update | Change search configuration details |
| 257 | Search | Search Configuration Delete | Delete a search configuration |
| 258 | Search | Search Campaign Create | Create a new search campaign |
| 259 | Search | Search Campaign Read | View search campaigns |
| 260 | Search | Search Campaign Update | Change search campaign details |
| 261 | Search | Search Campaign Delete | Delete a search campaign |
| 262 | Search | Search Schema Definition Create | Create a search schema definition |
| 263 | Search | Search Schema Definition Read | View search schema definitions |
| 264 | Search | Search Schema Definition Update | Change search schema definition details |
| 265 | Search | Search Schema Definition Delete | Delete a search schema definition |
| 266 | Search | Search Redirects Create | Create a new search redirect |
| 267 | Search | Search Redirects Read | View search redirects |
| 268 | Search | Search Redirects Update | Change search redirect details |
| 269 | Search | Search Redirects Delete | Delete a search redirect |
| 282 | Search | Search Synonym Create | Create a new search synonym |
| 283 | Search | Search Synonym Read | View search synonyms |
| 284 | Search | Search Synonym Update | Change search synonym details |
| 285 | Search | Search Synonym Delete | Delete a search synonym |
| 286 | Search | Search Merchandizing Rule Create | Create a new search merchandizing rule |
| 287 | Search | Search Merchandizing Rule Read | View search merchandizing rules |
| 288 | Search | Search Merchandizing Rule Update | Change search merchandizing rule details |
| 289 | Search | Search Merchandizing Rule Delete | Delete a search merchandizing rule |
| 293 | Search | Search Facets Create | Create a new search facet |
| 294 | Search | Search Facets Read | View search facets |
| 295 | Search | Search Facets Update | Change search facet details |
| 296 | Search | Search Facets Delete | Delete a search facet |
| 225 | SettingsCustomRoutes | Create CustomRoutes Definition | Create new custom routes |
| 226 | SettingsCustomRoutes | Read CustomRoutes Definition | View existing custom routes |
| 227 | SettingsCustomRoutes | Update CustomRoutes Definition | Change existing custom routes |
| 228 | SettingsCustomRoutes | Delete CustomRoutes Definition | Delete custom routes |
| 49 | SettingsGeneral | General Settings Read | View the general settings for your sites |
| 51 | SettingsGeneral | General Settings Update | Change the general settings for your sites |
| 57 | SettingsOrder | Order Settings Read | View existing order settings |
| 59 | SettingsOrder | Order Settings Update | Change existing order settings |
| 118 | SettingsPlatformAppDev | Application Status Enable | Enable applications for the tenant |
| 53 | SettingsShipping | Shipping Settings Read | View existing shipping settings |
| 54 | SettingsShipping | Shipping Settings Create | Create new shipping settings |
| 55 | SettingsShipping | Shipping Settings Update | Change existing shipping settings |
| 56 | SettingsShipping | Shipping Settings Delete | Delete existing shipping settings |
| 8 | Site | Publish Content Changes | Discard or publish staged changes to site content |
| 11 | Site | Site Create Content | Create new content in the Content Editor module |
| 12 | Site | Site Update Content | Change content in the Content Editor module |
| 13 | Site | Site Delete Content | Delete content in the Content Editor module |
| 120 | Site | Site Read Content | View content in the Content Editor module |
| 121 | Site | Site Read Document List | View document lists |
| 122 | Site | Site Create Document List | Create new document lists |
| 123 | Site | Site Update Document List | Change document lists |
| 124 | Site | Site Delete Document List | Delete document lists |
| 160 | Site | Validate an address | Enable address validation in General Settings |
| 165 | Site | Preview changes before they're published | View/preview the site's staging version |
| 166 | Site | Change Content Publishing Mode | Change the publishing mode for content changes in the Publishing module |
| 222 | Site | View live content | View the site's live version |
| 301 | SLA | SLA Create | Create new [fulfillment SLAs](/pages/fulfillment-slas "Fulfillment SLAs") |
| 302 | SLA | SLA Read | View existing [fulfillment SLAs](/pages/fulfillment-slas "Fulfillment SLAs") |
| 303 | SLA | SLA Update | Change existing [fulfillment SLA](/pages/fulfillment-slas "Fulfillment SLAs") details |
| 304 | SLA | SLA Delete | Delete [fulfillment SLAs](/pages/fulfillment-slas "Fulfillment SLAs") |
| 45 | Tenant | Tenant Read | View tenant details |
| 224 | Tenant | Log Read Behavior | Log read behavior |
| 28 | User | Admin User Read | View existing Admin user details |
| 29 | User | Admin User Create | Create new Admin users |
| 30 | User | Admin User Update | Change existing Admin user details |
| 33 | User | Shopper User Read | View shopper account details |
| 34 | User | Shopper User Create | Create shopper accounts |
| 35 | User | Shopper User Update | Change shopper account details |
| 36 | User | Shopper User Delete | Delete shopper accounts |
| 37 | User | User Role Read | View existing Admin role details |
| 161 | Wishlist | Wishlist Read | View customer wishlists |
| 162 | Wishlist | Wishlist Create | Create new customer wishlists |
| 163 | Wishlist | Wishlist Update | Change customer wishlists |
| 164 | Wishlist | Wishlist Delete | Delete customer wishlists |
These additional behaviors are only available to applications and developer resources:
| Behavior ID | Behavior Category | Behavior | Description |
| ----------- | ----------------------- | ---------------------------- | ----------------------------------- |
| 89 | Developer Account | Developer Account Read | View developer accounts |
| 90 | Developer Account Asset | Developer Asset Read | View developer assets |
| 91 | Developer Account Asset | Developer Asset Create | Create a new developer asset |
| 92 | Developer Account Asset | Developer Asset Update | Change a developer asset |
| 93 | Developer Account Asset | Developer Asset Delete | Delete a developer asset |
| 216 | MZDB | Create EntityList Definition | Create a new entity list definition |
| 217 | MZDB | Update EntityList Definition | Update an entity list definition |
| 218 | MZDB | Delete EntityListDefinition | Delete an entity list definition |
| 114 | SettingsPlatformAppDev | Application Status Read | View application statuses |
| 115 | SettingsPlatformAppDev | Application Status Update | Change an application's status |
| 116 | SettingsPlatformAppDev | Application Status Create | Create an application status |
| 117 | SettingsPlatformAppDev | Application Status Delete | Delete an application status |
# Application Development Best Practices
Source: https://docs.kibocommerce.com/pages/application-development-best-practices
This topic describes best practices and answers common questions for third parties developing applications for the Kibo Composable Commerce Platform (KCCP). This topic assumes you are familiar with basic [Application Development Requirements](/pages/application-development-requirements).
## Security
The following sections describe best practices for protecting your applications and users from security threats.
### Encrypt Sensitive Data
Always encrypt any sensitive data that your application might handle in transit or at rest. Failure to encrypt the following data may prevent Kibo from approving your application when you submit it for certification:
* Application keys/IDs
* Shared secrets
* Usernames
* Passwords
* Access keys
### Use a Configuration Dialog to Get User Credentials
As an application developer, you should never directly request authentication credentials from a merchant for either Kibo or a third-party platform. For this reason, KCCP provides a built-in configuration dialog that is essentially an iframe into which you can load any HTML. You can use this dialog to allow merchants to enter their own credentials. Then, you are responsible for encrypting the data and ensuring it isn't logged or stored in a sensitive location.
To create a configuration dialog:
1. Write the HTML required for any configuration data and add it to your application code.
2. [Upload](/pages/application-asset-management#upload-file-based-applications) your application to Dev Center.
3. Click **Develop** > **Applications**.
4. Double-click the application you want to configure.
5. Click the **Packages** tab.
6. Enter the URL for the content you want the configuration dialog to display in the **Configuration URL** field. This causes the Configuration link to appear when users access the application from any tenant where it's installed.
### OAuth: Redirect Users Back to Your Application
Many platforms you might want to integrate with use the OAuth authorization standard. You cannot implement OAuth in an iframe across domains, so you must temporarily take the user out of your configuration dialog while they authenticate with the third-party.
In cases where OAuth is required, you can use redirects to return the user to Admin and the configuration dialog. Simply direct the user back to the tenant URL with `/#configure` appended. For example:
```
https://t00000.mozu.com/Admin/s-1111/capability/edit/fbe22a718c7e3245a16543210c1bd334/#configure
```
### Prevent Cross-Tenant Access
By default, all URLs contain a tenant ID. To prevent potential misuse of your tenant ID, you should configure your application to transform it. For example, the Kibo Integrations team hashes tenant IDs with session IDs when developing applications to conceal the tenant ID and prevent unauthorized access.
## Event Management
Keep the following information in mind when dealing with events:
* When you configure an application to [subscribe to events](/pages/event-subscription "Event Subscription"), Kibo sends an HTTP POST request to your application server whenever that event occurs (e.g., product updated).
* The platform sends one event for each site and catalog you have. If you have two sites, one master catalog, and two catalogs, then it sends five POST requests for each event to which your application is subscribed.
* Whenever you make changes to application behaviors or event subscriptions, you must [re-install](/pages/application-asset-management#install-an-application) the application on your sandbox and [re-enable](/pages/application-asset-management#enable-a-capability) it in Dev Center in order for the changes to work.
### Verify Event Authenticity
Although optional, it's a good idea to verify that an event originated from the platform before interacting with it programmatically. The method you use depends on your application's security model:
* Applications on the original (V1) security model verify events using the **shared secret** and the `x-vol-hmac-sha256` header, as described in [Verify with the Shared Secret (V1)](#verify-with-the-shared-secret-v1).
* Applications on the enhanced (V2) security model verify events using a **dedicated webhook signing secret** and the `kibo-signature` header, as described in [Verify with the kibo-signature Header (V2)](#verify-with-the-kibo-signature-header-v2).
#### Verify with the Shared Secret (V1)
To verify the authenticity of an event, your application must generate a SHA 256 hash that matches the SHA 256 hash generated by the platform.
Here’s a description of how the hashing function works:
1. Use Base64 encoding.
2. Concatenate the application's shared secret with itself to get a starting key.
3. Generate a SHA 256 hash of the starting key.
4. Concatenate the Base64-encoded hash, event date from the request header, and request body.
5. Generate a second SHA 256 hash.
6. Encode the second SHA 256 hash using the Base64 encoding scheme.
7. Compare the SHA 256 hash in the request header (`x-vol-hmac-sha256";`) with the hash your application generated. Matching hashes confirms event authenticity.
**Tips:**
* Use the built-in hashing function in the [Node](https://github.com/mozu-customer-success/mozu-node-sdk-webtoolkit), [.NET](https://github.com/Mozu/mozu-dotnet-toolkit), and [Java](https://github.com/Mozu/mozu-java-toolkit) toolkits. You’ll have to write your own if you’re using another language.
* Enhance the security of your application by enforcing a time constraint on generating the SHA 256 hashes. Make sure you're application server is synchronized with the platform by using the [NIST Internet Time Service](http://www.nist.gov/pml/div688/grp40/its.cfm).
Here's an example of a POST request (header and body) coming from KCCP:
```
x-vol-correlation: 4e84d4304b6342a4a32eb0e9efba9a87
x-vol-tenant: 12345
x-vol-currency:
x-vol-locale:
x-vol-tenant-domain: t12345.sandbox.mozu.com
x-vol-site: 16772
x-vol-catalog: 3
x-vol-master-catalog: 1
Date: Tue, 01 Mar 2016 20:51:22 GMT
x-vol-hmac-sha256: n8R65NCMOoemLohdg0uMMZVdzOcJFrcUngon08D3e/g=
Content-Type: application/json; charset=utf-8
Host: 702443ca.ngrok.io
Content-Length: 211
X-Forwarded-Proto: https
X-Forwarded-For: 162.219.105.124
```
```
{
"eventId": "a585728e-18eb-49af-afea-a5bc0157b267",
"topic": "customeraccount.updated",
"entityId": "1001",
"timestamp": "2016-03-01T20:51:37.4784068Z",
"correlationId": "4e84d4304b6342a4a32eb0e9efba9a87",
"isTest": "false"
}
```
#### Verify with the kibo-signature Header (V2)
Applications on the [enhanced (V2) security model](/pages/application-asset-management#application-credentials-and-security) verify webhooks using a dedicated webhook signing secret, which is separate from the credentials used to authenticate API calls. Kibo signs each webhook and includes the signature in a `kibo-signature` header.
All existing webhook headers are preserved, so V2 webhooks continue to include headers such as `x-vol-tenant`, `x-vol-site`, and `x-vol-correlation`. The `kibo-signature` header is added alongside them:
```
kibo-signature: t=1707584123, v1=6cc75952c1e6e0f12702755e1..., v1=a1b2c3d4e5f6g7h8i9j0...
```
The header contains:
* `t=` — the Unix timestamp (in seconds) when Kibo generated the signature.
* `v1=` — one or more signature values. During normal operation a single `v1` value is present. During a [key rotation](/pages/application-asset-management#rotate-and-revoke-keys) window, Kibo signs with both the old and new signing secrets and includes both `v1` values so your endpoint keeps working while you update.
**How the signature is constructed**
Kibo uses HMAC-SHA256 with your webhook signing secret as the key. To prevent replay attacks, Kibo does not sign the JSON body alone — it signs the timestamp and the raw body together:
```
signed payload = t + "." + raw_json_body
```
* `t` is the same Unix timestamp found in the `t=` part of the header.
* `.` is a literal period that separates the two values.
* `raw_json_body` is the exact, unmodified request body. If your server parses or reformats the JSON before verifying (even changing a space or newline), the signature will not match.
**Verify an incoming webhook**
1. Read the `t=` timestamp and all `v1=` values from the `kibo-signature` header.
2. Reconstruct the signed payload as `t + "." + raw_request_body`, using the raw, unparsed body.
3. Compute an HMAC-SHA256 of the signed payload using your configured webhook signing secret.
4. Compare your computed signature against each `v1` value in the header. If it matches any of them, the webhook is authentic.
5. Reject the request if the `t=` timestamp is older than your allowed tolerance (5 minutes is recommended) to protect against replay attacks.
Because Kibo signs with both secrets during a rotation window, you can update your webhook signing secret with zero downtime: configure the new secret on your side at any point during the window, and verification continues to succeed against whichever `v1` value matches.
### Acknowledge Events
KCCP is expecting an HTTP status code in the 200 range in response from your application, but it’s important to acknowledge unsuccessful POST requests as well. You should send status codes back as soon as possible, otherwise KCCP will try to resend the event after 30 seconds and then continue periodically resending the event for up to 24 hours.
KCCP sends a unique ID for each event it tries to resend in the response body, even if it’s the same event.
### Prevent Infinite Callback Loops
Infinite loops can occur when your application subscribes to an event that can be triggered by events in a third-party system. To prevent this, make sure that the **Disable Callbacks** checkbox is checked when you add the event subscription to your application in Dev Center.
Click [here](/pages/application-asset-management#subscribe-to-an-event) for instructions on adding an event subscription to your application.
## Performance Optimization
The following sections contain best practices for improving the performance of your applications.
### Store Data in the Database (MZDB)
To use the MZDB effectively, you must have a general understanding of [entity lists and entities](/api-overviews/openapi_entities_overview). Entity lists are similar to database tables—describing the types of data that can be stored, which properties should be indexed for high-scale retrieval, and the list’s read/write security model. Currently, you can create entity lists with the API or API Extension applications. Entities are objects in an entity list and are similar to rows in a database table, while objects are rich JSON structures rather than fixed tabular rows. You can use entity lists to store and retrieve website content throughout the platform and third-party applications, such as creating and maintaining a list of physical store locations.
You can create as many fields as you want in a custom entity list, but you can only index a maximum of four. Indexing fields impacts application performance in different ways. There's a correlation between application performance and number of indexed fields in an entity list:
* Indexed fields *increase* the speed of read operations.
* Indexed fields *decrease* the speed of write operations.
An application that performs mostly read operations benefits from a higher number of indexed fields, but an application that performs mostly write operations will have slower performance as the number of indexed fields increases.
### Avoid Re-Fetching Slow-Changing Data on Every Request
If an [API Extension](/pages/getting-started-with-api-extensions) action fetches data that does not change frequently — such as a list of store locations, configuration values, lookup tables, or external CMS content — do not re-fetch it on every storefront request. Re-fetching adds latency to every page load and creates memory pressure on the platform under traffic. As an example, an action that fetches 1000 location records on every product search will accumulate significant latency and memory usage compared to an action that fetches the same records once and reuses them.
Strategies for reducing repeat fetches:
* **Filter at the source.** When you do have to fetch from an API, use [`responseFields`](#limit-data-returned-from-api-calls) and any available query filters to retrieve only the records and fields the action actually needs. Fetching a large amount of records using a large `pageSize` is a common cause of memory pressure.
* **Avoid chained sequential calls in hot actions.** If your action must make multiple outbound calls, run independent calls in parallel with `Promise.all()`. See [Calling External APIs Safely](/pages/programming-patterns#calling-external-apis-safely) for details.
### Limit Data Returned from API Calls
If you're developing an application that calls large JSON objects from the API, or if you’re doing targeted reporting (e.g., product pricing), you can use the `responseFields` URL parameter to filter the data returned inside a JSON object. Efficiently allocating application memory will help improve performance.
Only use the responseField parameter to retrieve data. Attempting to update data using this parameter may cause data loss.
For example, `commerce/catalog/storefront/products/{productcode}` returns a JSON object that looks like this:
```
{
"productCode":"1005",
"productSequence":"5",
"productUsage":"Standard",
"fulfillmentTypesSupported":[
"DirectShip",
"InStorePickup"
],
"goodsType":"Physical",
"content":{
"productName":"Piona Kailas Patent Pump",
"productFullDescription":"\\"Faux patent leather upperAlso available in a faux metallic & printed leather upper Ankle strap with an adjustable buckle\\1 hidden platform\\5 heel\\Synthetic sole",
"productShortDescription":"You'll be hot to trot in the Kailas by Piona. This sexy pump is is sure to draw some attention.",
"metaTagTitle":"",
"metaTagDescription":"",
"metaTagKeywords":"",
"seoFriendlyUrl":"",
"productImages":[
{
"imageUrl":"/files/64/1/1e3813e5-e60a-462b-a109-087682eb2a31",
"sequence":"1"
}
]
},
"purchasableState":{
"isPurchasable":"true"
},
"isActive":"true",
"publishState":"Live",
"price":{
"price":"60",
"priceType":"List",
"catalogListPrice":"60"
},
"productType":"Shoe_Women",
"productTypeId":"3",
"isTaxable":"true",
"pricingBehavior":{
"discountsRestricted":"false"
},
"inventoryInfo":{
"manageStock":"false"
},
"createDate":"2013-12-17T05:06:15.980Z",
"dateFirstAvailableInCatalog":"2013-12-17T05:06:15.980Z",
"daysAvailableInCatalog":"811",
"categories":[],
"measurements":{
"packageWeight":{
"unit":"lbs",
"value":"1.25"
}
},
"properties":[
{
"attributeFQN":"tenant~availability",
"isHidden":"false",
"isMultiValue":"false",
"attributeDetail":{
"valueType":"Predefined",
"inputType":"List",
"dataType":"String",
"usageType":"Property",
"dataTypeSequence":"1",
"name":"Availability",
"searchableInStorefront":"true",
"allowFilteringAndSortingInStorefront":"true"
},
"values":[
{
"value":"24hrs",
"stringValue":"Usually Ships in 24 Hours"
}
]
}
]
}
```
If you only need the call to return a product’s name and description, you can specify that in the response field. For example, `commerce/catalog/storefront/products/{product code}?responseFields=content(productName, productShortDescription)` returns a JSON object that looks like this:
```
{
"content": {
"productName": "Piona Kailas Patent Pump",
"productShortDescription": "You'll be hot to trot in the Kailas by Piona. This sexy pump is is sure to draw some attention."
},
"isTaxable": "true",
"createDate": "2013-12-17T05:06:15.980Z"
}
```
**Tips:**
* Access all nested fields inside an object property by specifying the property only, such as `?responseFields=property`.
* Use parentheses to access specific nested fields inside an object property. Use a comma-separated list to select multiple fields.
* Access multiple nested fields inside multiple object properties using the following syntax (comma-separated properties): `?=responseFields=property1(field1, field2), property2(field3, field4)`.
* When working with collection-based API endpoints (e.g., [GetProducts](/api-reference/storefrontproducts/get-products) vs. [Get Product](/api-reference/storefrontproducts/get-product)), you must use a different syntax to access fields inside JSON object properties. The GetProducts endpoint contains an `items` property that you must specify as the first property. For example, `?responseFields=items(content(productName), price(priceType), productCode)`.
# Application Development Requirements
Source: https://docs.kibocommerce.com/pages/application-development-requirements
The Kibo Composable Commerce Platform is designed for extensibility. Through our REST API, you have complete access to the operations and entities you need to develop applications. We also provide SDKs that you can use to write apps in the language of your choice.
See how to create a new application in the Kibo Dev Center
## Advantages of SDKs
Kibo strongly recommends using one of our [SDKs](/pages/sdk-overview) for app development. If you use an SDK, all of the following tasks are handled behind the scenes by the SDK:
* Routing requests to proper endpoint URLs
* Ensuring all calls to use the correct API context
* Authenticating your app
* Creating and regenerating access and refresh tokens
* JSON conversion
* Event handling and decrypting/validating event message
The remainder of this topic explains these concepts as they pertain to all applications. Refer to the readmes and code comments for each SDK for more specific information.
## Requests to the API
To facilitate application development, the API for all platform/application-level services is hosted behind a generic US or EU domain. You can make calls to either a production or sandbox environment, as well as optionally include a Site ID in addition to the required Tenant ID (which would make the Base URL `t10000-s00000` instead of `t10000`). The tp0 is your tenant's assigned production pod.
* Example US Sandbox Tenant: `https://t10000.sandbox.mozu.com/api`
* Example US Production Tenant: `https://t10000.tp0.mozu.com/api`
* Example EU Sandbox Tenant: `https://t100000.sb.euw0.kibocommerce.com/api`
* Example EU Production Tenant: `https://t100000.tp0.euw1.kibocommerce.com/api`
Your application can send requests to this domain by including it in the request path. For example, you can use the following path to send a production authentication request:
```
http://t00000.tp0.mozu.com/api/platform/applications/authtickets
```
Requests require the following:
* The authentication ticket your application uses to complete API calls
* The resource URI you want to query
* The API context in the request header
* The application must have the [appropriate behaviors](/pages/application-development-best-practices#application-behaviors "Application Development Best Practices") to access the API
## API Context
For any request your application sends, the request header must include an API context which often identifies the site and catalog you are referencing. If you use the hostname format that includes the site ID (t00000-s00000.tp0.mozu.com) then the master catalog, catalog, site, locale, and currency context are inferred by the site and do not need to be explicitly provided. Likewise, the tenant is usually not necessary in the header since the tenant ID is already included in the hostname.
The following is an example explicitly defining that context:
```
x-vol-tenant: 0000
x-vol-master-catalog: 1
x-vol-catalog: 1
x-vol-site: 11111
```
### Supported Headers
If you are using one of the SDKs to develop your application, you can look at the ApiContext and Headers files at the top level of the source directory to see how the API context is implemented and what headers you can include in your requests. Otherwise, refer to the [API documentation](/pages/making-api-calls) for a full list of possible headers.
## Authentication
Any application that calls into the API must authenticate. When you [create an application in the Dev Center](/pages/application-asset-management), an Application Key/ID and Secret is generated. You use these values to authenticate, which will return your access and refresh tokens.
See the Application Authentication API specs for more details about the auth operations: there is a [standard auth call](/api-reference/appauthtickets/app-authenticate) and an [OAuth 2.0 JWT call](/api-reference/appauthtickets/oauth-authenticate-app), which have slightly different requests and responses.
### Environment-Specific Credentials (V2)
The original (V1) security model, in which a single shared secret is used everywhere, is being deprecated. All applications will need to move to the enhanced (V2) security model, which authenticates with environment-specific credentials. The credential you use depends on the environment you are calling:
* **Sandbox auth keys** authenticate only against Sandbox tenants.
* **Production auth keys** authenticate only against Production tenants.
Each credential consists of a **Client ID** and a secret. The Client ID identifies the specific credential and can be rotated or revoked on its own; it is formed by prefixing the key's name to the Application Key (for example, `NewKey.kadmin1.AppTest.1.0.0.Release`). The **Application Key** remains the app's immutable identifier used for logging, reporting, and permissions. Authenticate exactly as you would with V1 credentials, but supply the Client ID and secret for the environment you are targeting. For details on generating, viewing, and rotating these credentials, see [Application Credentials and Security](/pages/application-asset-management#application-credentials-and-security).
SDKs also include logic that handles authentication for you using your API context and the Application Key and Shared Secret. For example, if you are using the [.NET SDK](https://github.com/Mozu/mozu-dotnet), you can add this information to the app.config file:
```
…
```
### Access and Refresh Tokens
An **access token** establishes an application’s identity. When an app calls a specific API operation, the access token is passed as part of the application claims information in the request header.
**Refresh tokens** allow an application to refresh an expired access token without re-authenticating the entire application. After the access token expires, the refresh token can use the Application Key and Shared Secret to generate a new authentication ticket that contains the same refresh token and refresh token expiration, but contains a new access token and access token expiration.
Both access tokens and refresh tokens are subject to expiration. After the refresh token expires, you must generate a new authentication ticket. Access tokens are viewable and readable for external programs. Refresh tokens should never be shared. Always protect information about your refresh token and shared secret.
### Generate an Authentication Ticket
1. Copy your Application Key and Shared Secret from Dev Center. Go to **Develop** > **Applications** and double-click the app you are developing to view this information.
2. In your external application, run a POST operation to the platform/applications/authtickets or platform/applications/authtickets/oauth resource. You can do this to the sandbox.mozu.com host for testing on a sandbox environment, while your complete and certified app will make requests using the production URL.
3. In the request body, enter the Application Key/ID and Secret. All current applications use the full Application Key value for the ID. Legacy applications use the Application ID instead of the full Application Key. The Application ID can be found as part of the full Key: `...`.
The system returns the refresh token, access token, and expiration information.
### Refresh an Authentication Ticket
If you used the platform/application/authtickets method and the access token has expired but the refresh token is still valid, complete the following steps to refresh the authentication ticket:
1. Run a PUT operation to the [platform/applications/authtickets/refresh-ticket](/api-reference/appauthtickets/refresh-app-auth-ticket) URL.
2. In the request, enter the refreshToken value string.
The system returns the refresh token, access token, and new expiration information.
## Run Operations from an Application
After you [provision a sandbox](/pages/set-up-your-system#provision-a-sandbox), [install an application](/pages/set-up-your-system#install-development-assets-on-a-sandbox) in that sandbox, and generate an authentication ticket for the application, you can begin to run API operations using the application.
Running an operation in the API consists of the following procedures:
* Retrieve the tenant ID
* Retrieve the domain name for the URI endpoint
* Use the tenant URL to perform API operations
### Retrieve the Tenant ID
You can view the tenant ID for a sandbox in the sandbox URL in Admin, or you can get it programmatically using the API:
1. In the Tenants resource, run a GET operation using the following URL: `http://t00000.tp0.mozu.com/api/platform/tenants`
2. In the request body, note the tenantID value.
### Retrieve the Domain Name for the URI Endpoint
To retrieve the domain name the application uses to run API operations in a development store, complete the following procedure:
1. In the application, in the Tenants resource, run a GET operation using the following URI: `http://t00000.tp0.mozu.com/api/platform/tenants/{tenantid}`
2. In the request URI, enter the tenant ID you retrieved in the previous procedure.
3. In the request body, note the following information:
* The DomainName value for the tenant, which appears as: `{tenantID}.{host name}.mozu.com`
* The master catalog ID values for the tenant.
* The catalog ID values for the tenant.
* The site ID values for the tenant.
### Use the Tenant URL to Perform API Operations
To use the sandbox domain name for the development store to begin performing API operations using the application, complete the following procedure:
1. In the application, run the operation you want to perform, using the URL retrieved in the previous procedure: `{domainname}/api/{resourcepath}`
2. In the request header, specify the [API context](#api-context).
# Application Settings
Source: https://docs.kibocommerce.com/pages/application-settings
Applications extend or replace existing Kibo Composable Commerce Platform functionality, such as the Avalara AvaTax Integration that replaces default tax functionality with Avalara's AvaTax functionality. After applications are installed on your tenant, you must enable them before you can use them.
## Enable or Disable Applications
To enable or disable applications:
1. Go to **System** > **Customization** > **Applications**.
2. Select the application you want to change.
3. Click **Enable Application** to toggle it on or off.
For more information about applications, visit the [Kibo Marketplace](https://www.kibocommerce.com/marketplace/).
Refer to each application's guide in the [Apps & Integrations](/pages/applications-1a6c791-introduction) section for information on using the specific application.
# Introduction
Source: https://docs.kibocommerce.com/pages/applications-1a6c791-introduction
You can build and install applications in sandboxes to extend the functionality of the Kibo Composable Commerce Platform (KCCP) and integrate with external systems. Applications can have multiple versions with behaviors and events specific to each version. Refer to [Application Development Best Practices](/pages/application-development-best-practices) for answers to common development questions and helpful tips.
The rest of this topic guides you through concepts essential to KCCP applications:
## Manage an Application
You manage applications in Dev Center. By navigating to **Develop** > **Applications**, you can:
* View existing applications.
* Create new applications.
* Install applications to sandboxes.
* Manage application versions.
* Configure behaviors, events, attributes, and capabilities.
* Submit an application for certification.
By clicking on an existing application record, you can also view the **Application Key** and **Shared Secret**, which are essential for authenticating your application.
## Assign Permissions through Behaviors
One of the most important tasks to complete when developing an application is to to assign appropriate behaviors to the application. For example, if you want your application to update a Customer record, you need to assign it the **Customer Update** behavior. Without behaviors, an application does not have permissions to read, update, create, or delete any data.
To assign application behaviors, go to **Packages** > **Behaviors** within a Dev Center application record. An application can have any number of behaviors based on the functions the application must perform. You can select individual behaviors or apply an entire category of behaviors to the application.
## Subscribe Applications to Events
You can subscribe applications to various events. When the specified event occurs, a trigger is routed to a configured endpoint. For example, if you subscribed your application to the product.created event, KCCP triggers a notification to the specified endpoint every time a new product is created in the sandbox where the application is installed.
To add event subscriptions, go to **Packages** > **Events** within a Dev Center application record. Refer to [Event Subscription](/pages/event-subscription) for more information.
## Install Attributes
To specify the attributes an application should access without having to first create those attributes in Admin , go to **Packages** > **Attributes** within a Dev Center application record.
Installing attributes for an application is an advanced use case that may cause conflicts with importing and exporting data using the [eCommerce Import-Export Application](/pages/introduction-to-import-export) or similar means. Contact Kibo for detailed instructions on using this feature.
## Add a Capability
Capabilities allow you to specify an endpoint URL to integrate with an external service. They provide ready-made integration points for common platform extensibility needs. All capabilities are registered through Dev Center under **Develop > Applications > Packages > Capabilities**.
The platform supports four publicly available capability types:
| Capability Type | Scope | Description |
| ------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------- |
| [`OrderValidator`](/pages/order-validators-and-fraud-check-applications) | Per-site (multiple allowed) | Order-level validation — e.g., fraud detection |
| [`AddressValidator`](/pages/address-validator) | Per-site per shopping country | Address validation for customer/order addresses |
| [`TaxCalculator`](/pages/creating-a-new-tax-integration) | Per-tenant per shopping country | Custom tax calculation |
| [`PaymentGatewayAdapter`](/pages/payment-gateways) | Per-site (multiple allowed) | Payment gateway integration |
`OrderValidator` and `PaymentGatewayAdapter` are the only two capability types that support multiple active instances simultaneously — the others are single-instance within their scope.
## Code Your Application
The following are the essential resources you use to code a custom application:
* **[Application Development Requirements](/pages/application-development-requirements):** this topic specifies the code requirements needed to interface with the platform, such as obtaining an API context and authenticating your application.
* **[The Kibo Composable Commerce Platform REST API](/pages/getting-started-with-api-extensions):** the primary interface that connects the pieces of the platform together, and the primary tool that allows developers to build custom applications. The API provides a multitude of resources, such as the Customer resource or the Orders resource, that give you access to nearly every aspect of the KCCP experience. Each resource contains unique operations, such as the GetCart or UpdateCart operations, that let you manipulate objects.
* **[SDKs](/pages/sdk-overview):** When developing your own applications, you can use SDKs to develop in common languages like .NET, Java, and Node.js.
* **[API Extensions](/pages/what-you-can-do-with-api-extensions):** When developing your own applications, you can use API Extensions to directly manipulate API operations and microservice logic.
## Specify a Configuration URL
An application's configuration URL allows you to specify an external endpoint for initial application setup. The endpoint renders a user interface that application users can launch from Admin to configure the basic settings for the application.
To specify a configuration URL, go to **Packages** > **Details** within a Dev Center application record.
# Apply Tags to Inventory Records
Source: https://docs.kibocommerce.com/pages/apply-tags-to-inventory-records
If tags have been enabled, then every single inventory record will be associated with those tags. However, items do not need to have tags specified in the order data. If an item does have a tag name provided in the order, then an associated value must be included as well.
For example, if your configuration has the tags OrderType and Channel and you only care about a certain item's OrderType, then specify the OrderType tag and its value. Do not include the Channel tag and it will be set to the default. If neither of these tags mattered for the product, then would exclude them both from the item data.
## Set Tags via API
An example of an [Inventory Refresh call](/api-reference/modifyinventory/refresh) that sets inventory data with discrete tag values:
```text theme={null}
{
"locationCode": "examplelocation",
"items": [
{
"upc": "AD1001",
"quantity": 100,
"tags": {
"Channel": "Warehouse"
}
},
{
"upc": "AD1001",
"quantity": 50,
"tags": {
"Channel": "Target"
}
}
]
}
```
By default, the `quantity` provided in this request (as well as in the inventory file import shown below) is used for the On Hand value. The system will then calculate the appropriate Available amount. If you want to change this behavior so that `quantity` is applied directly as the Available inventory value, contact [Kibo Support](https://help.kibocommerce.com/) to update your tenant configurations.
## Upload Tagged Inventory Files
The [inventory import process](/pages/inventory-import-file) also supports segmentation, so you can use this file upload to apply your tags instead of doing it via API. To do this, add the tag name as a column header after the default headers and insert the tag value into the column value. The example below shows a sample file with Channel and OrderType tag columns:
```text theme={null}
LOCATIONCODE,PARTNUMBER,UPC,SKU,QUANTITY,DELIVERY_DATE,Channel,OrderType
Spatula_LA_WH,SpatulaTestPartNumber,SpatulaTestUPC,SpatulaTestSKU,10,,,
Spatula_DAL_WH,SpatulaTestPartNumber3,SpatulaTestUPC3,SpatulaTestSKU3,30,,Amazon,CarrierPigeon
```
## Redistribute Tagged Inventory
Inventory should be periodically redistributed between your channels based on the allocation percentages. You can do this on-demand by calling the [Inventory Redistribution API](/pages/inventory-api-overview#inventory-redistribution "Inventory API Overview") with the UPCs and/or location codes you want to redistribute across. Asynchronous redistribution will then occur at the next Refresh or Adjust update to restore the appropriate amount of inventory to the designated channels.
## Apply Tags via the new Supply/Demand UI
**Note:** This option is only available in the new Supply/Demand UI. Contact [Kibo Support](https://help.kibocommerce.com/) to opt in. All sandbox tenants will receive the new UI on July 21.
In the new UI, you can assign a tag to an inventory record directly from the Supply Demand UI at the point of creation — no API call or file import required.
**Prerequisite:** Inventory Tags must be enabled for your tenant. Go to **Main > Orders > Inventory > Settings > Inventory Tags** to enable. If Tags are disabled, the tag selector will not appear in the Create drawer.
1. Go to **Main > Orders > Inventory**.
2. Click **+ Create Inventory**. The Create drawer opens on the right.
3. Enter the **UPC / Product Code** and select a **Location**.
4. In the **Tag** field, select the tag you want to assign this record to.
If no tag is selected, the record is created at the UPC-location level (untagged). Previously, the only way to create tag-level records was via the API or file import.
5. Enter **On Hand** and any other applicable quantity values.
6. Click **Save**.
The record is created at the selected tag level. To verify, open the record via **View** or **Edit** and select the **Tags tab** to see per-tag On Hand, Available, and Allocated quantities.
# Associate Credit to Shopper (After)
Source: https://docs.kibocommerce.com/pages/associate-credit-to-shopper-after
**Related API:** This extension modifies the [Associate To Shopper](/api-reference/credit/associate-credit-to-shopper) operation.
This action manipulates the HTTP request or response after the AssociateCreditToShopper operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.associateCreditToShopper.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/associateCreditToShopper](/api-reference/credit/associate-credit-to-shopper) operation.
**HTTP Request**
PUT `api/commerce/customer/credits/{code}/associate-to-shopper?responseFields={responseFields}`
**Request Body**\
No request body content.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Associate Credit to Shopper (Before)
Source: https://docs.kibocommerce.com/pages/associate-credit-to-shopper-before
**Related API:** This extension modifies the [Associate To Shopper](/api-reference/credit/associate-credit-to-shopper) operation.
This action manipulates the HTTP request or response before the AssociateCreditToShopper operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.associateCreditToShopper.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/associateCreditToShopper](/api-reference/credit/associate-credit-to-shopper) operation.
**HTTP Request**
PUT `api/commerce/customer/credits/{code}/associate-to-shopper?responseFields={responseFields}`
**Request Body**\
No request body content.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Attribute Localization
Source: https://docs.kibocommerce.com/pages/attribute-localization
If you have created an international catalog, a Localization section will appear in the System menu. This section includes several pages where you set localized values for product attributes in different languages and currencies.
Learn about product catalog architecture and management
## Localization Pages
These pages allow you to localize values at the master and child catalog levels. However, you are not able to create new attributes or edit their other configurations from these pages.
* **Attributes**: Translate the name of each attribute at the master catalog level.
* **Attribute Values**: Translate each individual value of every attribute at the master catalog level, e.g. all color possibilities for the attribute tenant\~color.
* **Product Properties**: Translate product property text at the child catalog level.
* **Product Extras**: Translate product pricing extras at the child catalog level, allowing you to set prices for different currencies.
* **Product Variants**: Translate product variation pricing at the child catalog level, allowing you to set prices for different currencies.
On each page, you can expand the drop-down menu in the top right corner of the table to customize which columns are displayed. You can also click any column header to sort by the values in that column.
### Attributes and Attribute Values
The Attribute page only controls the name of the attribute itself, not the possible values. Make sure you select the correct master catalog from the options above the table.
The Attribute Values page is where you localize the individual values of those attributes. Again, make sure you select the correct master catalog.
### Product Properties
In this page, you localize product property text at the child catalog level. Make sure you have selected the correct master catalog from the options above the table. You will be able to switch between the child catalogs of this master catalog as needed for translation.
If you switch to a non-English locale, an additional column for that language will appear in addition to the en-US configuration. This allows you to reference the English text while translating.
### Product Extras and Variants
The Product Extras and Product Variation Pricing pages are similar to the Product Properties page. They both require you to select a master catalog and allow you to switch between child catalogs for different locales. Here, you localize the pricing options based on currency.
In this Product Extras Pricing page, switching between the English and French catalogs would allow you to set different prices for USD and EUR, which overrides the master catalog pricing (which is in USD by default and displayed for reference).
The Product Variation Pricing page includes more editable fields to support product variants including MSRP, Extra Price, and Extra Credit Price.
Localizing variation prices is required, not optional, whenever a child catalog's currency differs from its master catalog's currency. Unlike product extras, product variations do not fall back to the master catalog price: any configurable product whose variations are unpriced in the child catalog's currency will not appear on that catalog's storefront. Refer to [Multi-Currency Catalogs](/pages/multi-currency-catalogs "Multi-Currency Catalogs") for the full workflow, including the API equivalent of this page.
# Auto-Add Free Product Discount
Source: https://docs.kibocommerce.com/pages/auto-add-free-product-discount
The Auto-Add Free Product Discount feature enables you to set free products to be automatically added to a shopper's cart if they meet certain criteria, instead of requiring that shopper to go and search for the product when they become eligible for it.
## Use Cases
### Auto-Add Gift Card
You create a discount in which the condition is product A and the target is a \$25 gift card. You select the auto-add free product discount type in the Discounts page. The gift card is automatically added to the end consumer's cart when they add Product A to their cart.
#### Multiple Auto-Add Discounts Applying to Same Target Product
You create two discounts:
1. Buy Product A, get Product B for free
2. Buy Product A, get Product C for free
Where:
1. Adds Product A (quantity 1) to their cart. The system determines which free product is the better deal to the consumer and adds it to the cart as part of the winning discount. If Product B and C are considered the same value, the system uses the first discount run and adds that target product to the cart.
2. Adds two copies of Product A to their cart and one of your discounts has a max redemption of 1 set. If the better deal is the discount with the max redemption, both discounts can be applied, giving the shopper both Product B and C for free. If the better deal is not the discount with the max redemption, then the shopper will receive the same target product with each copy of Product A.
3. Adds two copies of Product A to their cart and both of your discounts have a max redemption of 1 set. The shopper receives both Product B and C.
## Effect on Discounts
### Auto-Add Discount Competing with Other Line Item Discounts
When applying an auto-add discount and a line item product discount to the same target product, the system selects the discount that provides the best deal for the shopper after the free product is added to the cart. If the system does not choose the auto-add discount, the free product returns to full price, remains in the cart, and must be removed by the shopper.
#### Auto-Add Free Products without Setting a Condition
Discounts with or without coupon codes must have any other product in cart before the free product is auto-added to cart. For example, if the shopper has a coupon code for a free product but no items currently in their cart, the shopper must add an item first, and then enter the coupon code to receive the free product.
#### Removing and Re-Adding Free Products from Cart
If the shopper removes the free target item from cart, the item will no longer be auto-added. However, if the shopper manually re adds the free target item manually, they will again see the item as free.
## Enable the Auto-Add Free Product Discounts Feature
This feature requires changes to your core theme. Ask your theme developer to make the required changes to your theme to enable this feature, as detailed in the following GitHub pull requests:
* [GitHub Pull Request 1](https://github.com/Mozu/core-theme/commit/032474fc52d0bbd7665878d1de2c60efc0efa3ea)
* [GitHub Pull Request 2](https://github.com/Mozu/core-theme/commit/3159ae7f25fbee68e9c6cb2a2ce7989e8c53e173)
### Set Up Auto-Add Target Discounts
To set up a discount to auto-add free products:
1. Go to **Sell** > **Discounts** in Admin.
2. Select either an existing discount or **Create Discount**.
3. Set the **Applies To** field to **Line Item** and the **Affects** field to **Product**. This enables you to view the **Auto Add Free Product** option in the **Type** field.
4. Set the **Type** field to **Auto Add Free Product**.
## Headless and Custom Storefront Implementation
The platform does not add the free product to the cart by itself. Instead, it signals eligibility via a `suggestedDiscounts` array on the `Cart` object. Your storefront is responsible for reading this signal and acting on it. Storefronts built on the Kibo Core Theme have this logic built in. Headless and custom storefronts must implement it manually using the steps below.
### How It Works
Every time the cart is modified (item added, updated, or removed), Kibo re-evaluates all active discounts and updates the `suggestedDiscounts` array on the cart. Each entry in this array tells your storefront whether a free product should be added, and how.
#### The `suggestedDiscounts` Object
```json theme={null}
{
"suggestedDiscounts": [
{
"discountId": 1001,
"productCode": "FREE-WIDGET",
"autoAdd": true,
"hasMultipleProducts": false,
"hasOptions": false
}
]
}
```
| Field | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `discountId` | The ID of the discount driving this suggestion |
| `productCode` | The product code of the free item to be added |
| `autoAdd` | `true` = add silently without shopper interaction. `false` = shopper input required, or item was previously rejected |
| `hasMultipleProducts` | `true` = multiple free products are eligible; shopper must choose one |
| `hasOptions` | `true` = the free product has configurable variants; shopper must select options |
### Step 1 — Mutate the Cart
When the shopper adds, updates, or removes a cart item, call the appropriate endpoint:
```text theme={null}
POST /api/commerce/carts/current/items (add item)
PUT /api/commerce/carts/current/items/{id} (update item)
DELETE /api/commerce/carts/current/items/{id} (remove item)
```
These endpoints return the individual `CartItem` that was added or updated — they do not return the full cart object. You must make a follow-up call (Step 2) to check for suggested discounts.
### Step 2 — Fetch the Full Cart
After every cart mutation, immediately call:
```text theme={null}
GET /api/commerce/carts/current
```
This returns the full `Cart` object, including the `suggestedDiscounts` array.
**Example response:**
```json theme={null}
{
"id": "cart-abc-123",
"items": [...],
"suggestedDiscounts": [
{
"discountId": 1001,
"productCode": "FREE-WIDGET",
"autoAdd": true,
"hasMultipleProducts": false,
"hasOptions": false
}
],
"rejectedDiscounts": []
}
```
### Step 3 — Evaluate Each `suggestedDiscount` Entry
Loop through each entry in `suggestedDiscounts` and apply the following logic.
#### Case 1: `autoAdd: true` — Silently Add the Free Product
When `autoAdd` is `true` and both `hasMultipleProducts` and `hasOptions` are `false`, add the free item to the cart automatically without any shopper interaction.
**Call:**
```text theme={null}
POST /api/commerce/carts/current/items
```
**Request body:**
```json theme={null}
{
"product": {
"productCode": "FREE-WIDGET"
},
"quantity": 1,
"autoAddDiscountId": 1001
}
```
`autoAddDiscountId` is required. Setting this field tells the platform this item was added as part of a discount. Without it, the platform will not be able to automatically remove the free item if the qualifying product is later removed from the cart, and shopper rejection will not be tracked correctly.
**Example pseudocode:**
```javascript theme={null}
for (const suggestion of cart.suggestedDiscounts) {
if (suggestion.autoAdd && !suggestion.hasMultipleProducts && !suggestion.hasOptions) {
await addCartItem({
product: { productCode: suggestion.productCode },
quantity: 1,
autoAddDiscountId: suggestion.discountId
});
}
}
```
#### Case 2: `hasMultipleProducts: true` — Show a Product Selection Modal
When multiple products are eligible as the free gift, the shopper must choose one. Display a modal or UI component listing the eligible products.
Once the shopper selects a product, add it:
```json theme={null}
{
"product": {
"productCode": "WIDGET-GREEN"
},
"quantity": 1,
"autoAddDiscountId": 1001
}
```
#### Case 3: `hasOptions: true` — Show a Variant/Configurator Modal
When the free product has required options (e.g. size, color), the shopper must select them before the item can be added. Display a product configurator or variant picker.
Once the shopper has selected their options, add the fully configured item:
```json theme={null}
{
"product": {
"productCode": "FREE-WIDGET",
"options": [
{ "attributeFQN": "tenant~size", "value": "L" },
{ "attributeFQN": "tenant~color", "value": "Blue" }
]
},
"quantity": 1,
"autoAddDiscountId": 1001
}
```
#### Case 4: `autoAdd: false` with No Other Flags — Shopper Previously Rejected
If `autoAdd` is `false` and neither `hasMultipleProducts` nor `hasOptions` is `true`, the shopper has already explicitly removed the free item from their cart during this session. The platform tracks this in `cart.rejectedDiscounts`.
Do not re-add the item or re-show the modal. Respect the shopper's choice for the remainder of the session.
```javascript theme={null}
// Do nothing — shopper already rejected this discount
if (!suggestion.autoAdd && !suggestion.hasMultipleProducts && !suggestion.hasOptions) {
return;
}
```
### Step 4 — Handle Qualifying Product Removal
If the shopper removes the product that qualified them for the discount, the platform will automatically remove the free item from the cart on the next re-price. When you call `GET /api/commerce/carts/current` after the removal, the free item will no longer appear in `cart.items` and `suggestedDiscounts` will be empty. No additional storefront action is required — simply re-render the cart from the response.
### Complete Decision Flow
```text theme={null}
After every cart mutation → GET /api/commerce/carts/current
|
+-- for each entry in suggestedDiscounts:
|
+-- autoAdd: true, no other flags
| +-- Silently POST add free item (with autoAddDiscountId)
|
+-- hasMultipleProducts: true
| +-- Show product selection modal → POST add chosen item (with autoAddDiscountId)
|
+-- hasOptions: true
| +-- Show variant/configurator modal → POST add configured item (with autoAddDiscountId)
|
+-- autoAdd: false, no other flags
+-- Shopper rejected — do nothing
```
### Key Rules
| Rule | Detail |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Always GET the full cart after mutations | `POST/PUT/DELETE /items` returns a `CartItem`, not the full cart — `suggestedDiscounts` is only on `GET /api/commerce/carts/current` |
| Always set `autoAddDiscountId` | Required when adding a free item so the platform can manage its lifecycle |
| Never re-add a rejected item | If `autoAdd: false` with no other flags, the shopper removed it — honor that for the session |
| Qualifying item removed = free item removed | The platform handles this automatically — just re-render from the GET response |
| Re-check after every mutation | `suggestedDiscounts` is re-evaluated on every cart change — always check after add, update, and remove operations |
# Avalara Application
Source: https://docs.kibocommerce.com/pages/avalara-application
![Avalara logo]() |
| Platforms: Legacy eCommerce, KCCP eCommerce and eCommerce+OMS |
[Avalara](http://www.avalara.com/) is a leading provider of tax calculation logic, sales tax returns, and services for small to large businesses conducting ecommerce transactions. Their leading product AvaTax aids thousands of companies with tax decision automation, accurately calculating the sales tax at local, state, and international levels including tax exemption and reseller certificates, tax processes, and file and remit returns.
The Avalara Application integrates your Avalara account and services to perform all sales tax and return calculations for every shopping cart and submitted order. The AvaTax services integrates through this app with eCommerce to provide seamless tax calculation support for all aspects of your business.
### Application Features
* Address validation
* Tax calculation based on rules you set in Avalara
## Install the App
For assistance installing the application, please reach out to your SI partner or Kibo's professional services and enablement team.
### Configuration Requirements
To configure Avalara to work seamlessly with eCommerce, you need specific items installed and settings provided. This guide details each step from requirements to final configuration for calculating taxes on orders.
You must meet the following criteria to configure the Avalara application:
* You must have the Avalara application installed on your tenant.
* You must have an active AvaTax account with Avalara.
* You must create and configure your company information in the AvaTax system.
You configure both address validation and tax configuration from the same dialog, so you do not need to configure each capability separately; however, you must enable each capability separately.
## Configure the App
1. In Admin, go to **System** > **Customization** > **Applications**.
2. Click **Avalara Tax Calculator and Address Validator**.
3. Set the **Shipping Country** to **US**.
4. Click **Configuration**.
The first time you launch the configuration screen, it behaves as a wizard, walking you through the different tabs in the order they need to be configured. After the initial configuration, you can freely navigate through the tabs to set specific information.
### Configure Account Settings
1. Click the **Account** tab.
2. Enter your Avalara **Account Number** and **License Key**. You receive this information from Avalara.
3. Select the environment to use. Use **Development** if you are testing your account in the Avalara sandbox. Use **Production** for live tax calculations.
4. Click **Test Account** to ensure you can successfully connect to your Avalara account from eCommerce and that there are no errors in your credentials.
5. Click **Save** to commit your changes.
### Configure Company Codes
The Company Codes tab allows you to map your tenant and sites to corresponding company codes defined in your Avalara account.
The app automatically populates the tab with the sites available in your tenant. You can select different company codes for each level so that different sites log tax transactions to different company names in Avalara. You must have at least one company code that maps to a tenant or a site.
1. Go to the **Company Codes** tab. The **Name** column displays each tenant with the associated sites in eCommerce, as marked in the **Type** column.
2. Enter an Avalara code in the **Company Code** column per tenant/site as needed. If the names do not exactly match, the application returns an error.
3. When you are done mapping, click **Verify Company Codes** to ensure the information you entered into the eCommerce application matches the information you have stored in Avalara.
4. Click **Save**.
### Configure Taxable Territories
You can select countries/nations for taxable purchases through the **Taxable Territories** tab. Each territory may include states and provinces, displayed in the table. These territories can be set as taxable per eCommerce site, associated through the company code associations made between eCommerce and Avalara.
1. Go to the **Taxable Territories** tab.
2. Select a eCommerce site from the drop-down menu.
3. Enable the checkboxes for each territory you want to set as taxable for purchases.
4. (Optional) Click **Configure** for a particular territory if you want to mark a subset of the states or provinces of that region as taxable. For example, you can mark the United States as a taxable country, but configure Texas as the only taxable state.
5. Enable **Product Tax Included** if the product cost listed in eCommerce already includes tax. This prevents double taxation in the Avalara system.
6. Enable **Shipping Tax Included** if the shipping cost listed in eCommerce already includes tax. This prevents double taxation in the Avalara system.
7. Click **Verify Company Codes** to have Avalara validate the associations and configurations in Avalara to support the selections made.
8. Click **Save**.
### Configure Tax Codes
Tax Code is a required field for products, so you must select a code for every new product you configure. Tax codes are available in a pull-down menu in your Product configuration page. One company code can have multiple tax codes. You can enter tax codes individually, but Kibo recommends importing your tax code information from Avalara.
#### Import Tax Codes
1. In Avalara, export your tax codes. You must format the exported file with each Tax Code and Description separated by a Tab stop character.
2. Click the **Tax Codes** tab.
3. Click **Import** in the Tax Codes dialog.
4. Click **Save** to commit your changes.\
**Caution:** Deleting entries from the Tax Code grid is only available *before* saving your settings. Once you save, you cannot edit or delete existing Tax code entries.
#### Manually Add Tax Codes
1. Click the **Tax Codes** tab.
2. Enter a **Shipping Taxcode**.
3. Enter a **Handling Free Taxcode**.
4. For Product Tax Codes, enter a **Tax Code** and **Description**. Click **Add**. Repeat for every tax code you need to add.
5. Click **Save** to commit your changes.\
**Caution:** Deleting entries from the Tax Code grid is only available *before* saving your settings. Once you save, you cannot edit or delete existing Tax code entries.
## Configure Map Attributes
The Map Attributes tab allows you to map order attributes for Avalara to use to read BIN and JurisCode data.
1. Select the **Map Attributes** tab.
2. Select a bin attribute from the **Bin Attribute** drop-down menu.
3. Select a JurisCode from the **JurisCode Attribute** drop-down menu.
4. If applicable, select a custom entity code attribute.
5. Select which field you want your customer code to be mapped to: the customer's email ID, their account ID in Kibo, or an external ID.
6. Select **Save**.
## Enable the App
1. In Admin, go to **System** > **Customization** > **Applications**.
2. Double-click **Avalara**.
3. Click **Enable App** on the Avalara page.
# B2B Attributes
Source: https://docs.kibocommerce.com/pages/b2b-attributes
B2B attributes are similar to [customer attributes,](/pages/customer-attributes) but applied specifically to B2B accounts or individual users. For instance, a "birthdate" or "gender" attribute could be used for a user, while a "logo" attribute could be used for an account.
As with customer attributes, you can configure B2B attributes to display only in Admin, or in both Admin and on the storefront. You can also specify whether the definition or selection of associated values can be done by shoppers, administrators, or both. You can choose various input and data types with various input parameters.
## Create a B2B Attribute
To create a B2B attribute:
1. Go to **System** > **Schema** > **B2B** **Attributes**.
2. Click **Create New B2B Attribute**.
3. Enter an **Attribute Label**. Keep in mind that this may appear on the storefront if you specify it to display there with the next step.
* If you want to give it a different name for administration purposes, edit the **Administration Name**. The default name is the **Attribute Label**.
* If you want to customize the **Attribute Code**, edit the value accordingly. This field automatically populates based on the **Attribute Label**.
4. Select a **Display Group**. This field determines whether the attribute displays in the Admin UI only or in both the Admin and storefront.
5. Select a **Value Source** to determine whether this attribute's value can be set via the Admin UI and/or Storefront. If you chose the Admin Only display group, then Admin Entered is the only valid source.
6. Toggle on **Available for Discounts** if you want this attribute to be available for use in [discount conditions](/pages/configure-discounts#attribute-conditions).
7. Toggle on **Available as Order Routing Filter** if you want this attribute to be available for use in order routing filters. When enabled, this attribute will appear under **Custom B2B** **Attributes** in the Order Routing filters. This option is disabled by default
8. Select an **Input Type**.
* If you choose **List**, select a **Data Type** and enter the selection options in the **Values** field.
* If you choose **Text box**, select a **Data Type**. Optionally, you can define input parameters in the **Min char/val** and **Max char/val** fields, or enter a regular expression in the **Input validation** field.
* If you choose **Text area**, you can optionally define a **Max char** value.
* If you choose **Date**, you can optionally define a start and/or end date for the selectable range.
9. Click **Save**. The attribute can now be applied to either account configurations or individual users, as with customer attributes.
# B2B Order Release
Source: https://docs.kibocommerce.com/pages/b2b-order-release
If you want to prioritize fulfilling certain B2B account's orders over other B2B or B2C orders with the same items, you can enable "order release." When there are orders in the Pending Shipment status for multiple customers or accounts, orders will move out of this state and proceed to fulfillment based on the account priorities that you set.
## Enable Order Release
Enable B2B Order Rules in your site settings to configure your order release method:
1. Go to **System** > **Settings** > **General** > **Site**.
2. Scroll down to Fulfillment Settings and toggle on **Enable configurable shipment release**. This is what allows orders to be held in a [Pending Shipment state](/pages/configure-shipment-creation#pending-shipments-status "Configure Shipment Creation") before being released for fulfillment.
3. Enter an integer between 1-7200 in **Release orders \_ mins after order submit.** This is required whenever configurable shipment release is enabled.
4. Ensure that **Reserve inventory when order status is PendingShipment** is disabled, otherwise B2B order rules will not be available.
5. Enable **B2B Order Rules**.
6. Select whether you want to **Manually release orders** (the default behavior that requires Admin users to [initiate release of orders for fulfillment](#manual-order-release)) or **Automatically release orders every \_ mins** and enter a value (in which orders will be released for fulfillment at the configured interval). This will be the method in which orders are released based on account priority. Any orders that are not released as part of B2B Order Rules will be released according to the **Release orders \_ mins after order submit** setting instead.
7. Click **Save**.
Enabling B2B Order Rules also allows you to create [purchase limit rules](/pages/purchase-limit-rules "Purchase Limit Rules"), meaning that orders will be validated at the time of release to ensure they do not exceed any quantity restrictions you have set. This is not required, but may be configured if you want to further fine-tune your B2B fulfillment process.
## Set Account Priority
Account priority determines which orders get released first, in numerical order and in entirety before moving to the next account. This means that if Company A has a priority of 1 and Company B has a priority of 3, and there are 10 orders from Company A and 1 from Company B, then all 10 Company A orders will be released before Company B's single order.
While [configuring the B2B account](/pages/manage-b2b-accounts "Manage B2B Accounts"), enter an integer as shown below to set the priority of the account as shown below. Multiple accounts can share the same priority number.
## Manual Order Release
If you chose to manually release B2B orders, you can do so from the Orders UI. Click **Manual Order Release** in the top right and select the site you want to release all Pending Shipment orders for, which will then prompt you to confirm. This requires the Manual Order Release and Order Read [user behaviors](/pages/user-roles "User Roles"). You can also do this with the [B2B Order Release API endpoint](/pages/b2b-order-release).
## Example Case
This example will release orders for the following four B2B accounts. It is the same for both manual and automatic order release.
* Veliora Construction and Sterma Auto Parts: Priority 1
* Harven Logistics: Priority 2
* Xumora Office Supplies: Priority 3
These accounts submitted orders in the following sequence, which are put in the Pending Shipment status.
1. Sterma Auto Parts Order 1
2. Xumora Office Supplies Order 1
3. Xumora Office Supplies Order 2
4. Sterma Auto Parts Order 2
5. Sterma Auto Parts Order 3
6. Harven Logistics Order 1
7. Harven Logistics Order 2
8. Veliora Construction Order 1
9. Sterma Auto Parts Order 4
10. Veliora Construction Order 2
11. Harven Logistics Order 3
The orders will be released as follows, from the highest account priority to lowest. When two accounts have the same priority, the system will alternate releasing their orders in a round robin.
1. Sterma Auto Parts Order 1
2. Veliora Construction Order 1
3. Sterma Auto Parts Order 2
4. Veliora Construction Order 2
5. Sterma Auto Parts Order 3
6. Sterma Auto Parts Order 4
7. Harven Logistics Order 1
8. Harven Logistics Order 2
9. Harven Logistics Order 3
10. Xumora Office Supplies Order 1
11. Xumora Office Supplies Order 2
# B2B Overview
Source: https://docs.kibocommerce.com/pages/b2b-overview
The B2B, or Business-to-Business, extension of Kibo eCommerce allows sales to be made to organizations separately from the single-consumer checkout experience. B2B allows you to manage the accounts of business buyers across your company, in which multiple buyers can log into a shared B2B account to access their pricing and purchasing options as well as negotiate order quotes with a designated sales representative.
Learn how to manage B2B buyer accounts, including creation, approval, and configuration
The B2B account functionality supports these multiple accounts with different roles and levels of authority, negotiated pricing, credit balances on accounts (Purchase Orders), and other features.
To begin creating a B2B implementation, contact a Kibo Customer Service Representative. For more information about the APIs associated with B2B Accounts, see the [API documentation](/api-overviews/openapi_customer_overview).
## How B2B Pricing Works
In eCommerce, specific pricelists are usually configured through customer segments. The segments found on the account are matched against the segments found on pricelists. If multiple pricelists match by segment, it resolves to the pricelist with the highest rank.
Similar functionality is supported for B2B accounts, however a pricelist may be specified directly on the B2B account, which takes precedence over any pricelist matched by customer segment. When a customer is logged into a B2B Account, pricing will reflect the appropriate pricelist pricing for their account. See the [Price List documentation](/pages/price-lists) for more information.
A buyer with the [Administrator](/pages/types-of-b2b-users) role may add credit cards and billing/shipping addresses to the account for use during checkout. Each user may choose their own primary billing/shipping address from those available on the account. The Purchase Order payment method may be available if the seller has enabled it on the account.
# Backorder Release
Source: https://docs.kibocommerce.com/pages/backorder-release
If some inventory is out of stock but you know that more will be delivered to fulfillment locations, backorder allows customers to continue ordering those items in the meantime. Shipments with backordered items will be placed on hold, then "released" for fulfillment when their items can be allocated with current inventory, future inventory, or both.
When an order is placed, the system will evaluate the [scenario after-actions](/pages/scenarios#after-action-logic "Scenarios") (or available inventory at the pickup location, if BOPIS) and suggest placing eligible items into a shipment with the Backorder status. These shipments will not be allocated immediately, but will wait to be released until inventory is available.
## Configure Backorder
Backorder is first enabled at the site level, and then on individual products.
### Enable for Site
To enable and configure your backordering behavior:
1. Go to **System** > **Settings** > **General** > **Site**.
2. Toggle on **Backorder job** to enable backordering.
3. Toggle on **Enable Partial Release** if you want to [release shipments for either partial line items or quantities](#partial-backorder-release). If not enabled, backordered shipments will only be released when all item quantities are available.
4. If you enabled partial release, click either **Release by Line Item** or **Release by Quantity** to determine which method you want to use.
* If releasing by line item, then a line item will move into a Ready shipment for fulfillment only if all of its quantity becomes available.
* If releasing by quantity, then partial quantity of an item will move into a Ready shipment as long as at least 1 quantity becomes available.
5. Toggle on **Enable payment void and reauth** to perform those payment actions when a backordered shipment is released. This is only available when your site is releasing backorder shipments in full.
6. Set a **Backorder job interval**. This is the frequency at which the backorder job runs to release shipments.
7. Enter the **Default backorder days**. Sets the number of days used to estimate when a backordered item will be available for customers. This is for informational purpose only and does not affect backorder processing and release. It is an optional field that can be used on the storefront to display an estimated backorder date. You can set Default Backorder days based on when you typically expect backordered inventory to become available.
### Enable for Products
The [product settings](/pages/configure-products "Configure Products") allow you to enable individual products for backordering. If backorder is not enabled here, then that product cannot be ordered while inventory is unavailable.
1. Go to **Main** > **Catalog** > **Products**
2. Click a product to edit its configurations or create a new product.
3. Select "Allow backordering" from the **If out of stock...** dropdown menu.
4. Click **Save**.
## Current vs. Future Inventory
The system can release inventory based on current inventory, future inventory, or a combination of both. This section describes how inventory is handled when backorders are being released in full.
### Current Inventory Only
The system follows the below steps when releasing backorders based on current inventory levels:
1. The system checks current inventory levels.
* For STH, Order Routing will look for assignment suggestions across locations.
* For BOPIS, inventory will only be checked for the pickup location.
2. If all items in the shipment can be assigned, the shipment is released. This generally means that the shipment moves into the Ready status. However, it may get split by quantity, line item, and/or locations depending on availability and Order Routing suggestions.
3. If not all items can be assigned, the shipment will remain in backorder.
For example, if a shipment has five KTP and five KTP2 items in backorder, then the following scenarios may happen after inventory refreshes:
* Order Routing suggests assignment of five KTP at Location A and five KTP2 at Location B. Since all items can be assigned, the shipment is released from backorder.
* Order Routing suggests assignment of five KTP at Location A but the KTP2 items are not available anywhere. Since not all items can be assigned, the shipment will remain in backorder.
### Future Inventory Only
When future inventory is enabled, the system can release backorders if the following rules are met:
1. Future inventory [must be enabled](/pages/future-inventory#enable-future-inventory "Future Inventory") in your site settings and product settings for that specific product.
2. The incoming inventory can be allocated within the Future Date Limit that you configured.
3. If all items in the shipment can be assigned, the shipment is released. This means that a new child shipment is created with the Future status, while the original parent shipment is moved from the Backordered status to Reassigned.
4. If not all items can be assigned, the shipment will remain in backorder.
For example, if a shipment has five KTP and five KTP2 items in backorder, then the following scenarios may happen after inventory refreshes:
* Two KTP will be available at Location A on the future date of 5/01 and another three KTP will be available at the same location on 5/10. Five KTP2 will be available on 5/15 at Location B. Since all items can be assigned for a future date, the shipment is released from backorder.
* Five KTP will be available at Location A on any future date(s) but the KTP2 items do not have an expected date. Since not all items can be assigned yet, the shipment will remain in backorder.
### Current and Future Inventory
Backorder release also supports a combination of current and future inventory, though current inventory is always prioritized. If the system finds that some items can be assigned with current inventory and the remainder can be assigned with future inventory, then the shipment will be released as long as it satisfies the above rules.
In this case, at least two child shipments are created with the Ready and Future statuses (containing the current and future inventory, respectively) while the original parent shipment is moved from the Backordered status to Reassigned.
For example, if a shipment has five KTP, five KTP2, and five KTP3 items in backorder, then the following scenarios may happen after inventory refreshes:
* Five KTP will be available at Location A on any future date(s) while five KTP3 will be available at Location B on any future date(s). Five KTP2 are now available at Location B. Since all items can be assigned with current and future inventory, the shipment is released from backorder.
* Five KTP will be available at Location A on any future date(s) while five KTP2 are now available at Location B. However, five KTP3 do not have an expected date. Since not all items can be assigned with current or future inventory, the shipment will remain in backorder.
## Partial Backorder Release
Partial backorder release can be used to fulfill some items or quantities from a backordered shipment even if others still aren't available. When enabled, the inventory that becomes available will move into a Ready shipment for immediate fulfillment while the remaining amount stays in backorder.
You can release partial backorders based on either full line items or quantities. If releasing by line item, then an item will move into a Ready shipment only if all of its quantity becomes available. If releasing by quantity, then any quantity of an item can move into a Ready shipment as long as at least one quantity becomes available. For example, if a shipment for five units of Product A is backordered and three units become available:
* If releasing by quantity, then three units will move into a new Ready shipment. The remaining two will stay in backorder.
* If releasing by line item, then no quantity will be released until all five units are available.
[Transfers](/pages/transfer-shipments "Transfer Shipments") can also be used when fulfilling partial backorders. For example, if a shipment for five units of Product A is backordered and two units become available at Location 1 while three units become available at Location 2:
* A shipment is created at Location 1 for two units.
* A transfer shipment from Location 2 is created to supply the remaining three units to Location 1 for fulfillment.
Partial backorder release is compatible with future inventory, in which a Future shipment will be created for the incoming inventory date instead of a Ready shipment for immediate fulfillment.
# Backorder Shipment Rules
Source: https://docs.kibocommerce.com/pages/backorder-shipment-rules
Backorder Shipment Rules determine the priority order in which backorder shipments are released when inventory becomes available during a rebalancing run. When the [Allocation Rebalancer](/pages/allocation-rebalancer) completes its future shipment rebalancing phase, the Backorder Shipment Rules run against the **full** backorder queue — not only the shipments newly affected by the triggering event — to re-rank all backorders against the revised inventory position. Shipments that match higher-priority rules are released first; shipments that cannot be fulfilled remain on backorder until the next run.
Backorder Shipment Rules follow the same composable rule structure used across Kibo for other rule types, using expression-based conditions across Account, Product, and Shipment dimensions. They are independently configurable from [Future Shipment Rules](/pages/future-shipment-rules) — a tenant may apply different prioritization logic to the backorder queue than to future shipments.
In addition to the UI detailed here, you can create and manage Backorder Shipment Rules using the Backorder Shipment Rules API endpoints. The [Product Rules](https://docs.kibocommerce.com/api-reference/productrules/create-product-rule) , [Customer Rules](https://docs.kibocommerce.com/api-reference/accountrankingrule/create-customer-rule) and [Shipment Rules](https://docs.kibocommerce.com/api-reference/shipmentrules/get-shipment-rule-by-code) APIs can also be used to manage supporting product, customer and Shipment rules.
## **Prerequisites**
Before configuring Backorder Shipment Rules, ensure the following:
* The **B2B Wholesale OMS** feature is enabled for your tenant. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this capability.
* You have **Admin** or **SuperAdmin** role permissions, or a role with the following behaviors assigned:
* Product Rule: Read, Create, Update, Delete
* Customer Rule: Read, Create, Update, Delete
* Backorder Shipment Rule: Read, Create, Update, Delete
* The **Allocation Rebalancer** is configured and enabled at the site level. See [Allocation Rebalancer](/pages/allocation-rebalancer).
## **How Backorder Shipment Rules Work**
### **When They Run**
Backorder Shipment Rules run as part of the Allocation Rebalancer's sequential flow — specifically as the backorder prioritization step (Step 5). They run every time the rebalancer is triggered, regardless of whether the triggering event was a supply decrease (which also processes future shipments) or a demand decrease (which goes directly to backorder processing).
The rules run against the **entire** backorder queue, not just the shipments affected by the triggering event. This ensures all backorders are sequenced correctly against the revised available inventory after every run.
### **Rule Evaluation**
All enabled Backorder Shipment Rules run together in ascending rank order. Each backorder shipment is evaluated against each rule in sequence. When a shipment matches a rule's criteria, that rule assigns a priority rank to the shipment. A shipment is only evaluated once — once it matches a rule, it is not re-evaluated against subsequent rules.
Shipments that do not match any enabled rule will be considered by Catch All Rule, which is treated as the lowest possible priority during reallocation.
Its up to the Admin to create a Catch All Rule Criteria such that all the shipments get eligible in that rule
### **Release Processing**
After prioritization, the rebalancer releases backorder shipments in priority order — highest-priority shipments are released first. Inventory sourcing during backorder release is governed by the [Backorder Inventory Settings](/pages/general-settings#allocation-rebalancer) configured at the site level (whether to use current inventory, future inventory, or both, and in what order).
### **Sort**
Each Backorder Shipment Rule includes a primary and optional secondary sort criterion. For shipments that match the same rule, the sort determines their relative release order within that priority tier. You can sort on any numeric or date field available on the shipment, such as `requestedShipDate` or `lastCancellationDate`.
## **Rule Criteria**
A Backorder Shipment Rule supports up to three criteria types:
| **Criteria Type** | **What It Filters** |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account / Customer Criteria** | Account attributes such as account ID, segment. |
| **Product Criteria** | Product-level attributes such as Product Code, Variant Product Code, UPC, Mfg Part Number ,Product Type, Category Code, Category List Price, Fulfilment Types Supported, Height, Length, Weight, Width, attributes properties |
| **Shipment Criteria** | Shipment-level attributes such as fulfillment type, carrier, shipping method, estimated delivery date, last cancellation date, SLA status, or extensible attributes at the shipment header or line level |
**Note:** Product Rules, Customer Rules and Shipment Rules created for Backorder Shipment Rules are exclusive to Backorder Shipment Rules and cannot be shared with other rule types.
## **Rule Attributes**
| **Attribute** | **Type** | **Required** | **Description** |
| :-------------------- | :---------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Code** | String | Yes | Unique identifier for the rule, scoped to the tenant. Auto-generated if left blank. |
| **Name** | String | Yes | Display name shown in the Admin UI. |
| **Description** | String | No | Optional free-text description of the rule's intent. |
| **Rank** | Integer | Yes | Priority order. Lower value = higher priority. Rank 1 runs before Rank 2. Values must be unique. |
| **Enabled** | Boolean | Yes | When disabled, the rule is skipped during rebalancing but remains saved for future use. |
| **Time Fence Days** | Integer | Yes | Symmetric window (±N days) around `requestedShipDate` for inventory search during backorder release. |
| **Primary Sort** | Field + Direction | Yes | The field and direction (ascending/descending) used to order matched shipments within a priority tier. Supports any numeric or date field on the shipment. |
| **Account Criteria** | List | No | References to Customer Rule criteria defining which accounts qualify. |
| **Product Criteria** | List | No | References to Product Rule codes defining which products this rule covers. |
| **Shipment Criteria** | List | No | References to Shipment Rule codes defining shipment-level filters. |
## **Configure Backorder Shipment Rules**
To create a new Backorder Shipment Rule:
1. Go to **Main** > **Fulfillment** > **Rules** > **Backorder Shipment Rules**.
2. Click **Create Backorder Shipment Rule**.
3. Enter a **Code**. If left blank, the system generates one automatically.
4. Enter a **Name** and an optional **Description**.
5. Enter a **Rank** value. The lower the number, the higher the priority.
6. Enter a **Time Fence Days** value. The rebalancer searches for inventory within this symmetric window around the shipment's requested ship date when releasing the backorder.
7. Toggle the rule **Enabled** to activate it.
8. Configure **Sort Criteria**:
* Under **Primary Sort**, select a numeric or date field and choose **Ascending** or **Descending**.
9. Optionally, add **Account / Customer Criteria**:
* Click **Add Customer Rule** and use the expression editor to define account-level conditions.
10. Optionally, add **Product Criteria**:
* Click **Add Product Rule** and use the expression editor to define product-level conditions.
11. Optionally, add **Shipment Criteria**:
* Click **Add Shipment Rule** and use the expression editor to define shipment-level conditions.
12. Click **Save**.
**Note:** At least one Rule Criteria is needed for the rule to be saved.
## **Manage Backorder Shipment Rules**
Access the Backorder Shipment Rules dashboard at **Main** > **Fulfillment** > **Rules** > **Backorder Shipment Rules** to manage your configured rules:
* Toggle the **Status** icon on a rule to activate or deactivate it without deleting it.
* Expand the actions menu on a rule to **Edit** or **Delete** it.
* Check multiple rules and use the **Actions** menu to enable, disable, or delete in bulk.
* Edit the **Rank** of a rule directly in the table, or click and drag to reorder.
## **Example Rule Configurations**
### **Release Strategic Account Backorders First**
| **Rule** | **Rank** | **Account Criteria** | **Sort** | **Expected Behavior** |
| :------- | :------- | :----------------------------------- | :---------------------------- | :------------------------------------------------------------------ |
| Rule 1 | 1 | `account.segment equals "strategic"` | `requestedShipDate` Ascending | Strategic accounts with the earliest ship dates are released first. |
| Rule 2 | 2 | `account.segment equals "preferred"` | `requestedShipDate` Ascending | Preferred accounts next. |
### **Combined Account and Product Priority**
| **Rule** | **Rank** | **Account Criteria** | **Product Criteria** | **Sort** | **Expected Behavior** |
| :------- | :------- | :----------------------------------- | :---------------------------------- | :---------------------------- | :---------------------------------------------------------------- |
| Rule 1 | 1 | `account.segment equals "strategic"` | `product.category equals "Premium"` | `requestedShipDate` Ascending | Strategic account backorders for premium products released first. |
| Rule 2 | 2 | `account.segment equals "strategic"` | *(none)* | `requestedShipDate` Ascending | All other strategic account backorders next. |
# Batch Import via APIs
Source: https://docs.kibocommerce.com/pages/batch-import-via-apis
Some APIs support "batch import" which is a slightly different method for submitting and processing update requests. This allows you to send a large batch of updates before marking them as ready for processing, at which point Kibo will begin to perform all updates at either the system's own pace or a specific scheduled date.
See the Import/Export API documentation for programmatic access
Batch importing provides better fault tolerance, as Kibo is able to retry the action several times. Processing batch updates at Kibo's own pace also reduces load on the system, helping to avoid service disruption.
## Batch Job Statuses
The below statuses indicate whether or not a job has been processed.
* **Ready**: Job is not yet processed but can begin immediately regardless of the date.
* **Pending**: Job is waiting for a scheduled date to be reached before it can be processed.
* **Completed**: Job has been fully processed.
* **Canceled**: Job has been canceled.
Individual items within a job also have their own Processing Status.
* **Waiting**: Item data is being updated.
* **Running**: An action has been performed for the item.
* **ValidationFailed**: Item could not be found.
* **Failed**: An error was experienced, such as missing data.
* **Completed**: Item data has been successfully added or updated.
* **Canceled**: Item's job has been canceled.
## Available APIs
Batch imports can only be performed on specific APIs, and their jobs can be managed with dedicated Batch Job API endpoints to start, cancel, or reset imports as needed.
### APIs with Batch Import Support
Only the Product, ProductProperties, and PriceLists endpoints of the [Catalog Admin APIs](/api-overviews/openapi_catalog_admin_overview) support batch importing with their POST, PUT, and DELETE calls. Support for more APIs may be added later if there is client demand for it.
### Manage Batch Import Jobs
The following Batch Job endpoints manage your batch import jobs.
* The [Create Batch Job](/api-reference/batchjob/create-batch-job) call initiates an unstarted batch job that your updates will be added to.
* The [Perform Batch Action call](/api-reference/batchjob/perform-batch-action) starts, cancels, and resets jobs. Reset can only be called for jobs that are already completed or canceled, and will remove all items so that you can re-use the empty job.
* The [Get Batch Job Items call](/api-reference/batchjob/get-batch-job-items) queries for items of a specific processing status and/or resource by appending `?processingStatus={processingStatus}&resourceType={resourceType}` to the endpoint.
* Resource Type Options: Products, ProductProperty, Pricelistentries
* The [Update Batch Job call](/api-reference/batchjob/update-batch-job) currently only allows you to change the name of the batch job.
## Batch Import Process
First make a [Create Batch Job](/api-reference/batchjob/create-batch-job) call. Only the code, name, and domain (which is "Catalog" for both prices and price lists) are required, as the status will default to Ready if not provided. Providing an optional `scheduledDate` field will determine when Kibo begins processing the import.
```
{
"code": "batch_job_1",
"jobName": "Example Job",
"scheduledDate": null,
"domain": "Catalog",
"status": "Ready"
}
```
Then make your update calls to the Product or Price Lists API and specify the `batchJobCode` as a parameter in the endpoint, as shown below (using the [Add Products API](/api-reference/products/add-product) as an example). This will add the updates to the job but not yet implement them.
```
.../commerce/catalog/admin/products/?batchJobCode={batch_job_1}
```
Once all of your updates are added to the job, call the [Perform Batch Action API](/api-reference/batchjob/perform-batch-action) to indicate that it's ready to be processed with the start action. This is necessary even for jobs with a scheduled date, which will go into Pending status until that date is reached (at which point Kibo will automatically begin the update process). If a scheduled date was not provided, the job will be processed immediately.
```
.../platform/data/batchJob/actions/{batch_job_1}
```
```
{
"action": "start"
}
```
# Blanket Orders
Source: https://docs.kibocommerce.com/pages/blanket-order
A **Blanket Order** is a contractual purchasing commitment that captures a buyer's long-term agreement to purchase a set quantity of products over a defined period—such as a season, quarter, or year. Configured per site, a Blanket Order serves as the single source of truth for contract commitments and balance consumption
Unlike traditional sales orders, Blanket Orders do not trigger fulfillment, perform inventory allocations, or create immediate shipping obligations. Instead, they deliver capabilities across four core dimensions:
* **Demand Visibility:** Total committed product quantities across B2B accounts provide operations teams with clear demand signals for procurement planning and supply management before fulfillment begins.
* **Inventory Protection**: Blanket Orders act as pure demand signals without placing inventory holds. Soft inventory allocation and protection are managed downstream by individual Call-Off Orders.
* **Contract Accuracy:** Call-off requests are validated against the remaining balance of the Blanket Order, preventing unauthorized over-consumption while automatically tracking balances and contract expirations.
* **Full Audit Traceability:** Maintains bidirectional references between the commitment agreement and downstream call-off orders for complete operational auditing.
**Tenant Activation:** Blanket Orders are created and visible within a specific site context. To enable Blanket Order functionality, contact KIBO Support for tenant-level activation. .
## **Blanket Order Dashboard**
Navigate to **Main > Demand > Blanket Orders**. The Blanket Orders List view site provides access to blanket orders for the selected site.
* **Site Scope Selection:** Select the target site from the site context dropdown to view blanket orders for that site.
* **Centralized Search:** Search for blanket orders using the Blanket Order Number, External Order ID, or Account ID.
* **Life Cycle Filtering**: Filter blanket orders by status.
## **Blanket Order Information**
Blanket contract level details capture foundational terms, contacts, and validity dates for the agreement:
* **Blanket Order Number:** Unique system-generated identifier for the contract.
* **B2B Account:** B2B Account associated with the agreement.
* **Buyer Contact Name & Email:** Contact information for the buyer representative (name, email, phone).
* **Seller Contact Name & Email:** Contact information for the assigned sales representative (name, email, phone).
* **Status:** System-managed lifecycle state of the contract.
* **External ID:** Optional external reference identifier supplied by the buyer or external system.
* **Start Date:** Contract validity start date.
* **End Date:** Contract validity end date.
* **Price List:** Optional price list governing negotiated product pricing.
* **Channel Code:** Origin channel of the order (e.g., Kibo Admin).
* **Notes:** Internal comments or contract notes.
* **Attributes:** Custom attributes configured for the Blanket Order entity.
* Note - Field editability is governed by the blanket order status. As the Blanket Order moves through its lifecycle, certain fields become locked to preserve agreement terms.
### **Item Level Details on Blanket Order**
Item level details track the specific products, negotiated pricing, and quantity balances under the contract:
* **Line ID:** Auto-assigned sequential line number within the Blanket Order.
* **Product:** Item included in the agreement.
* **Committed Qty:** Total quantity agreed upon for purchase across the contract duration.
* **Consumed Qty:** Total quantity drawn across validated call-off orders.
* **Remaining Qty:** Computed balance available for future call-off orders (Committed Qty minus Consumed Qty).
* **Unit Price:** Negotiated unit price.
* **Line Status:** Operational state of the line item (Open, Partially Consumed, Fully Consumed, or Cancelled) .
* **Line Attributes:** Custom attributes configured for the Blanket Order line items.
* Note - Field editability is governed by the line item status.
## **Blanket Order Lifecycle & Statuses**
### **Contract Statuses**
The contract status reflects the operational state of the overall Blanket Order based on validity dates and product balance consumption:
* **Open:** The contract is activated and accepting call-off orders.
* **Partially Consumed:** At least one product line has been drawn down by a call-off order, while remaining balance exists on one or more lines.
* **Fully Consumed:** All item lines have reached zero remaining balance. If a call-off order is cancelled and restores balance to any line, the overall contract automatically re-opens for call-offs
* **Expired:** The contract validity end date has passed. The system automatically transitions Open contracts to Expired when the end date passes. No further call-off orders are accepted, though remaining balances on open line items may be rolled over to a new Blanket Order for the next agreement period.
* **Cancelled:** The Blanket Order is cancelled.
### **Line Item Statuses**
Each product line within a Blanket Order maintains an independent status that tracks its consumption state under the agreement:
* **Open:** The full committed quantity is available for consumption by call-off orders. No consumption has occurred.
* **Partially Consumed:** A portion of the committed quantity has been drawn down by call-off orders, while open balance remains on the line.
* **Fully Consumed:** The entire committed quantity for this line has been drawn. No further call-offs are allowed against this line unless line quantities are increased or a downstream call-off order is cancelled to restore balance.
* **Cancelled:** The item line has been cancelled from the agreement.
## **Creating a Blanket Order in Admin UI**
* **Navigate to Blanket Orders:** Go to **Demand** > **Blanket Orders** in the main navigation menu.
* **Initiate Creation:** Click **Create Blanket Order** on the top right of the page. The Blanket Order will automatically be scoped to your currently active site context.
* **Provide Blanket Order Details:** Enter the required header details. Ensure the B2B Account is active, the Start Date set to and the End Date is after the Start Date.
* **Add Line Items:** Click **Add Line**, select a product, and specify the Committed Qty (must be greater than zero). At least one line item is required to submit.
* **Submit:** Click **Submit**.
### **Cancellation**
Contract and line item cancellations manage commitment termination while preserving downstream processing:
* **Mandatory Cancellation Reasons:** An explicit cancellation reason code must be specified when cancelling a Blanket Order or an individual product line. Cancellation reason options can be customized by administrators.
* **Existing Call-Off Orders Unaffected:** Cancelling a Blanket Order or an individual product line does not affect or cancel any Call-Off Orders previously created from it. Existing Call-Off Orders continue through the fulfillment pipeline independently.
### **Roll Over to a New Blanket Order**
If a Blanket Order's expiry date has reached or passed, any line items in an "Open" status with remaining balances are eligible to be transferred to a new Blanket Order for the next agreement period. To roll over a blanket order - .
1. Open the expired Blanket Order.
2. Select the eligible line items to roll over.
3. Set a new Start Date and End Date for the new agreement.
4. Provide attribute values.
Key contract terms—including B2B Account, contacts, price list, etc.—are automatically copied along with the selected line items to create the new Blanket Order.
### **Extensible Attributes**
* **Blanket Order Attributes:** Blanket order attributes capture custom order level data, such as internal contract classifications, or legacy agreement references. For full configuration details on entity selection and attribute value sync settings, see [Extensible Attributes](https://docs.kibocommerce.com/pages/schema-extensible-attribute).
* **Blanket Order Item Attributes:** Blanket order item attributes capture custom line item level data, such as customer-specific part numbers, or line-level negotiated terms. For full configuration details on entity selection and attribute value sync settings, see [Extensible Item Attributes](https://docs.kibocommerce.com/pages/schema-extensible-item-attribute).
### **Audit Log**
Every modification made to a Blanket Order or its line items is automatically recorded in the contract audit log, capturing the user identity, timestamp, modified field, original value, and updated value.
# Blanket Order — Network-Level Reservation
Source: https://docs.kibocommerce.com/pages/blanket-order-network-level-reservation
When a seller signs a Blanket Order with a key B2B buyer, they may need to do more than record a commercial commitment — they may need to **protect the committed inventory** from the moment of signing, before the buyer places a single Call-Off Order. Blanket Order Network-Level Reservation is the mechanism that provides this guarantee.
A Blanket Order created in **network-level mode** immediately removes the committed quantity from general network availability, ring-fencing it for the entitled buyer. As the buyer places Call-Off Orders and inventory is progressively reserved, the ring-fence draws down in lockstep — ensuring that every committed unit is counted exactly once and never double-sold.
A Blanket Order in **call-off-level mode** (the default) records the same commercial commitment but protects no inventory in advance. Each Call-Off Order competes for stock when placed, just like any other order. The buyer carries the risk that inventory may not be available.
The mode is selected at Blanket Order creation and **cannot be changed after the order is created**.
**Note:** Network-Level Reservation is available only for tenants with the **B2B Wholesale OMS** feature enabled. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this capability.
***
## **Prerequisites**
Before using Blanket Order Network-Level Reservation, ensure the following:
* The **B2B Wholesale OMS** feature is enabled for your tenant.
* New Supply Demand UI (Inventory UI) is enabled for your tenant. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this capability
* At least one **Blanket Order** has been created in **network-level mode**. See [Create a Blanket Order](/pages/blanket-order) for steps.
* The **Ring-Fence Scope** site-level setting is configured before network-level Blanket Orders are placed. See [Ring-Fence Scope](#ring-fence-scope) below.
* You have **Admin** or **SuperAdmin** role permissions.
***
## **Key Concepts**
### **Modes**
Every Blanket Order is created in one of two immutable modes:
| **Mode** | **Inventory Protected at Signing?** | **How Call-Offs Are Filled** |
| :----------------------------- | :----------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Network-level** | Yes — the committed quantity is immediately ring-fenced through availability netting | Each Call-Off Order draws the ring-fenced balance down. Inventory is soft-reserved when the Call-Off is placed. |
| **Call-off-level** *(default)* | No — nothing is ring-fenced | Each Call-Off Order competes to reserve available inventory when placed. |
**Note:** The only difference between the two modes is the ring-fence. In both modes, a Call-Off Order reserves real inventory when it is placed.
***
### **The Called / Uncalled Ledger**
For every network-level Blanket Order, Kibo maintains a live **Called / Uncalled ledger** that tracks the reservation position of the commitment at all times.
| **Field** | **Definition** |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Contracted** | The total quantity committed on the Blanket Order |
| **Called** | The portion of the contracted quantity that has been successfully reserved (soft-allocated) against one or more Call-Off Orders |
| **Uncalled** | The remaining contracted quantity not yet reserved — `Contracted − Called` |
**The invariant that always holds:**
> **Contracted = Called + Uncalled**
Any operation that would break this invariant is rejected. Every committed unit is counted exactly once: it is either in **Called** (reserved, in Allocated) or in **Uncalled** (ring-fenced, subtracted from network availability). It is never in both and never in neither.
**Example — ledger in motion:**
| **Event** | **Called** | **Uncalled** |
| :------------------------------------------------------ | :--------- | :----------- |
| Blanket Order signed — contracted 1,000 | 0 | 1,000 |
| Call-Off Order for 200 units, fully reserved | 200 | 800 |
| Call-Off Order for 300 units, fully reserved | 500 | 500 |
| Call-Off Order for 100 units, no stock — cannot reserve | 500 | 500 |
| Retry reserves the outstanding 100 | 600 | 400 |
When the third Call-Off Order finds no stock, Called and Uncalled do not change — the 100 units remain in Uncalled, and the platform retries reservation automatically as new inventory arrives (see [Partial Reservation and Retry](#partial-reservation-and-retry)).
***
### **Availability Model**
Network-level ring-fencing works by subtracting the **Uncalled balance** from the network aggregate availability calculation. Call-off-level Blanket Orders have zero uncalled balance and therefore subtract nothing.
```text theme={null}
Network ATS = (On Hand − Allocated) − sum of Uncalled across all network-level Blanket Orders on the item
Network ATP = (On Hand − Allocated + Future) − sum of Uncalled across all network-level Blanket Orders on the item
```
**Location-level availability is unchanged.** Netting applies only to the network aggregate — never to an individual location:
```text theme={null}
Location ATS = On Hand − Allocated
Location ATP = On Hand − Allocated + Future
```
**No double-counting.** When a Call-Off Order reservation succeeds, the reserved quantity moves from Uncalled into Called and into Allocated simultaneously. At that moment, `(On Hand − Allocated)` drops by the reserved quantity while the Uncalled subtraction shrinks by the same amount — total network availability does not change at the instant of reservation.
**Note:** The network ring-fence is a **soft aggregate reserve**. It protects the availability number returned by network-level queries, but it does not hard-lock specific physical units at specific locations. Location-level orders — such as B2C sales orders, BOPIS, or store fulfillment — allocate against location availability, which is intentionally blind to the blanket's uncalled balance. This can drive network availability negative (see [Network Availability Going Negative](#network-availability-going-negative)).
***
## **Ring-Fence Scope**
By default, a network-level Blanket Order's uncalled balance nets against **all locations** in the network. Administrators can optionally restrict the ring-fence to a specific **Location Group** — meaning netting and reservation apply only to locations within that group, not the full network.
This is a **site-level setting** that applies uniformly to every network-level Blanket Order on the site. It is not configured per Blanket Order.
| **Scope** | **Behavior** |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **All Locations** *(default)* | The uncalled balance nets against the full all-locations aggregate. Call-Off Orders reserve from any location. |
| **Location Group** | The uncalled balance nets against the configured group's aggregate only. Call-Off Orders reserve from locations within that group only. |
### **Configure Ring-Fence Scope**
1. Go to **Main** > **System** > **Settings** > **General**.
2. Select the **Site** tab.
3. Scroll to the **B2B** section.
4. Under **Blanket Order Settings**, set **Ring-Fence Scope** to **All Locations** or **Location Group**.
5. If **Location Group** is selected, choose a valid, existing location group from the **Location Group** field. Exactly one group may be configured per site.
6. Click **Save**.
**Important:** Configure the ring-fence scope **before** creating network-level Blanket Orders. Changing the scope after network-level Blanket Orders have been placed re-scopes the aggregate that all existing Blankets net and reserve against, which can produce unexpected availability behavior.
***
## Selecting the Reservation Mode
When creating a Blanket Order in the Kibo Admin UI, the reservation mode is selected via a single checkbox:
* Go to Main > Demand > Blanket Orders.
* Click Create Blanket Order.
* Enter the required header details (B2B Account, Start Date, End Date, etc.).
* Locate the Reserve inventory in advance (Guaranteed Supply) checkbox.
* Check or uncheck the box:
1. Checked — The Blanket Order is created in network-level mode. The committed quantity is ring-fenced from network availability at signing.
2. Unchecked (default) — The Blanket Order is created in call-off-level mode. No inventory is reserved in advance.
* Add line items and specify committed quantities.
* Click **Submit**.
**Note**: The reservation mode cannot be changed after the Blanket Order is submitted.
## **How Network-Level Reservation Works**
### **At Blanket Order Creation**
When a network-level Blanket Order is created:
* The ledger initializes: **Called = 0**, **Uncalled = Contracted quantity**
* The uncalled balance is immediately subtracted from the network availability calculation (or Location Group availability, if configured)
* The entitled buyer's committed quantity is ring-fenced from the moment of signing — before any Call-Off Order is placed
No inventory is physically reserved or allocated at this point. The ring-fence is purely a subtraction in the availability formula.
### **When a Call-Off Order Is Placed**
When the entitled buyer places a Call-Off Order against a network-level Blanket Order, the reservation flow runs as follows:
1. **Validate commitment** — the requested quantity must be within the Blanket Order's remaining commitment. Any quantity in excess of the contracted balance is rejected.
2. **Reserve** — the platform attempts to soft-reserve inventory for the requested quantity using Order Routing, scoped to the configured ring-fence scope (All Locations or Location Group).
3. **Update the ledger** — for the quantity that reserves successfully: **Called increases** and **Uncalled decreases** by the same amount. The reserved units move into Allocated. This ledger update and the reservation are a single atomic operation — availability is never overstated between them.
4. **Retain the remainder** — any portion of the request that could not be reserved stays outstanding on the Call-Off Order and remains within Uncalled. The platform retries reservation automatically (see [Partial Reservation and Retry](#partial-reservation-and-retry)).
**Note:** At the moment a reservation succeeds, total network availability does not change. The reserved units move from Uncalled (subtracting from availability) into Called and into Allocated (also subtracting from availability). The subtraction simply shifts from one mechanism to the other.
### **Partial Reservation and Retry**
A Call-Off Order reserves as much of its requested quantity as inventory allows — it does not require full availability to proceed. Whatever reserves successfully moves from Uncalled into Called; the unreserved remainder stays outstanding on the Call-Off Order and remains within Uncalled.
The platform automatically retries reservation for outstanding quantities at timed intervals via a background job. As new inventory arrives, the job reserves what it can — each success moving additional quantity from Uncalled into Called. The original requested quantity on the Call-Off Order is preserved throughout and is never reduced by partial reservation.
**Example:**
| **State** | **Called** | **Uncalled** | **Call-Off: Requested** | **Call-Off: Reserved** | **Call-Off: Outstanding** |
| :---------------------------------- | :--------- | :----------- | :---------------------- | :--------------------- | :------------------------ |
| Blanket signed — 1,000 | 0 | 1,000 | — | — | — |
| Call-Off for 100, only 20 available | 20 | 980 | 100 | 20 | 80 |
| Retry reserves 30 more | 50 | 950 | 100 | 50 | 50 |
| Retry reserves remaining 50 | 100 | 900 | 100 | 100 | 0 |
The invariant holds at every step: 1,000 = Called + Uncalled.
**Note:** The automated retry job, Reservation Rules, and Call-Off Order reservation are documented in detail in [Reservations](/pages/reservations) and [Reservation Rules](/pages/call-off-reservation-rules). The retry and partial reservation behavior described here is specific to how network-level Blanket Orders interact with those mechanisms.
***
## **Entitlement**
The uncalled balance of a network-level Blanket Order belongs exclusively to its **entitled customer**. Only that customer can draw down the balance through Call-Off Orders against that specific Blanket Order.
While the ring-fence reduces network availability for everyone, the ring-fenced quantity is not available for purchase by any other customer — even though it is not physically reserved at a specific location. This protection is enforced on every reservation drawn against the Blanket Order.
***
## **Contract Increase**
The contracted quantity of a Blanket Order can be increased at any time. For a network-level Blanket Order, increasing the contracted quantity raises the uncalled balance by the same amount, which further reduces network availability immediately.
**Note:** Reducing the contracted quantity is handled through cancellation or reduction of Called quantity (see [Cancellation and Reduction](#cancellation-and-reduction)). There is no direct "reduce contract quantity" operation.
***
## **Cancellation and Reduction**
When a Called quantity is cancelled or reduced:
* The Blanket Order's **Uncalled balance is restored** by the cancelled or reduced quantity
* The matching inventory reservation is released and returned to general availability
* The invariant is maintained: Contracted = Called + Uncalled
***
## **Supply-Shortfall Prioritization**
A drop in physical supply does not reduce a Blanket Order's uncalled balance. The committed quantity remains a contractual claim regardless of current on-hand position.
When supply cannot cover all commitments:
* Committed blanket quantities — including outstanding Call-Off Order quantities awaiting retry — are served **ahead of general demand** as new inventory arrives
* This ensures contracted buyers are protected under scarcity
***
## **Network Availability Going Negative**
It is possible — and expected — for network availability to go negative. This occurs when total commitments (uncalled balances) across multiple network-level Blanket Orders exceed the available on-hand stock, or when location-level orders consume physical stock that was backing the ring-fence.
**Why location-level orders can erode the ring-fence:**
The network ring-fence subtracts from the *aggregate* availability figure, but location-level orders allocate against *individual location* availability — which is intentionally blind to the blanket's uncalled balance. A B2C sales order, BOPIS pick, or store fulfillment order can therefore consume physical stock at a location even when network availability reads zero or negative.
***
## **Multiple Network-Level Blanket Orders on the Same Item**
When several network-level Blanket Orders exist for the same item, their uncalled balances are **summed** in the availability formula:
```text theme={null}
Network ATS = (On Hand − Allocated) − (Uncalled_B1 + Uncalled_B2 + ... + Uncalled_Bn)
```
Network availability may go negative when total commitments exceed On Hand — this is a permitted over-commitment state, resolved as supply arrives.
**Blanket Orders do not have priority among themselves.** Network ring-fencing is made in order of the Blanket Order received. Any prioritization between accounts is handled during actual reservation at the Call-Off Order level through [Reservation Rules](/pages/call-off-reservation-rules).
## **Viewing Blanket Network Reservations**
The **Blanket Network Reservations** view in the Supply Demand UI provides a consolidated, per-product picture of ring-fenced inventory and network availability. Use this view to see how much stock exists, how much is ring-fenced by blanket orders, how much is otherwise allocated, and how much is genuinely free to promise.
### **Accessing the View**
1. Go to **Main** > **Supply** > **Inventory** > **Supply Demand**.
2. Click the **Blanket Network Reservations** link.
3. The page opens with the title **Blanket Network Reservations** and a filter section at the top.
### **Filters**
The filter section at the top of the page contains the following controls:
| **Filter** | **Type** | **Behavior** |
| :------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Site** | Dropdown | Select a site to scope the data. Required — no data loads until a site is selected. |
| **Ring-Fence Scope** | Dropdown (read-only) | Appears only after a site is selected. Displays the ring-fence scope configured for the selected site: **All Location** or the name of the configured **Location Group**. This field is read-only — the scope is determined by the site-level setting (see [Ring-Fence Scope](#ring-fence-scope)). |
| **Master Catalog** | Dropdown | Allows users to choose master catalog , only visible when Catalog is enabled for the tenant |
| **Child Catalog** | Dropdown | Allows users to choose Child catalog , only visible when Catalog is enabled for the tenant |
| **Product Name** | Dropdown | typeahead (3+ characters), Variants product Support, multi-select; catalog-enabled only |
| **UPC** | Input field | Product Code/Variant Code — single or multi-value chip input comma separated |
After applying filters, a **Selected Filters** summary section appears below the filter area, showing active filter chips.
### **Network Reservation Grid (Primary Grid)**
The primary grid displays one row per product (UPC) within the selected filters and scope. Each row shows the network-level inventory summary for that product.
| **Column** | **Description** |
| :-------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **UPC** | Product Code/Variant Code |
| **Network on hand** | Total stock for this product across all locations in the ring-fence scope (all locations, or locations within the configured Location Group). |
| **Blanket Network Reservations (Ring Fenced)** | Total quantity ring-fenced under all active network-level Blanket Orders for this product. This is the summed uncalled balance across all blankets. |
| **Allocations (Direct Call Off Reservations + Shipment Allocations)** | Stock committed but not yet shipped. This includes **both** inventory allocated to active shipments **and** inventory reserved against Call-Off Orders — shown as a single combined figure. |
| **Network Available** | What is genuinely free to promise to new orders: Network on hand minus Blanket Network Reservations minus Allocations. This value **may be negative** — a negative number indicates over-commitment and is a valid replenishment signal, not an error. |
Each row includes an **view** action on the right side. Click the view icon to open the blanket detail sidebar for that UPC (see below).
### **Blanket Detail Sidebar (Secondary Grid)**
Clicking the **eye icon** on a primary grid row opens a right-side sidebar showing the individual Blanket Orders that contribute to that UPC's ring-fenced quantity. The sidebar uses the same interaction pattern as the Inventory record view.
**Sidebar header** displays:
* The selected **UPC**
* The **site** selection details
**Sidebar body** contains a secondary grid and a B2B account filter.
#### **B2B Account Filter**
Above the secondary grid, a **B2B Account** filter allows you to filter the blanket order rows by customer account. Select an account from the dropdown to show only blanket orders belonging to that customer.
#### **Blanket Detail Grid**
| **Column** | **Description** |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **Blanket** | The Blanket Order number, displayed as a clickable link. Clicking the link opens the Blanket Order Details page in a new browser tab. |
| **Blanket Order Qty** | The total committed quantity on this Blanket Order for this product. |
| **Called** | The quantity already drawn down (reserved) against this Blanket Order for this product. |
| **Uncalled** | The remaining quantity available to be ordered (`Blanket Order Qty − Called`). |
# Boost and Bury Fields
Source: https://docs.kibocommerce.com/pages/boost-and-bury
You may Boost or Bury any field entry that was created in the Schema Editor. This allows the ranking of certain products relative to others within the search results to be manually changed. The allowable boost/bury value is –100 to 100. Any value of 0 or higher is a boost, while a negative number is a bury.
Learn how to create and manage merchandizing rules for search and categories
## Add Boost/Bury Expression
To add a new entry:
1. Click **Add Expression** on the Boost/Bury page.\\
2. Choose the Boost Type (Core Field or Custom Attribute) from the drop-down menu and then click **Next**.\\
3. Select the Field Name, Operator, Field Value, and Boost Value. Click **Done**.\\
4. To add a more complex boost, click **Custom Boost Function**.\\
5. Enter the full expression into the text field and click **Done**.
## Boost/Bury Merchandizing Fields
In addition to the other core fields, some fields support special boosting for use alongside [merchandizing rules](/pages/merchandizing-rules "Merchandizing Rules"). These fields are available in the schema out-of-the-box.
* **Margin**: Based on the product's cost subtracted from the sale price. If a sale price is not available, then the price is used instead. This requires a sale price or price to be set in the catalog as well as the cost.
* **Sales Rank**: Based on sales rankings from a certain amount of days, as a percentile of quantity sold for a product in relation to overall product sales. You can choose whether this is calculated over a short, medium, or long term time frame. For example, you could boost the bestselling items of the past 30 days and bury those that have not sold as well.
* This consists of three product property attributes that can be configured to specific days: `syscalc~sales-rank-short-term`, `syscalc~sales-rank-medium-term`, and `syscalc~sales-rank-long-term`. By default, these attributes are set to 30, 60, and 90 days respectively but you can change them by [editing the attribute in your catalog](/pages/property-attributes "Property Attributes"). They cannot be edited on individual products.
* **First Available Date**: Based on product availability from either a specific date or a number of days from the current time. This supports operators of equals, greater than or equals, greater than, less than, and less than or equals. For example, you could boost a product that has been in the catalog for less than 7 days, bury a product that has been in the catalog for greater than 30 days, or boost products that became available on March 10.\\
# Builder Integration
Source: https://docs.kibocommerce.com/pages/builders-kibo-plugin
Builder's Kibo plugin helps you to connect your Kibo product catalog to Builder for seamless integration. This delivers exceptional customer experiences by harnessing the power of feature-rich, composable digital commerce and lets you meet customer expectations by creating experiences where order management data matters.
## Prerequisites
You must have the following accounts:
* [Kibo Commerce account](https://kibocommerce.com/)
* [An app integrated with Builder](https://www.builder.io/c/docs/integrating-builder-pages)
For information on how you can integrate Kibo with Builder and create a Kibo storefront using Builder, read this [document](https://www.builder.io/c/docs/plugins-kibo).
# Bulk Inventory Deletion
Source: https://docs.kibocommerce.com/pages/bulk-inventory-deletion
How to safely delete inventory records in bulk using the Kibo Inventory APIs, including dry runs, async job monitoring, batch sizing, and self-throttling.
This guide walks through how to safely delete inventory records in bulk using Kibo's Inventory APIs — including how to structure your requests, validate before executing, monitor deletion jobs, and self-throttle your requests to avoid HTTP `429 Too Many Requests` errors.
Best practices, job management, and segmentation via the Inventory API
Use Location Export files to build a complete inventory deletion list
Rate limiting, retry logic, and request patterns for Kibo APIs
Look up current inventory by product identifier before deleting
***
## Overview
Bulk inventory deletion in Kibo is handled through two API endpoints that share the same asynchronous job-based execution model. Both endpoints return immediately — the actual deletion work happens in the background via Kibo's job queue. This means there is no risk of HTTP timeouts for large deletions, and you can track progress through the job IDs returned in the response.
**When you should use these APIs:**
* Removing discontinued product lines across all or selected locations
* Clearing out inventory for a tenant migration or re-platforming effort
* Deleting a large set of SKUs identified by a known naming convention
Deletion is permanent. Always use `dryRun: true` first to verify scope before executing a live deletion.
## The Two Deletion Endpoints
### Option 1: Delete — Single-Product Pattern
[**`POST /api/commerce/inventory/v5/inventory/delete`**](/api-reference/modifyinventory/delete-inventory)
Use this endpoint when targeting **one product identifier** — a single `partNumber`, `upc`, or `sku` — across one or all locations.
#### Request Body
```json theme={null}
{
"dryRun": true,
"allLocations": true,
"partNumber": "DISC-2023-.*",
"locationCodes": [],
"explicit": false
}
```
#### Field Reference
| Field | Type | Description |
| --------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `dryRun` | boolean | When `true`, reports what would be deleted without making any changes. **Always start here.** |
| `allLocations` | boolean | When `true`, targets all locations for the tenant. Overrides `locationCodes`. |
| `locationCodes` | array of strings | Scope the deletion to a specific set of location codes. Ignored when `allLocations` is `true`. |
| `partNumber` | string | The product part number. |
| `upc` | string | Alternative identifier. |
| `sku` | string | Alternative identifier. |
| `explicit` | boolean | When `true`, the response includes full per-item detail (inventory IDs, location IDs, audit IDs). Useful for auditing. |
Provide only one of `partNumber`, `upc`, or `sku` per request. This endpoint is designed for single-product targeting.
***
### Option 2: Delete Items — Multi-Product Bulk Pattern
[**`POST /api/commerce/inventory/v5/inventory/deleteItems`**](/api-reference/modifyinventory/delete-items)
Use this endpoint when you have a **list of multiple products** to delete in one operation. The `items` array accepts individual product identifiers — each specified by `partNumber`, `upc`, or `sku`.
#### Request Body
```json theme={null}
{
"dryRun": false,
"allLocations": true,
"items": [
{ "upc": "UPC-001" },
{ "upc": "UPC-002" },
{ "partNumber": "PART-003" },
{ "sku": "SKU-004" }
]
}
```
#### Field Reference
| Field | Type | Description |
| --------------- | ---------------- | -------------------------------------------------------------------------------- |
| `dryRun` | boolean | When `true`, reports what would be deleted without making changes. |
| `allLocations` | boolean | When `true`, targets all locations. Overrides `locationCodes`. |
| `locationCodes` | array of strings | Scope to specific locations when not using `allLocations`. |
| `items` | array | List of products to delete. Each item may specify `partNumber`, `upc`, or `sku`. |
| `explicit` | boolean | When `true`, returns full per-item deletion detail. |
***
## How Deletion Actually Works (Async Job Model)
Both endpoints operate **asynchronously**. When you submit a deletion request, Kibo:
1. Validates the request.
2. Enqueues **one background job per location** affected by the deletion.
3. Returns immediately with a response — no waiting for the deletion to complete.
This architecture is why these endpoints are safe to use for large-scale operations involving millions of records or hundreds of locations. There is no HTTP timeout risk on the deletion request itself.
#### Example Response
```json theme={null}
{
"dryRun": false,
"totalProductsDeleted": 312,
"totalInventoryEntriesDeleted": 4245251,
"totalLocationsAffected": 312,
"totalAuditsDeleted": 0,
"totalPickWavesDeleted": 0,
"itemsDeleted": [...],
"jobIDs": [12345, 12346, 12347]
}
```
The `jobIDs` array contains one job ID per affected location. For large tenants with many locations, this list can be long. Store all job IDs returned — you will use them to monitor progress.
***
## Monitoring Deletion Progress
Since deletion runs in the background, use the [**Get Job API**](/api-reference/inventoryjob/get-job) to poll each job until it reaches a terminal status.
```text theme={null}
GET /api/commerce/inventory/v1/queue/{jobID}
```
To retrieve all jobs at once (useful when you have many job IDs to review), use the [**Get Jobs API**](/api-reference/inventoryjob/get-jobs):
```text theme={null}
GET /api/commerce/inventory/v1/queue
```
#### Job Status Values
| Status | Meaning |
| --------- | ----------------------------------------------------------------- |
| `PENDING` | Job is queued and has not started yet. |
| `WORKING` | Job is actively being processed. |
| `SUCCESS` | Job completed successfully. |
| `FAILED` | Job encountered an error. Check the `messages` field for details. |
#### Example Polling Approach (Pseudocode)
```text theme={null}
for each jobID in jobIDs:
repeat:
response = GET /api/commerce/inventory/v1/queue/{jobID}
if response.status == "SUCCESS" or response.status == "FAILED":
log result and stop polling this job
else:
wait 10–30 seconds before polling again
```
Do not poll at a rapid fixed interval. Poll every 10–30 seconds per job using exponential backoff, particularly if you have many jobs to track simultaneously. Excessive polling of the job endpoint itself consumes your API rate limit quota.
***
## Step-by-Step: Recommended Execution Workflow
### Step 1 — Identify Your Scope
Decide which products need to be deleted and how to identify them:
* Do they share a naming pattern (prefix, suffix)? → Use the **Delete** endpoint with a `partNumber`/`upc`/`sku`.
* Do you have a discrete list of product identifiers? → Use the **Delete Items** endpoint with an `items` array.
* Are you deleting across all locations, or specific ones? → Set `allLocations: true` or populate `locationCodes`.
#### How to Get a Reliable Full Inventory List Before a Bulk Deletion
There are several paths available, depending on your current tenant configuration and baseline data set:
| Situation | Recommended approach |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The full list of the tenant's product IDs is known (API-only path) | Use [Get Inventory (POST)](/api-reference/inventory/get-inventory-post) per location with [pagination](/pages/api-best-practices), scoped to known identifiers |
| The tenant already receives daily inventory export files | Use the most recent **Location Export** file — it is the authoritative full-tenant inventory list |
| The tenant does not have exports set up yet | Contact [Kibo Support](https://help.kibocommerce.com/) to enable exports, or use your own catalog/ERP as the source of product identifiers to query the Get Inventory API |
The cleanest path for a bulk deletion project is: get the Location Export file → parse all `UPC`/`PartNumber`/`SKU` values from it → use that list as the input to the bulk delete operation. This gives you a provable, timestamped snapshot of exactly what was in inventory at the time of deletion, and a clean audit record.
##### Option A: The Inventory Export File
[**Inventory Export File documentation**](/pages/inventory-export-file)
The **Location Export** is the most reliable way to get a complete, authoritative list of every item at every location across your entire tenant. It includes key fields such as `PartNumber`, `UPC`, `SKU`, quantity on hand, quantity available, safety stock, floor quantity, and `locationCode` for every record.
**The tradeoff:** The export is not on-demand via API. It is a **scheduled daily file** delivered by Kibo to your configured drop point (such as an SFTP site or cloud storage destination). You cannot trigger it yourself via an API call.
* If your tenant already has inventory exports enabled and is receiving daily files, the most recent Location Export file is the best starting point — it gives you a clean, parseable list of all product identifiers per location.
* If the tenant does not have exports enabled, you need to contact [Kibo Support](https://help.kibocommerce.com/) to enable the feature and set up a delivery destination.
**Two export types:**
| **Export Type** | **What it contains** | **Best for** |
| -------------------- | ------------------------------------------------------------ | ------------------------------------- |
| **Location Export** | Every item at every location, with location codes | Building a per-location deletion list |
| **Aggregate Export** | Total quantities across all locations, no location breakdown | Understanding overall scope |
For building a deletion list you will use against the bulk delete endpoint, the **Location Export** is what you want — it gives you the product identifiers and the [location codes](/developer-guides/location-admin) together.
##### Option B: The Get Inventory (POST) API
[**Get Inventory (POST) API**](/api-reference/inventory/get-inventory-post)
The Get Inventory API supports [pagination (`pageSize`)](/pages/api-best-practices) and location filtering. However, there is a critical constraint: **the `items` array in the request body is required**, and it specifies which products you want to look up. This is an inquiry/lookup API — not a "dump everything" API. You cannot submit an empty request and get all inventory back.
* If you already know the product identifiers (e.g., from your ERP or catalog system), you can paginate through the Get Inventory API per location to confirm what exists in Kibo before building your deletion list.
* If you do not have a known product list, the API alone cannot enumerate all inventory records without already knowing what to query for.
### Step 2 — Run a Dry Run First
Always submit your request with `dryRun: true` before any live execution.
```json theme={null}
{
"dryRun": true,
"allLocations": true,
"partNumber": "DISC-2023-.*"
}
```
Review the response carefully:
* `totalProductsDeleted` — confirms how many products match.
* `totalInventoryEntriesDeleted` — shows the volume of records that will be removed.
* `totalLocationsAffected` — tells you how many location-level jobs will be created.
* `itemsDeleted` — if `explicit: true` was set, inspect individual matches before proceeding.
Do not proceed to Step 3 until the dry run results match your expectations.
### Step 3 — Batch Your Live Requests (If Using Delete Items)
If you are using the **Delete Items** endpoint `/api/commerce/inventory/v5/inventory/deleteItems` with a large list of products, do not send all items in a single request. Break your list into batches.
**Recommended batch size: 500 items per request.**
The request returns immediately once jobs are enqueued, but the enqueuing itself is synchronous and bounded by database and process timeout limits. Staying at or below 500 items per batch keeps your requests well within the timeout ceiling, even on tenants with a large number of locations.
**Hard maximum: 1,000 items per request.** The Delete Items endpoint will reject requests that exceed this ceiling under any circumstances.
**Between batches, add a deliberate delay of at least 5–10 seconds.** This serves two purposes: it gives the job queue time to begin processing the previous batch, and it keeps your sustained request rate below the per-minute API rate limit.
**Recommended approach:**
* Split your full product list into batches of **500 items per request**.
* Do not exceed **1,000 items per batch under any circumstances**.
* Submit one batch at a time. Collect all `jobIDs` returned in the response before proceeding.
* **Wait at least 5–10 seconds between batches.**
* Do not use batch completion (all jobs at `SUCCESS`) as a gate before submitting the next batch — the jobs run asynchronously and may take time to work through the queue. Pace by time delay, not by job status.
### Step 4 — Submit the Live Deletion with `dryRun: false`
Once the dry run is validated and your batch strategy is in place, submit with `dryRun: false`. Collect and store all `jobIDs` returned.
```json theme={null}
{
"dryRun": false,
"allLocations": true,
"partNumber": "DISC-2023-.*"
}
```
### Step 5 — Monitor All Jobs to Completion
Poll each job ID using the [Get Job API](/api-reference/inventoryjob/get-job). Log all `FAILED` jobs and their `messages` for investigation. A failed job does not automatically retry — you will need to re-submit a targeted deletion request for any failed scope.
***
## Self-Throttling to Avoid HTTP 429 Errors
Kibo enforces **rate limiting** per API route to protect platform stability for all tenants. If you exceed the allowed request rate, subsequent requests will be rejected with an `HTTP 429 Too Many Requests` response until the restriction window expires.
### Understanding the 429 Response
```text theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```
The `Retry-After` response header tells you exactly how many seconds to wait before making another request. Possible values are **60, 900, 1800, 2700, or 3600 seconds** (1 minute up to 60 minutes). Do not continue making requests during this window — they will also be rejected, and sustained violations can extend the restriction period.
### How Rate Limits Work
Kibo applies limits at both the **per-minute (RPM)** and **per-hour (RPH)** level for each API route. Both limits count against the same requests:
* **Minute limits** reset at the start of each new minute.
* **Hourly limits** operate on a rolling 60-minute window divided into 15-minute buckets.
**Burst behavior:** You can send requests up to the maximum RPM rate, but only for as long as your hourly budget allows. For example, if the inventory route allows 50 RPM and 200 RPH, you can sustain 50 RPM for a maximum of 4 minutes before exhausting your hourly budget. Plan accordingly — do not use your entire hourly quota in a short burst.
To view the exact rate limits for your tenant per API route, go to **Dev Center** > **API** > **Limits**. If you are within limits, the status shows **OK** in green. If throttled, it shows **Throttled** in red.
### Practical Self-Throttling Rules for Bulk Deletion
| **Rule** | **Why It Matters** |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Send one batch at a time.** Never fire multiple deletion requests simultaneously. | Each request to `delete` or `deleteItems` generates jobs and counts against your per-minute and hourly API rate limits. |
| **Add deliberate delays between batches.** Wait at least a few seconds between requests, longer for large lists. | This keeps your sustained request rate below the per-minute limit without exhausting your hourly budget too quickly. |
| **Honor the `Retry-After` header immediately.** If you receive a 429, stop all requests and wait the full duration. | Continuing to send requests during a restriction window will not succeed and may extend the throttle period. |
| **Poll job status at low frequency.** Poll each job every 10–30 seconds, not continuously. | Job status poll requests count against the same `/api/commerce/inventory/*` rate limit pool as your deletion requests. |
| **Schedule large deletions during non-peak hours.** | For US tenants, non-peak hours are **05:00–11:00 UTC**. For EU tenants, **22:00–04:00 UTC**. Running bulk operations during these windows reduces contention. Non-peak hours are calculated in UTC — schedule jobs in UTC to avoid Daylight Saving Time shifting your window. |
### Handling a 429 — Retry Logic Pattern (Pseudocode)
```text theme={null}
function submitWithRetry(requestPayload):
attempt = 0
while attempt < MAX_RETRIES:
response = POST /api/commerce/inventory/v5/inventory/deleteItems (requestPayload)
if response.status == 200:
return response
if response.status == 429:
retryAfterSeconds = response.headers["Retry-After"]
log("Rate limited. Waiting " + retryAfterSeconds + " seconds before retry.")
wait(retryAfterSeconds) // Respect the exact header value
attempt += 1
if response.status == 500 or other error:
wait(exponentialBackoff(attempt)) // Add delay before retrying non-429 errors
attempt += 1
raise Error("Max retries exceeded")
```
Per the [API Best Practices](/pages/api-best-practices), always add delay before retrying on non-200 responses. Use exponential backoff or a similar strategy rather than retrying immediately.
***
## Endpoint and Capability Summary
| **Feature** | **Delete (Single Pattern)** | **Delete Items (Bulk Pattern)** |
| ------------------------ | -------------------------------------------- | -------------------------------------- |
| **Endpoint** | `POST /v5/inventory/delete` | `POST /v5/inventory/deleteItems` |
| **Products per request** | 1 | Many (array of identifiers) |
| **Execution model** | Async — one job per location | Async — one job per location |
| **Timeout risk** | None — returns immediately | None — returns immediately |
| **Dry run support** | Yes | Yes |
| **Location scoping** | `allLocations` or `locationCodes` | `allLocations` or `locationCodes` |
| **Progress tracking** | Job IDs → Get Job API | Job IDs → Get Job API |
| **Best for** | Pattern-based deletion of one product family | Deleting a known list of multiple SKUs |
## Quick Reference: API Links
| Resource | Link |
| ---------------------------------- | ---------------------------------------------------------------- |
| Delete Inventory (single-product) | [API Reference](/api-reference/modifyinventory/delete-inventory) |
| Delete Items (bulk) | [API Reference](/api-reference/modifyinventory/delete-items) |
| Get Job (monitor a single job) | [API Reference](/api-reference/inventoryjob/get-job) |
| Get Jobs (list all jobs) | [API Reference](/api-reference/inventoryjob/get-jobs) |
| Get Inventory (POST) | [API Reference](/api-reference/inventory/get-inventory-post) |
| API Best Practices (rate limiting) | [API Best Practices](/pages/api-best-practices) |
| Inventory Export File | [Guide](/pages/inventory-export-file) |
## Pre-Deletion Checklist
Before running a bulk inventory deletion, confirm the following:
* [ ] Dry run (`dryRun: true`) has been executed and the scope has been reviewed.
* [ ] The `totalProductsDeleted` and `totalInventoryEntriesDeleted` values in the dry run match expectations.
* [ ] If using Delete Items, the full product list has been split into batches of 500 or fewer.
* [ ] A delay between batch submissions is built into the process.
* [ ] A retry mechanism that respects the `Retry-After` header is implemented.
* [ ] Job IDs from the live request have been captured and are being monitored via the Get Job API.
* [ ] The deletion is scheduled during non-peak hours where possible (05:00–11:00 UTC for US tenants; 22:00–04:00 UTC for EU tenants).
* [ ] Any jobs returning `FAILED` status have been reviewed and re-submitted as needed.
# Buy Online Pickup In Store
Source: https://docs.kibocommerce.com/pages/buy-online-pickup-in-store
Buy Online Pickup In Store (BOPIS) shipments follow a slightly different process than Ship to Home (STH).
Learn how transfer shipments work to fulfill orders from alternative locations
See how to fulfill buy online pickup in store orders
Where STH shipments usually print a pack sheet *after* stock validation, pickup shipments instead print a pick sheet *before* validating stock. Then, the shipment is provided for the customer to pick up instead of preparing for carrier shipment.
## Begin Fulfillment
To get started:
1. Go to **Main** > **Fulfiller**.
2. Locate the shipment you want to fulfill, whether through the search bar or the widgets on the Fulfiller homepage.
3. Click **Finish** **Fulfilling Shipment** at the bottom of the shipment details.
* If you accessed this shipment's details page directly, such as by clicking a link from the Order Admin, then this button will not be displayed. Instead, the page will already show you the current shipment step.
### Cancel Fulfillment
At any point in this process, the shipment can be cancelled by clicking **Cancel Shipment** from the dropdown actions menu in the top right. If an order has multiple shipments, then canceling one of its shipments does NOT cancel the other shipments nor the order itself. The order will only be canceled in one of two ways: automatically by the system when all of its shipments are canceled first, or manually by an admin or customer service representative through the Admin UI. See the [Order Admin UI documentation](/pages/cancel-orders-and-shipments) for more information about cancellation at the order level.
Before you begin, note that you can also click **View Workflow** from the above action menu at any point to view the BPM for that fulfillment method.
## Accept Shipment
The first step in the BOPIS fulfillment process is Accept Shipment, where you acknowledge the shipment and indicate that it is ready to start fulfillment.
1. Review the shipment details.
2. Click **Yes**.
## Print Pick Sheet
You must print a pick sheet before you can validate the item availability at your fulfillment location.
1. Click **Print Pick Sheet** to print the sheet.
2. Click **Proceed to Validate Stock**.
3. Alternatively, click **Reject Shipment** if you cannot fulfill this shipment.
## Validate Stock
Stock validation indicates how many of each product you can fulfill.
1. In the **In Stock** column for each shipment, type in the quantity you have in stock.
* Or, if you click inside the field then arrows will appear. Click these to increase or decrease the quantity by one.
* The barcode(s) can also be scanned to be automatically populate this field instead. For more details and configurable scanning options, see [the UI overview](/pages/fulfiller-ui-overview#barcode-scanners).
2. If any additional item identifiers are displayed, such as in the Identification Number column shown below, then enter the appropriate values. These are item-level attributes that denote important unique information such as a serial number, manufacturer number, number for a gift card item to load a value to, or other identifying data point.
* Item identifiers are defined as the `fulfillmentFields` object in the [Create Order API](/api-reference/order/create-order). If any are flagged as required, then you will not be able to proceed until you have provided them.
3. If you have all of the required quantity in stock, click **Ready for Pickup**. If some quantity is not in stock, then your next action will depend on whether the [site setting](/pages/general-settings#site) for BOPIS Transfer at **System** > **Settings** > **General** in the Admin UI is enabled.
* If transfers are enabled, click **Transfer Shipment** to create a transfer for another location to supply the the missing quantity.
* If the site setting is disabled, then you will not be able to request a transfer for the missing quantity. Instead, clicking **Some Items Not Available** will reject the shipment. A pop-up will require the user to select a reason before confirming the rejection and sending the shipment to Customer Care.
If your implementation is set up to allocate inventory from granular fields, then you will be able to adjust the quantities being fulfilled from each granular record during Validate Stock. See the [Granular Inventory Fields guide](/pages/granular-inventory-fields#fulfiller-ui "Granular Inventory Fields") for more details.
### Barcode Scanners
Scanning capability is available for the Validate Stock step, making it easier to input the quantity you have in stock for that shipment. Both USB plug-in laser and camera scanners are supported, though camera scanners are only available through the [mobile fulfiller application](/pages/fulfiller-ui-overview) and will use the camera of that mobile device.
By default, you can input your laser scan into the text field of the In Stock column in the Validate Stock table. However, you can also implement a "Scan UPC/SKU" text box (shown below) that displays above the table to input your scan results. This is a more straightforward method compared to the default interface, but requires a [custom theme change](/pages/fulfiller-theme-customization) to display the field. In your theme, simply activate the `isItemUPCScanAllowed` setting within the language file.
You may also want to reverse the way that the Validate Stock table displays counts when using laser scanning. By default, the In Stock field is populated with the expected count of the order and the fulfiller is expected to decrease this value for any quantity they are rejecting. However, you can instead start the In Stock count at 0 and scan items to increase the value. To enable this behavior, find your `ValidateStockQuantity` [theme settings](/pages/fulfiller-theme-customization) and set `defaultZeroQuantity` to "1" and set both `defaultShipmentQuantity` and `locationInventoryQuantity` to "0" as shown below.
```
"ValidateStockQuantity": {
"defaultZeroQuantity": 1,
"defaultShipmentQuantity": 0,
"locationInventoryQuantity": 0
},
```
## Optional: Waiting for Transfer and Partial Pickup
If a transfer was initiated during Validate Stock, the BOPIS shipment will be placed into Waiting for Transfer. However, it may be possible for the customer to pick up any items that are on-hand before the transfer has arrived.
In this case, the on-hand items are displayed in their own section as shown below. Click **Pickup** to split those items into a new shipment that can be fulfilled while the transfer remains pending for this original shipment. The customer will receive a Partial Pickup Ready email and can come collect these items, then return to pick up the transferred items when they arrive.
## Provide to Customer
In the final step, you have the option to print the pick sheet if needed. Additionally, you may be able to [offer a partial pickup](/pages/transfer-shipments#partial-pickup) if the BOPIS shipment is waiting on a transfer but some items are available.
1. Once the customer arrives to pick up their order, you click either **Customer Accepts Entire Shipment** or **Customer Wants To Cancel** depending on the appropriate case.
2. If the shipment is accepted, then it will be completed and set to the Fulfilled status.
### Change Pickup Contact and Shipment Details
In cases where the customer designated an alternate pickup contact at checkout, the Fulfiller UI will display both the primary and alternate contact details above **Print Pick Sheet** in this step (as well as in the Customer Information tab in the shipment header). This information is not be editable in the Fulfiller UI and can only be changed from the order details page in [the Order Admin UI](/pages/edit-orders#edit-pickup-contacts) or the [Order API](/api-reference/order/addupdate-alternate-contact).
If the customer wants to change the quantity of an item or requires a price adjustment appeasement, you can edit those values within this step.
1. In this case, click the **Edit Shipment** option before accepting or canceling the entire shipment.
2. Click the quantity and/or unit price field and enter the new value.
3. Click **Save Changes**.
4. If changing the unit price, a pop-up will prompt you to select an appeasement reason. The possible reasons include the default options of Damaged or Defective Item, Price Match, Arrived Too Late, Customer Satisfaction, Lost In Transit, and Other (which will require the user to enter the reason information in a text box, with a limit of 255 characters). However, this list can be customized via the Refund Reasons .[before](/pages/refund-reasons-before) and .[after](/pages/refund-reasons-after) API Extension actions.
# Call Center Overview
Source: https://docs.kibocommerce.com/pages/call-center-overview
Customer service representatives (CSRs) can use the Call Center UI to access customer accounts, orders, and returns on a single page to streamline the resolution process and optimize customer interactions. related tasks can also be grouped under customer sessions to improve their workflow.
These comprehensive tools allow CSRs to handle requests more quickly and improve their service quality.
## Access the Call Center
Submit a request to [Kibo Support](http://help.kibocommerce.com/) if you want to use this feature, as it must be enabled in your tenant settings.
Once enabled, the user interface will be available at **Main** > **Customer** > **Call Center** for users with [appropriate permissions](/pages/user-roles "User Roles") (such as the Order Manager role) to view the Catalog and access customers, orders, and returns. The link will not be displayed for users without these permissions.
Refer to the other guides in this category for more details about how to search within the Call Center and manage customer sessions.
# Call-Off Orders
Source: https://docs.kibocommerce.com/pages/call-off-orders
A **Call-Off Order** is a purchase order issued against an existing **Blanket Order** to request the supply of specific goods or services as and when they are required. Rather than renegotiating commercial terms for every procurement, organizations establish a Blanket Order as a long-term purchasing agreement with a supplier. This agreement defines the key commercial terms, such as approved suppliers, pricing, delivery conditions, validity period, and the maximum contract quantity or value.
As business requirements arise throughout the duration of the agreement, individual Call-Off Orders are created to "draw down" or "release" quantities from the Blanket Order. Each Call-Off Order specifies the quantity required, the requested ship date, and any delivery-specific information, while automatically inheriting the pricing and contractual terms defined in the Blanket Order. This enables organizations to procure recurring goods or services quickly and consistently without repeatedly creating new procurement agreements. Each Call-Off Order contributes to the overall consumption of the Blanket Order, allowing organizations to monitor the remaining contract quantity or value until the agreement is fully utilized or reaches its expiry date.
## **Call-Off Order Dashboard**
The Call-Off Orders list view provides access to call-off orders for the selected site.
* **Site Scope Selection:** Select the target site from the site context dropdown to view call-off orders for that site.
* **Centralized Search:** Search for call-off orders using the Call-Off Order Number, External Call-Off Number, Blanket Order Reference, or Account ID.
* **Lifecycle Filtering:** Filter call-off orders by operational status.
## **Call Off Order Information**
Call Off contract level details capture foundational terms for the order: :
* **Call Off Order Number:** Unique system-generated identifier for the Call-Off Order.
* **Blanket Order Reference:** Reference identifier of the parent Blanket Order being drawn against (not applicable to standalone call off orders).
* **B2B Account & Account Name:** B2B Account and account name associated with the order request.
* **External Call Off Number:** Optional buyer-supplied purchase order or external reference number.
* **Status:** Operational lifecycle state of the Call-Off Order.
* **Price List:** Reference to the price list governing product pricing.
* **Payment:** Optional payment information, supporting Purchase Order details.
* **Notes:** Free-text field for internal comments or operational notes.
* **Custom Attributes:** Custom attributes configured for the Call Off Order entity.
* **Channel:** Submission channel through which the order originated.
* Note - Field editability is governed by the call off order status. As the Blanket Order moves through its lifecycle, certain fields become locked to preserve agreement terms.
### **Item Level Details on Call Off Order**
* **Product Code & Product Name:** Product Code being requested and associated product name.
* **Requested Quantity:** Quantity requested on the line item.
* **Requested Ship Date:** Target ship date specified per individual line item.
* **Address:** Delivery destination address or location specified for the line item.
* **Fulfillment Type:** Fulfillment Type assigned to the line item.
* **Inventory Segment:** Inventory segment tags that scope the soft reservation pool.
* **Line Status:** Operational lifecycle state of the individual line item.
* **Unit Price:** Unit price governing the product line item.
* **Call Off Line Attributes:** Custom attributes configured for the Call Off Order line items.
* Note - Field editability is governed by the line item status.
### Fulfillment Details
Line items on a Call-Off Order capture necessary delivery, schedule, and fulfillment attributes prior to submission:
* **Dynamic Location Handling:** The location selection field dynamically adapts based on the chosen fulfillment method. It serves as an **Address** selector for Ship To Home and Delivery lines, or as a **Pickup Location** selector for BOPIS (Store Pickup) lines.
* **Requested Ship Date:** Target ship date specified per line item.
* **Requested Delivery Date:** Buyer-supplied target date for goods arrival. Distinct from Requested Ship Date, RDD serves as the customer's delivery expectation and remains editable while the line item is in an editable state.
* **Estimated Delivery Date:** Read-only, system-calculated date representing when soft-reserved line items are expected to reach the buyer. Dynamically computed using location processing times, carrier transit times, and the reservation time-fence window anchored by the Requested Ship Date.
* **Actual Delivery Date:** Factual record of when the line item was physically delivered.
* **Bulk Line Application:** Delivery address, requested ship date, and fulfillment method can be applied across multiple selected line items simultaneously.
* **Inline Address Management:** New shipping addresses can be added during line setup and saved permanently to the B2B account profile
* **Multi-Ship-To Sales Order Split:** Upon order release, lines are automatically grouped by unique delivery address, creating a separate downstream Sales Order for each destination while maintaining complete traceability back to the Call-Off Order.
* **Fulfillment Validation:** Fulfillment methods are validated against catalog capabilities. If an assigned method is unsupported for a product, submission is halted and affected lines are highlighted for correction.
### Payment Information
Purchase Order is optional on a Call-Off Order. When Purchase Order (PO) payment is selected, captured payment details automatically cascade to downstream Sales Orders upon conversion:
* **Billing Address:** Required; can be selected from saved B2B account addresses or added as a new address.
* **PO Number:** Required field when entering Purchase Order payment.
* **Payment Terms**
* **Amount:** Defaults to the total Call-Off Order amount and is non-editable.
## **Call Off Order Lifecycle & Statuses**
### **Order Statuses**
The contract status reflects the operational state of the overall call off Order
* **Pending:** Standalone Call of is created but not submitted.
* **Hold:** The Call Off Order has passed validation and been accepted. Qty can be soft. reserved against the lines. The Call Off Order is not yet eligible for order release.
* **Partially Reserved:** At least one line has inventory reserved against it.
* **Fully Reserved:** All the line items are fully reserved.
* **Partially Released:** At least one line has converted into a Sales Order but other lines are still in Hold or have inventory reserved and are awaiting release.
* **Fully Released**: All lines have been converted into Sales Orders.
* **Cancelled:** The Call Off Order was cancelled. If a Blanket Order reference was present, any drawn balance is restored to the Blanket.
### **Line Item Statuses**
Each product line within a Call Off Order maintains an independent status that tracks its consumption state under the agreement:
* **Hold:** The line has been accepted and is awaiting inventory reservation.
* **Partially Reserved**: Inventory has been reserved for part of the requested quantity on this line. The line is eligible for order release on the reserved portion.
* **Fully Reserved:** Inventory has been reserved for ALL of the requested quantity on this line.
* **Released:** Line is converted into a sales order.
* **Cancelled:** Line item has been cancelled and any soft inventory reservations are released (terminal state).
## **Creating Call-Off Orders**
### **Creating a Call-Off Order from a Blanket Order**
When created from a Blanket Order, the Call-Off Order references the original agreement. Users can select specific line items from the Blanket Order to create a Call-Off Order.
To create a Call-Off Order from a Blanket Order, navigate to an eligible Blanket Order or the Call-Off Orders list and select lines from the parent contract.
* **Line Selection:** Only contract lines in **Open** or **Partially Consumed** status are available for selection. Lines in **Fully Consumed** or **Cancelled** status are locked.
* **Balance Validation & Drawdown:** Requested line quantities are validated against the Blanket Order line's available remaining balance. Upon successful creation, system automatically decrements the remaining balance on the referenced contract lines and records a consumption audit entry.
* The B2B Account is automatically inherited from the parent Blanket Order.
### **Standalone Call-Off Orders**
To create a standalone Call-Off Order without referencing a Blanket Order, create a new Call-Off Order directly for the B2B Account. Standalone call-offs allow B2B delivery requests to be processed without drawing against a pre-existing commitment agreement. For standalone call-offs, the B2B Account must be manually selected during creation.
### **Inventory Reservation**
Inventory soft reservations protect supply for confirmed orders without creating immediate fulfillment obligations:
* **Line-Level Trigger:** At the line level, a line item starts in Hold status while awaiting inventory soft reservation. Reservation is not triggered at order creation time.
* **Reservation Transition:** Once inventory is allocated, that specific line item transitions from Hold to Partially Reserved or Fully Reserved.
* **Multi-Location Allocation Records:** A single line item may hold multiple reservation records across different fulfillment locations to satisfy the total requested quantity.
### **Inventory Segmentation**
Inventory segments allow merchants to scope inventory reservations to specific, labeled inventory segments:
* **Line-Level Segment Tags:** Inventory segment tags are configured at the line item level to target specific inventory segments.
* **Segment Tag Updates:** Inventory segment tags can only be updated while a line item is in Hold status. They become permanently locked once a line item transitions to Partially Reserved or Fully Reserved.
### **Manual Release**
Administrators can execute manual release overrides to bypass background release schedules and immediately process lines currently in Partially Reserved or Fully Reserved status. Manual releases convert quantities backed by active inventory reservations directly into downstream Sales Orders.
### **Call Off Order Level Manual Release**
Header-level manual release allows administrators to process all reservation-backed lines within a Call-Off Order simultaneously:
* **Eligible Header Statuses:** Available only when the order header status is Partially Reserved, Fully Reserved, or Partially Released. It is unavailable when the order is in Pending, Hold, Fully Released, or Cancelled status.
* **Reservation-Backed Conversion:** Executing a header release converts only line items (or partial quantities) currently in Partially Reserved or Fully Reserved status. Lines in Hold status are not converted.
* **Selective Order Generation:** Converted line items immediately generate downstream Sales Orders.
### **Line-Item Manual Release**
Users can also release individual line items independently:
* **Eligible Line Statuses:** Available strictly for individual line items in Partially Reserved or Fully Reserved status. Lines in Hold, Released, or Cancelled states do not expose manual release controls.
* Executing a line manual release converts only the targeted line item into a downstream Sales Order line.
A user can execute manual release actions only if assigned the required behavior permission.
### **Credit Hold Management**
Call-Off Orders include credit hold controls to prevent unapproved order conversions:
* **Order Release Blocking:** Call-Off Orders can be placed on Credit Hold manually by administrators or automatically via external credit engine integrations. While on Credit Hold, order lines cannot be released or converted into Sales Orders.
* **Customizable Reasons:** An explicit reason code can be specified when applying a credit hold, with reason lists customizable by administrators.
* **Extensibility Hooks:** System provides API extension points at creation and release to call external credit engines that dynamically place orders on or remove them from credit hold.
### Cancellation
Order and line item cancellations handle balance restoration and inventory allocation release:
* **Mandatory Cancellation Reasons:** An explicit cancellation reason code must be specified when cancelling an order or an individual line item. Cancellation reason options can be customized by administrators.
* **Inventory Reservation Release:** Cancelling a line item automatically releases any soft inventory reservations held for that line.
* **Blanket Balance Restoration:** For contract-linked Call-Off Orders, cancelling a line item automatically restores the requested line quantity back to the parent Blanket Order line's available balance and recalculates the contract status.
### **Extensible Attributes**
* **Call Off Order Attributes:** Call off order attributes capture custom order level data, such as such as special project codes, or buyer department references. For full configuration details on entity selection and attribute value sync settings, see [Extensible Attributes](https://docs.kibocommerce.com/pages/schema-extensible-attribute).
* **Call Off Order Item Attributes:** Call off order item attributes capture custom line item level data, such as line-level priority flags or special fulfillment instructions. For full configuration details on entity selection and attribute value sync settings, see [Extensible Item Attributes](https://docs.kibocommerce.com/pages/schema-extensible-item-attribute).
### **Audit Log**
Every modification made to a Blanket Order or its line items is automatically recorded in the contract audit log, capturing the user identity, timestamp, modified field, original value, and updated value.
# Call Off Release Rules
Source: https://docs.kibocommerce.com/pages/call-off-release-rules
Order Release Rules determine precisely when and under what conditions Call-Off Order lines become eligible to convert into downstream **Sales Orders**.
Merchants configure rules to automate order release using **Product Rules**, **Customer Rules**, **Call-Off Order Rules**, and **Release Parameters**, and **Site Scoping** . An automated background process runs per site, evaluating call-off lines against active rules. Order Release Rules are managed in the KIBO Admin UI. The list view displays active rules within your selected site context and outlines the conditions a Call-Off Order line must satisfy to be eligible for release.
* **Controlled Order Conversion:** Automatically schedules order conversion based on configured release timing parameters.
* **Inventory-Aware Release:** Requires a configurable minimum inventory fill rate threshold before a line converts, preventing premature release of under-allocated orders.
* **Demand & Buyer Prioritization:** Evaluates account, product, and order criteria to prioritize specific B2B accounts or products during release.
* **Automated Processing Pipeline:** Evaluates line items across configurable background job cycles, converting eligible items into Sales Orders.
## **Release Rules List View**
* Navigate to Main > Demand > Rules > Call Off Order Release Rules
* **Site-Level Configuration:** Select a target site from the site selector to view and manage the order release rules.
* **Execution Status Monitoring:** Displays real-time execution status for the background release job, providing operational visibility into the most recent run date, job status, and completion time.
* **Prioritized Rule Evaluation:** Rules are displayed in ascending priority sequence based on their assigned rank. Call-Off Order lines are evaluated against rules in this exact order, and evaluation stops as soon as a rule match is found.
* **Rule Status Toggle:** Individual rules can be toggled on or off to include or exclude them from evaluation cycles.
## **Configuring Release Rules**
Each Call-Off Release Rule combines targeting criteria with execution parameters to determine when specific order lines qualify for Sales Order conversion:
### **Administrative & Priority Settings**
* **Rule Code:** Unique alphanumeric identifier for the rule.
* **Rule Name & Description:** Unique descriptive identifier and optional summary capturing the business purpose of the rule.
* **Rank:** Priority sequence number that determines evaluation order, where lower numerical values represent higher evaluation priority. If left blank during rule creation, the system automatically assigns the next available rank.
* **Enabled Status:** Active toggle controlling whether the rule is included in automated background evaluation runs.
### **Combining Conditions**
Rules filter order lines using condition builders supported by logical operators (AND / OR) to define evaluation criteria.
### Supported Rule Parameters
Conditions can be configured using attributes across three distinct criteria categories:
* **Product Rules:** Filter order lines by catalog properties, such as Product Code, Variant Product Code, UPC, Product Type, Category Code, Catalog List Price, Fulfillment Types Supported, or custom product attributes.
* **Customer Rules:** Filter order lines by B2B account properties, limited to:
* Customer (Account ID)
* Customer Segment
* Account Attribute
* **Call-Off Order Rules:** Filter order lines at the header or line item level using parameters including **Call-Off Order Total Amount**, **Account ID**, **Channel Code**, **Item Product Code**, and **Item Requested Ship Date**, as well as custom **Order Attributes** (header level) and **Item Attributes** (line level).
### **Release Execution Parameters**
Once an order line matches the rule conditions, the platform applies two required execution parameters to determine conversion eligibility:
* **Release Fence Days:** Configures the advance window (in days) prior to the requested ship date when line conversion is permitted. The platform calculates the conversion date using: Release Date = Requested Ship Date - Release Fence Days
* **Minimum Fill Rate (%):** Configures the minimum percentage of requested inventory that must be successfully soft-reserved before line conversion can occur.
### **Eligibility Criteria**
To qualify for Sales Order conversion under a matched rule, a Call-Off Order line must satisfy two criteria simultaneously:
1. **Release Timing Condition:** The current date must reach or pass the computed release date:
Release Date = Requested Ship Date - Release Fence Days
2. **Minimum Fill Rate Condition:** The line item's current fill rate must meet or exceed the rule's **Minimum Fill Rate (%)** threshold: (Reserved Quantity\Requested Quantity) \* 100
3. Note: Lines already in **Released** or **Cancelled** status are skipped during evaluation.
### **Evaluation Outcomes & Scenarios**
* **Release Date Reached, Fill Rate Not Met:** If the release date window is open but the reserved inventory does not meet the minimum fill rate threshold, the line remains unreleased and continues to be evaluated on subsequent background runs.
* **Fill Rate Met, Release Date Not Reached:** If the fill rate threshold is satisfied prior to the release window opening, the line holds in its current reserved status until the computed release date arrives.
* **Partial Reservation Release:** When both eligibility conditions are met for a partially reserved line (for example, 80% reserved against an 80% minimum fill rate rule), a Sales Order is created for the reserved quantity, while the unreserved balance remains on the order.
## **Background Release Job Configuration & Sales Order Conversion**
Automated line evaluation is controlled by a site-level background job configured within the platform:
* **Site Setting Location:** Accessible under **Site Settings > B2B** in the Kibo Admin UI.
* **Job Activation & Frequency:** Administrators enable the background release job and define its execution frequency to dictate how often unreleased lines are evaluated.
When a Call-Off Order line satisfies all eligibility conditions during a release run, the platform automatically converts the reserved quantity into a downstream Sales Order. The generated Sales Order inherits the exact fulfillment location established during inventory reservation. Product pricing, custom attributes at both header and line levels, and Purchase Order payment specifications flow directly from the Call-Off Order to the Sales Order. Each generated Sales Order maintains explicit bidirectional references back to the originating Call-Off Order for complete audit traceability. Upon conversion, the Call-Off Order line transitions to Released status, while the overall order header updates to Partially Released or Fully Released depending on the status of remaining lines.
### Run Release Rules
While Call-Off Release Rules are processed automatically on a background schedule, administrators can manually trigger an evaluation cycle at any time using the Run Release Rules button on the Call-Off Release Rules dashboard.
1. **On-Demand Execution:** Submits an immediate, site-scoped release run that evaluates all Call-Off Order lines within the active site context against all active Call-Off Release Rules. Only lines that satisfy eligibility criteria are released; ineligible lines are skipped and remain available for evaluation on subsequent runs.
2. **Ranked Rule Evaluation:** The system evaluates lines against enabled Call-Off Release Rules in ascending rank order (Rank 1 being highest priority). The first rule whose conditions a line satisfies is applied; no further rules are evaluated for that line. Disabled rules are skipped entirely.
3. **Eligibility Processing**: For each line, the system verifies the line against the two required Eligibility Criteria (Release Timing Fence Days and Minimum Fill Rate %). Lines failing either condition are skipped with a recorded skip reason.
4. **Sales Order Creation**: Lines satisfying all rule criteria are grouped by fulfillment destination and asynchronously converted into downstream Sales Orders. Line statuses update to Released, maintaining explicit links back to the originating Call-Off Order line.
5. **Real-Time Progress Monitoring:** Executing a run activates a "Last Run" status banner on the dashboard that updates in real time—polling from Running until the job reaches Completed. Status polling automatically resumes if you navigate away and return to the page.
# Call Off Reservation Rules
Source: https://docs.kibocommerce.com/pages/call-off-reservation-rules
Call Off reservation Rules define which Call-Off Orders are eligible for inventory reservation and in what priority order. When the Reservation batch job runs, it evaluates all Call-Off Orders in **Hold** or **Partially Reserved** status against your configured rules — ranked by priority — and invokes the Reservation Service to soft-allocate inventory for matched orders. Rules that rank higher receive inventory first; lower-ranked rules only see what remains after higher-priority rules have completed their allocation pass.
Call Off reservation Rules follow the same composable rule structure used across Kibo for other rule types such as [Purchase Limit Rules](/pages/purchase-limit-rules) and [Call-Off Release Rules](/pages/call-off-release-rules), using the same expression-based criteria framework for product, customer, and Call off order-level conditions.
In addition to the UI detailed here, you can create and manage Call Off reservation Rules with the Reservation Rules API endpoints. The [Product Rules](https://docs.kibocommerce.com/api-reference/productrules/create-product-rule) , [Customer Rules](https://docs.kibocommerce.com/api-reference/accountrankingrule/create-customer-rule) and [**Call Off Order Rule**](https://docs.kibocommerce.com/api-reference/calloffreleaserules/create-call-off-release-rule) APIs can also be used to manage supporting product , customer rules and call off order rules.
## **Prerequisites**
Before configuring Reservation Rules, ensure the following:
* The **B2B Wholesale OMS** feature is enabled for your tenant. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this capability.
* You have the **Admin** or **Super Admin** role, or a role with the following behaviors assigned:
* Product Rule: Read, Create, Update, Delete
* Customer Rule: Read, Create, Update, Delete
* Reservation Rule: Read, Create, Update, Delete
* At least one [**Call-Off Order**](/pages/call-off-orders) exists in **Hold** status as input to the engine.
## **How Reservation Rules Work**
### **Rule Evaluation Order**
Call Off reservation Rules are evaluated in **ascending rank order** — the rule with **Rank 1** has the highest priority and runs first. All Call-Off Orders matched by Rank 1 are allocated inventory before Rank 2 runs. Rank 2 only sees inventory remaining after Rank 1 has completed its full pass.
A Call-Off Order line matched by a higher-priority rule is excluded from lower-priority rules in the same batch cycle. This prevents double-allocation and ensures deterministic, priority-based inventory distribution.
**Note:** All enabled Call Off reservation Rules run as a group in each batch cycle. There is no option to trigger an individual rule in isolation.
### **Rule Matching Logic**
A Call-Off Order must satisfy **all** criteria types defined on a rule (AND logic across criteria types) to be eligible under that rule. Within a single criteria type — for example, within Product Criteria — conditions can be combined using **AND** or **OR** logic as configured in the expression editor.
If a rule defines a simple criteria for a particular type which will match all the call off orders (e.g Total Amount ≥ 1\$), all orders automatically pass that criterion. This makes it straightforward to configure a **catch-all rule** at the lowest rank to ensure every Call-Off Order receives an allocation pass.
### **Priority Enforcement**
The rule engine processes rules as the **outer loop**. Rule N+1 only receives the inventory left after Rule N has fully completed allocation across all its matched Call-Off Orders. This architecture ensures that high-priority buyers always receive their inventory preference before lower-priority segments are served.
## **Rule Criteria**
A Call Off reservation Rules is a composite rule made up of up to three criteria types. **All** types present on a rule must match (AND logic across types) for a Call-Off Order to qualify:
| **Criteria Type** | **What It Filters** | **Notes** |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Product Criteria** | Which products the rule applies to | Uses the existing Product Rule infrastructure . Supports first-class fields(like-Product Code, Variant Product Code, UPC, Mfg Part Number ,Product Type, Category Code, Category List Price, Fulfilment Types Supported, Height, Length, Weight, Width), attributes properties |
| **Customer / Account Criteria** | Which B2B buyer accounts qualify | Uses the existing Customer Rule infrastructure. Supports Customer & Customer Segment. |
| **Call-Off Order Criteria** | Call-Off Order header and line-level attributes such as channel, order type, total amount, and custom attributes | Expression-based criteria type specific to B2B Wholesale OMS. Like Call-Off Order Total Amount, Account ID, Channel Code, Item Product Code, and Item Requested Ship Date, as well as custom Order Attributes (header level) and Item Attributes (line level). |
**Note:** Product Rules , Customer Rules and call off order rules created for Call Off reservation Rules are exclusive to Call Off reservation Rules and cannot be shared with other rule types such as [Purchase Limit Rules](/pages/purchase-limit-rules) or [Return Rules](/pages/return-rules).
## **Time Fence Configuration**
Each Reservation Rule includes a **Time Fence Days** parameter that controls the inventory search window used when performing Order Routing for matched Call-Off Order lines.
The time fence is calculated symmetrically around the line's **Requested Ship Date**:
* `deliveryDateAfter = requestedShipDate − timeFenceDays`
* `deliveryDateBefore = requestedShipDate + timeFenceDays`
Only inventory available within this window is considered during Order Routing. A value of `0` means only inventory available exactly on the requested ship date is considered.
**Note:** Requested Ship Date is mandatory on every Call-Off Order line. The time fence has no site-level fallback default.
## **Rule Attributes**
| **Attribute** | **Type** | **Required** | **Description** |
| :-------------------------- | :------- | :----------- | :---------------------------------------------------------------------------------------------------------- |
| **Code** | String | Yes | Unique identifier for the rule, scoped to the tenant. Auto-generated if left blank. |
| **Name** | String | Yes | Display name shown in the Admin UI. |
| **Description** | String | No | Optional free-text description of the rule's intent. |
| **Rank** | Integer | Yes | Priority order. Lower value = higher priority. Rank 1 runs before Rank 2. Rank values must be unique. |
| **Enabled** | Boolean | Yes | When disabled, the rule is skipped during batch evaluation but remains saved for future use. |
| **Time Fence Days** | Integer | Yes | Symmetric window (±N days) around `requestedShipDate` for inventory search. Must be a non-negative integer. |
| **Product Criteria** | List | No | References to Product Rule codes defining which products this rule covers. |
| **Customer Criteria** | List | No | References to Customer Rule codes defining which accounts qualify. |
| **Call-Off Order Criteria** | List | No | References to Call-Off Order Rule codes defining order-level filters. |
At least one Criteria is mandatory out of Product Criteria , Customer Criteria & Call-Off criteria
## **Configure Call Off Reservation Rules**
To create a new Call Off Reservation Rule:
1. Go to **Main > Supply> Rules > Call Off Reservation Rules**.
2. Select a **Site** from the site selector.
3. Click **Create Reservation Rule**.
4. Enter a **Code**. If left blank, the system generates one automatically.
5. Enter a **Name** and an optional **Description**.
6. Enter a **Rank** value. The lower the number, the higher the priority.
7. Enter a **Time Fence Days** value. Enter `0` to restrict the inventory lookup to the exact requested ship date only.
8. Toggle the rule **Enabled** to activate it for batch processing.
9. Optionally, add **Product Criteria**:
* Click **Add Product Rule** to select an existing product rule or create a new one.
* Use the expression editor to define product-level conditions. Click **Preview** to view a list of products that would be matched by the expression.
10. Optionally, add **Customer / Account Criteria**:
* Click **Add Customer Rule** to select an existing customer rule or create a new one.
* Use the expression editor to define account-level conditions such as segment, priority, ID, or custom attributes.
11. Optionally, add **Call-Off Order Criteria**:
* Click **Add Call-Off Order Rule** to create a new expression for order-level conditions such as channel, total amount, custom attributes, or requested ship date.
At least one Criteria is mandatory out of Product Criteria , Customer Criteria & Call-Off criteria
12. Click **Save**.
**Note:** Rules are scoped to the site level. A rule configured for one site applies only to Call-Off Orders processed under that site.
## **Manage Call Off Reservation Rules**
The dashboard at **Main** > **Supply**> **Rules** >**Reservation Rules** displays all existing rules and allows you to manage them with the following actions:
* Toggle the **Status** icon on a rule to activate or deactivate it without deleting it. Disabled rules are skipped during batch processing.
* Click on the Kebab icon on a rule to **Edit** or **Delete** it.
* Check multiple rules and then use the **Actions** menu in the top right to enable, disable, or delete them in bulk.
* Edit the **Rank** of a rule directly in the table, or click and drag to reorder. Rules are always evaluated from highest to lowest rank, with Rank 1 running first.
## **Example Rule Configurations**
### **Priority Allocation for Strategic Accounts**
Configure two rules to ensure platinum-tier buyers always receive inventory before standard-tier buyers:
| **Rule** | **Rank** | **Customer Criteria** | **Expected Behavior** |
| :------- | :------- | :---------------------------------- | :------------------------------------------------------- |
| Rule 1 | 1 | `account.segment equals "platinum"` | All platinum-tier Call-Off Orders are allocated first. |
| Rule 2 | 2 | `account.segment equals "standard"` | Standard-tier orders receive whatever inventory remains. |
### **Channel-Based Reservation Priority**
Prioritize wholesale channel orders over outlet channel orders:
| **Rule** | **Rank** | **Call-Off Order Criteria** | **Expected Behavior** |
| :------- | :------- | :-------------------------- | :------------------------------------------------- |
| Rule 1 | 1 | `channel eq "wholesale"` | All wholesale Call-Off Orders are allocated first. |
| Rule 2 | 2 | `channel eq "outlet"` | Outlet orders receive remaining inventory. |
# Campaigns
Source: https://docs.kibocommerce.com/pages/campaigns
Campaigns allow you to design marketing strategies across your entire site by coordinating storefront product displays and promotions. This guide describes how to manage campaigns in the Admin UI. This includes creating promotions within a campaign and page variations for displaying content.
## Example Campaign
For example, a Summer Savings campaign runs from June 1—July 30 and features flip flops, swimwear, and barbecue gear. This campaign includes the following elements:
* There are multiple promotions running during this time period for the category and product levels:
* Category: All Women’s Flip Flops \$5 Off during June 1st through 15th.
* Product: Smoky Joe Grill—20% Off throughout the campaign.
* Shoppers can use the “FABSUMMER40" coupon code on any product in the above categories in the first launch week of the campaign.
* A banner image displays deals and trends on the storefront landing page and all content pages.
* This campaign is targeted to particular customer segments in promotions and site variations.
## Campaign Homepage
At **Main** > **Marketing** > **Campaigns**, you can view the list of all existing campaigns and their current statuses (which are Scheduled, Active, Ended, or Disabled). The campaign code, name, and start/end dates are displayed by default, but you can customize the columns that are shown or hidden by using the dropdown menu in the top right corner of the table. To view, edit, or delete a campaign, expand the dropdown menu on the right.
By default, the table will not include campaigns that have ended. However, you can display them by using the Advanced Filter of the search bar.
## Experiences
Before creating a campaign, it is important to understand how campaign experiences work. Experiences are the set of discounts and site content that support your campaign and form the shopper experience.
When adding experiences, you will configure the following in your campaign details:
1. Set up discounts
2. Set up page variations
3. Set up merchandizing rules
### Discounts
Discounts are often important to campaigns, as they supply the price reductions and coupon codes usually associated with a marketing campaign. However, you can still create a campaign without discounts—such as if a campaign is intended to highlight a certain set of products that are not necessarily on sale.
When creating a campaign, you can only add discounts whose active date ranges fit within the start/end dates of the campaign. Though not recommended, you can edit the discount to extend its active dates beyond the end date of the campaign. This discount will be highlighted in red to indicate that its dates are out of range for the campaign, but the discount will still be active and run for the entire length of its time frame.
Expand the dropdown menu on the right side of a listed discount to edit or remove it. Removing it from the campaign will not delete the discount in your system, and you can still access it in **Main** > **Marketing** > **Discounts**.
### Site Variations
You can assign page variations to a campaign for your storefront to display themed versions of pages to support your campaign while it is active. This table will display variations under the template they belong to, their start/end dates, ranking preference, and associated customer segment. This allows you to use multiple variations of the same page template during your campaign, such as if you want certain customers to see an alternate version of the homepage or if you want different messaging to be displayed on the final day of the campaign to help drive last-day sales.
As with discounts, you can only add page variations whose active date ranges fits within the start/end dates of the campaign while you are initially creating the campaign. Later, you can edit the variation to extend its active dates beyond the end date of the campaign. This variation will be highlighted in red on the listing page to indicate that its dates are out of range for the campaign.
Expand the dropdown menu on the right side of a listed variation to edit or remove it.
### Merchandizing Rules
Merchandizing rules are part of the Search feature and provide the ability to create and manage boost and bury conditions, sort definitions, and control how products are displayed in specific search scenarios. They can be applied to both Site and Category [search types](/pages/search-types "Search Types"), which are maintained as separate lists that you can switch between when viewing the merchandizing rules on the campaign. For more information, see the [merchandizing rules guide](/pages/merchandizing-rules "Merchandizing Rules").
When adding merchandizing rules to a campaign, the same active date range requirements will be used for merchandizing rules as with discounts and site variations. This means that you cannot add a merchandizing rule when initially creating the campaign if its active date range does not fit into the campaign's date range.
Expand the dropdown menu on the right side of a listed rule to edit or remove it. Removing it from the campaign will not delete the rule in your system, and you can still access it in **Main** > **Search** > **Merchandizing Rules**.
## Create a Campaign
Campaigns are set up at the child catalog level and will be activated across all sites that belong to that child catalog, so make sure that you have selected your preferred catalog at the top of the page before creating a new campaign.
To create a campaign:
1. Go to **Main** > **Marketing** > **Campaigns**.
2. Click **Create New Campaign** in the top right.
3. Toggle whether you want the campaign to be immediately enabled or not.
4. Enter an ID (code) and name for the campaign.
5. Select a start and end date for the campaign. Note that if the campaign is disabled, then it will not automatically activate when the start date is reached.
6. Enter an optional description if desired.
7. Click **Save**. Note that the Discounts, Site Variations, and Merchandizing Rules tabs are disabled until you have saved the campaign with its general settings first.
8. In the Discounts tab, add any discounts to the campaign. You can:
1. Click **Select** to select an existing discount to add to the campaign.
2. Click **Create New** to configure a new discount. This will open the Discounts page in a new tab, where you can click **Create New Discount** and follow the [usual discount creation process](/pages/configure-discounts). Then, go back to your Campaigns tab and select the new discount to add it to the campaign.
9. In the Site Variations tab, add any page variations to the campaign. You can:
1. Click **Select** to select an existing variation to add to the campaign.
2. Click **Create New** to configure a new variation. This will open the Content Editor page in a new tab, where you can [create page variations](/pages/general-settings). Then, go back to your Campaigns tab and select the new variation to add it to the campaign.
3. You can switch between Single Pages and Category Pages to view those different types of page variations. They display similar information, but the category page table includes the associated category code for each variation.
10. In the Merchandizing Rules tab, add any Search merchandizing rules to the campaign. You can:
1. Click **Select** to select an existing rule to add to the campaign.
2. Click **Create New** to configure a new rule. This will open the Merchandizing Rules page in a new tab, where you can click **Create New Rule** and follow the [usual rule creation process](/pages/merchandizing-rules). Then, go back to your Campaigns tab and select the new rule to add it to the campaign.
3. You can switch between Site Search and Categories to view those different types of merchandizing rules.
11. Click **Save** again to finalize these configurations.
## Edit or Delete a Campaign
Clicking on an existing campaign on the Campaigns home page will open the campaign configurations for editing. This includes changing the start/end dates, which allows you to stop an active campaign or modify a scheduled campaign, as well as adding or removing discounts, site variations, and merchandizing rules.
However, when you update a campaign's start/end dates then it is possible that the experience no longer lies within the timeline of the campaign. The experience will not be automatically updated, but these elements will be flagged on the campaign's Discounts and Site Variations configuration tabs for the user to update as needed.
You can delete a campaign by expanding the dropdown menu on the far right of the campaign listing on the home page and clicking **Delete**. When confirming, you must choose whether to keep the associated discounts and variations or delete them along with the campaign.
## Activate or Deactivate a Campaign
While the campaign will automatically become active on your site once the start date is reached, you can also manually enable campaigns prior to that date. Likewise, the campaign will automatically end once the end date is reached but you can manually disable it prior to that date if desired.
To toggle a campaign:
1. Go to **Main** > **Marketing** > **Campaigns**.
2. Either click a campaign in the table or select **View/Edit Campaign** from the dropdown menu on the right.
3. Toggle the campaign to enable or disable it. If you make other edits to the campaign first, you must save those changes before you will be able to update this toggle.
4. This toggle will also enable or disable the experiences within the campaign including all discounts, merchandizing rules, and site variations (even if they are used in other campaigns as well). A pop-up will warn you about this behavior and ask you to confirm.![The Enable Campaign pop-up asking the user to confirm]()
5. Click **Save** in the top right.
If you need to manually enable or disable specific discounts, merchandizing rules, or page variations (such as if you disable a campaign but need to turn some of those experiences back on for other campaigns), then you can do so from the respective [Discounts](/pages/configure-discounts "Configure Discounts"), [Merchandizing Rules](/pages/merchandizing-rules "Merchandizing Rules"), and Content Editor UIs.
# Cancel Orders and Shipments
Source: https://docs.kibocommerce.com/pages/cancel-orders-and-shipments
In the Admin UI, you can either cancel an entire order which requires crediting the customer's payment or cancel individual shipments within the order. If all shipments are cancelled on an order, then the order will be automatically cancelled and credited as well.
For information about canceling individual line item quantities, see [Edit Order Items](/pages/edit-order-items#cancel-item).
## Cancel an Order
While individual shipments can be canceled from their assigned fulfillment location in the Fulfiller UI, orders must be either canceled manually in the Admin UI or canceled automatically by the system when all of its shipments are canceled first. When doing a manual cancellation, you will generally have to credit the order payments first.
However, if the order is in the Pending Shipments status and payments have not yet been collected, then you can immediately cancel the order without having to perform any extra steps as there are no shipments or amounts to credit. Do this by clicking **Cancel Order** from the order details screen.
If the `restrictCancellation` flag is set to true on the order [via API](/pages/orders-api-overview "Orders API Overview"), then a user without the Override Order Update Restriction [behavior](/pages/user-roles "User Roles") will not be able to cancel the order. However, they will still be able to cancel individual shipment line items if the `restrictEdit` flag is not set to true.
### Automatic Cancellation
When all shipments are canceled from an order (whether from the Admin UI as detailed in the [Cancel a Shipment](#cancel-a-shipment) section or by fulfillers), the order is automatically canceled as well. This automatic cancellation voids all authorized payments and credits any captured payments by the system, and does not require an administrator or customer service representative to perform those actions.
If there is a failure in these processes and the order is unable to finish canceling, then an notification will be triggered and the order will need to be manually canceled per the steps in the Admin UI detailed in the next section. This email can be enabled/disabled in the general site settings at **System** > **Settings** > **General** > **Email** as “Cancel Order Failure” in the email options and is enabled by default.
### Manual Cancellation
Manual cancellation is a two-step process that first requires either voiding the payment auth or issuing a credit before canceling the order. When the order is canceled, then all of its shipments will be automatically canceled as well (if they are not already).
Whether to void payment auth or issue a credit depends on how authorization and capture is configured in the site settings and what the payment state is. If the shopper’s card has been authorized but not paid, then the auth must be voided. If payment has been captured, then it should be credited. Even if the amount to be returned is \$0.00, the credit should still be performed in the system before canceling the order.
When manually canceling an order, payment can be either voided or credited from the dropdown menu in the **Payments** tab of the Order Details depending on whether payment has already been captured or not. For example, in a case where payment has been captured and shipments exist:
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to cancel to open its order details.
3. Click on the **Payments** tab.
4. Click the drop-down action menu on the payment you want to credit.
5. Click **Credit Payment**.
6. A popup will appear to confirm the amount. You can change this value as needed.
7. Enter a reason for the credit.
8. Click **Save** to confirm.
If the entire amount is credited, the order's payment status will be changed to “Credited" and you will be able to cancel the order.
## Cancel a Shipment
An individual shipment can be canceled from an order from the order details. Payment does not have to be credited first if only one shipment is being cancelled and not the entire order.
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to cancel a shipment from to open its order details.
3. Click on the **Shipments** tab.
4. Click **Update Shipment** to open the shipment status change options.
5. Click **Cancel Shipment**.
6. Select a reason for the cancellation.
7. Click **Cancel shipment** to confirm.
You can have your tenant configured to retain the handling fee when an entire shipment is cancelled. The handling total of its items will be redistributed to another active Ship-to-Home shipment on the order (with priority by status: Ready, Future, Backorder, Customer Care, and then Fulfilled). In eCommerce+OMS implementations that do not distinguish between order-level and item-level handling fees, the total order handling fee will be retained. If there are no available STH shipments, the handling cost will be cancelled. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this behavior.
# Cancel Reasons (After)
Source: https://docs.kibocommerce.com/pages/cancel-reasons-after
This action manipulates the HTTP request or response around the shared cancel reasons operation, which returns cancellation reasons for the specified resource type and category. This endpoint is shared by Blanket Orders and Call-Off Orders and is distinct from the order-level [cancellation reasons](/pages/cancellation-reasons-before) action. Category defaults to `SHOPPER` and category matching is case-insensitive.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.cancel.reasons.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**
This action corresponds to the shared cancel reasons operation (`api/commerce/cancel/reasons`).
**HTTP Request**
GET `api/commerce/cancel/reasons?resourceType={resourceType}&category={category}&skip={skip}&take={take}`
**Request Body**
There is no request body for this GET operation.
**Response Body**
Use `context.response.body` to write the HTTP response body using this action. The response body is a `CancelReasonCollection` containing the cancellation reasons for the specified resource type and category.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Cancel Reasons (Before)
Source: https://docs.kibocommerce.com/pages/cancel-reasons-before
This action manipulates the HTTP request or response around the shared cancel reasons operation, which returns cancellation reasons for the specified resource type and category. This endpoint is shared by Blanket Orders and Call-Off Orders and is distinct from the order-level [cancellation reasons](/pages/cancellation-reasons-before) action. Category defaults to `SHOPPER` and category matching is case-insensitive.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.cancel.reasons.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**
This action corresponds to the shared cancel reasons operation (`api/commerce/cancel/reasons`).
**HTTP Request**
GET `api/commerce/cancel/reasons?resourceType={resourceType}&category={category}&skip={skip}&take={take}`
**Request Body**
There is no request body for this GET operation.
**Response Body**
Use `context.response.body` to write the HTTP response body using this action. The response body is a `CancelReasonCollection` containing the cancellation reasons for the specified resource type and category.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Cancellation Reasons (After)
Source: https://docs.kibocommerce.com/pages/cancellation-reasons-after
**Related API:** This extension modifies the [Get Order Cancel Reasons](/api-reference/order/get-order-cancel-reasons) operation.
This action manipulates the HTTP request or response after the GetCancelReasons operation occurs in Kibo. This enables customization of the order cancellation reasons.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.orders.cancellationReasons.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Get Cancellation Reasons](/api-reference/order/get-order-cancel-reasons) operation.
**HTTP Request**
GET `api/commerce/orders/cancel/reasons`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Cancellation Reasons (Before)
Source: https://docs.kibocommerce.com/pages/cancellation-reasons-before
**Related API:** This extension modifies the [Get Order Cancel Reasons](/api-reference/order/get-order-cancel-reasons) operation.
This action manipulates the HTTP request or response before the GetCancelReasons operation occurs in Kibo. This enables customization of the order cancellation reasons.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.orders.cancellationReasons.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Get Cancellation Reasons](/api-reference/order/get-order-cancel-reasons) operation.
**HTTP Request**
GET `api/commerce/orders/cancel/reasons`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Cart Pages (After)
Source: https://docs.kibocommerce.com/pages/cart-pages-after
This action manipulates the HTTP response after a Cart page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.cart.request.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Cart Pages (Before)
Source: https://docs.kibocommerce.com/pages/cart-pages-before
This action manipulates the HTTP request or response before a Cart page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.cart.request.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Cart Takeover
Source: https://docs.kibocommerce.com/pages/cart-takeover
The cart takeover feature enables customer service representatives (CSRs) to take over an online cart and make changes so that the cart has the shopper's desired products and options. For instance, a shopper may need help ordering several custom products with complex configurations. A CSR can take control of the shopper's cart, browse for products, select options, and add/remove them from the cart.
Learn about shopping cart and checkout workflows
See the Cart API documentation for programmatic access
This feature is supported for both single- and multi-ship tenants, but a CSR must be assigned to a role that has the Customer Update behavior.
## How to Use Cart Takeover
In order to view a shopper's cart, a new order must be made first. CSRs can do this for both anonymous and registered shoppers. However, keep in mind that viewing an anonymous user's cart pulls up an empty cart. For a logged-in user, viewing the cart pulls up the shopper's online cart.
The following example uses an eCommerce storefront. See the [Cart Takeover for Kibo Headless Storefronts section](#cart-takeover-for-kibo-headless-storefronts) for details on how the process differs for headless implementations.
1. Go to **Main** > **Demand** > **Orders**.
2. Click **Create New Order** in the top right. This opens the below page.
3. Select the customer from the **Customer Search** drop-down menu on the right.
4. Now that the order is created, click **View User's Cart** in the header.
5. This will open the cart page, where no items will be displayed initially. To add an item, first search for a keyword or use the drop-down list of products.
The cart will always display the CSR logged in as the shopper even though that is not the case. The CSR should not be confused or try to click Log Out.
6. Clicking on an item opens its details page. Select any options (if applicable) and click **Add to Cart**.
7. When all items have been added, click **Add Items to Order** in the top right to exit the takeover and allow the shopper to complete checkout on their own.
Do not click Checkout while doing a cart takeover, unless you intend to enter the customer's payment information yourself as an offline order.
## Cart Takeover for Kibo Headless Storefronts
[Headless integrations](/pages/getting-started "Headless Integrations") can use cart takeover with external storefronts. Admin users can either follow a link on the Customers page to access the storefront directly, or submit an offline order populated with items from the shopper's cart. External cart takeover is not supported for anonymous shoppers.
Contact [Kibo Support](https://help.kibocommerce.com/) to enable this feature.
### View the Kibo Headless Storefront
In addition to the offline order page as shown above for non-headless cases, headless integrations will also display **View User's Cart** buttons on the **Main** > **Customers** > **Customers** table and the customer details page. Clicking either of these buttons will prompt you to select a site before continuing to the external storefront to edit the cart there.
When viewing [a B2B account,](/pages/manage-b2b-accounts "Manage B2B Accounts") clicking any user in the table will redirect you to the above customer details page. From there, you can view the user's cart and perform a takeover using the same process as documented here.
### Create Order in Admin UI
If creating a new order in the Admin UI, any changes will not be reflected on the external storefront. This means that you will have to submit it as an offline order, instead of releasing it for the shopper to checkout on their own.
1. After creating a new order and selecting the customer, click **Populate Items from Cart** in the actions menu. This will add all items from the shopper's external cart to the order.
2. Click **Edit Details** to add/remove items, select a shipping method, or perform adjustments.
3. Click **Save** on the Edit Details modal when complete.
4. Enter the customer's payment information in the **Payments** tab.
5. Click **Submit Order** in the top right of the page.
# Cartonization
Source: https://docs.kibocommerce.com/pages/cartonization
Kibo Fulfillment supports Cartonization recommendations. Cartonization provides optimized packing recommendations for the items in the shipment using the available containers / boxes used for shipping. By leveraging intelligent 3D bin-packing algorithms, Kibo helps fulfillment centers reduce shipping costs, minimize packaging waste, and streamline packing.
## Configuration and Setup
To use Cartonization, you must enable the feature at the tenant level and configure your packaging specifications within the Location Group settings.
### Enable Cartonization
Cartonization must be enabled by Kibo in your tenant settings. Once enabled, you can choose to use Kibo's native Cartonization API or integrate with third-party cartonization providers, based on your business needs. Submit a request to [Kibo Support](https://help.kibocommerce.com/) if you want to use this feature.
Cartonization is enabled using the tenant attribute `"fulfillment.cartonization.enabled = true"`. In addition, a Cartonization Type setting must be configured to determine whether the tenant uses Kibo's native in-house Cartonization API or integrates with a third-party provider. To enable Kibo's native in-house Cartonization API with an optimization strategy based on total volume, set the tenant attribute: `"fulfillment.cartonization.type = TOTAL_VOLUME"` .
### Configure Box Management
You must define the physical boxes available at your fulfillment centers so the algorithm knows what containers to recommend.
1. Navigate to Main > Orders > Location Groups
2. Select the desired Location Group.
3. Scroll to the Box Management section.
4. Click Add New Box Type or edit an existing one:
* Box Type Name: Give the box a recognizable name (e.g., "Medium Shipping Box").
* External Dimensions: Enter the Length, Width, and Height.
* Max Box Weight Limit: Enter the maximum weight capacity the box can support (e.g., 50 lbs).
5. Save
The system assumes infinite availability for configured box types. Kibo does not track real-time inventory levels for packaging materials.
### Location Group Fulfillment Settings
Ensure your fulfillment workflow is compatible with Cartonization.
1. In the Location Group settings, navigate to Other Settings.
2. Maximum Packing Slips: Set the limit for how many packages can be generated for a single shipment (default is 10).
3. Auto generate packing list: Enable, if you want to use a single packing slip for shipments.
Disable this setting, if you want to use multiple packing slips for shipments.
### Product Data Preparation
Cartonization requires accurate product dimensions to function. If dimensions are missing, the system will fall back to manual packing.
1. Navigate to Catalog > Products.
2. Under the Shipping section for each product, ensure the following are populated:
* Length, Width, and Height
* Weight
3. Ship by Itself: If this flag is enabled on an item, the cartonization engine will automatically isolate it into its own packing slip and will not attempt to pack it with other items.
## How Cartonization Works
Once Cartonization is enabled, the package recommendation engine becomes an integrated step within the standard fulfillment workflow. Warehouse staff interact with these suggestions directly in the Fulfiller interface to ensure optimal packing.
### Fulfillment Step: Print Packing Slip
For ship to Home (STH), Delivery and Transfer shipments, the option to use Cartonization appears during the Print Packing Slip step.
#### Get Packing Recommendation
1. Navigate to the Print Packing Slip step after validating stock.
2. Click on Get Packing Recommendations Button.
3. The system analyzes:
* Item dimensions and quantities
* Available box types for the fulfillment location
4. The system returns a cartonization recommendation showing:
* Recommended box type(s) with dimensions
* Specific items and quantities to pack in each box
#### Review Recommendations
* Review which items and quantities are assigned to each box
* The system automatically updates the required number of packing slips
* Each packing slip corresponds to one recommended box.
* If acceptable, click Save, then click Proceed to Prepare for shipment step.
#### Manual Override/Reject Recommendations
Warehouse staff can override cartonization recommendations at any time:
1. Click Reject Packing Recommendations button.
2. The system clears the cartonization results.
3. The shipment reverts to a fully manual packing slip and box selection process.
### Fulfillment Step: Prepare for Shipment
During the Prepare for Shipment step, cartonization data is used to finalize package details for label generation. Recommended box dimensions and weight are automatically pre-populated on every packing Slip.
To change the box type at this stage, users must return to the **Print Packing Slip** step and perform a **Manual Override**.
#### 3D Visual Instructions
If proceeding with the recommendation, users can click View Box Packing button to open a modal displaying:
* 3D visualization of item placement and quantities
* Box dimensions
* Complete item list with quantities
* Volume utilization percentage
* Overall package weight
#### Finalize Shipment
Once packaging details are confirmed:
* Generate shipping labels as usual
* Tracking numbers are created per box (for multi-box shipments)
# Catalog and Site Structure Settings
Source: https://docs.kibocommerce.com/pages/catalog-and-site-structure-settings
Catalogs and sites are fundamental structural elements of your Kibo Composable Commerce Platform tenant. Even for OMS-only implementations, a catalog is required to perform customer service actions such as adding line items to an order or applying discounts. While catalogs are easily managed in the user interface as shown here, there are a number of [Catalog APIs](/api-overviews/openapi_catalog_admin_overview) that can be used to interface with different aspects of the catalog.
## Catalogs and Sites
Refer to the following table for more information about master catalogs, catalogs, and sites:
| Element | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Master catalog | A master catalog is a set of products that multiple catalogs can inherit from, with or without overridden properties. You can set global product properties that are shared across all associated catalogs at the master catalog level. |
| Catalog | A catalog is a subset of products tied to a specific site. You can override global product properties at the catalog level, such as price and description. |
| Sites | Sites are places from which you conduct transactions. You must tie each site to one and only one catalog. |
For example, you have multiple catalogs—one for each of your sites—and you have one master catalog with which each catalog is associated. This allows you to easily share products across all your catalogs. Within each catalog, you can override certain properties of a product, such as price and description.
## System Structure Settings
Go to **System** > **Structure** in the Admin UI to find three sections.
* **Sites:** Lists your sites that are currently tied to a catalog.
* **Catalogs:** Lists your master catalogs and catalogs.
* **Channels:** Lists the channels your sites are associated with, such as online, kiosk, brick and mortar, etc.
Refer to [Channel Settings](/pages/channel-settings) for more information about channel settings.
Your master catalogs, catalogs, and sites are all named after the tenant as it was named in Dev Center during provisioning. You can edit the names by expanding the actions menu and selecting **Rename**.
Do not delete a master catalog from your tenant if you only have one master catalog. If you need to delete a master catalog, ensure that you have an additional master catalog before deleting the master catalog. If you delete the only master catalog in your tenant, the tenant will no longer function properly and you will need to have an entire new tenant provisioned. Doing so will result in this error:
## Create Catalogs and Sites
You can create additional catalogs within your master catalog, or additional master catalogs with as many catalogs as you like. For each catalog, you must create a corresponding site.
### Create Master Catalogs
To create master catalogs:
1. Go to **System** > **Structure** > **Catalogs**.
2. Click **Create New Catalog**.
3. From the **Catalog Type** drop-down menu, choose **Master Catalog**.
4. Enter a **Master Catalog Name**.
5. Select a **Default Locale Code**.
6. Select all additional **Supported Locales** that child catalogs will be able to localize product data for.
7. Select a **Currency Code**.
8. Click **Save**.
### Create a Child Catalog
To create a child catalog:
1. Go to **System** > **Structure** > **Catalogs**.
2. Click **Create New Catalog**.
3. From the **Catalog Type** drop-down menu, choose **Catalog**.
4. Select a **Master Catalog** for the catalog to inherit.
5. Enter a **Catalog Name**.
6. Select a **Default** **Locale Code**. This must be one of the locales supported by the master catalog.
7. Select a **Currency Code**.
8. Click **Save**.
If you select a **Currency Code** that differs from the master catalog's currency, you must also set a localized price for every product variation in that currency. Configurable products whose variations are not priced in the child catalog's currency will not appear on the storefront. Refer to [Multi-Currency Catalogs](/pages/multi-currency-catalogs "Multi-Currency Catalogs") for the required steps.
### Create a Site
To create a site:
1. Go to **System** > **Structure** > **Sites**.
2. Click **Create New Site**.
3. Enter a **Site Name**.\
You use this value to identify the site in the context switcher throughout Admin.
4. Choose whether or not the site represents a storefront that online shoppers can visit.
5. Choose a **Catalog** to associate with the site.
6. Choose a **Country Code**.
7. Select a **Locale Code**. This must be one of the locales supported by the catalog.
8. Click **Save**.
Although you can only associate one catalog with any given site, you can associate as many sites as you like with any given catalog. In many modules in Admin, there's a context switcher in the top left that allows you to select which site you want to view or edit.
After creating a new site, it may take up to 30 minutes before the cache refreshes and the site settings are available for configuration.
# Catalog and Site Structure Settings
Source: https://docs.kibocommerce.com/pages/catalog-and-site-structure-settings-2
Catalogs and sites are fundamental structural elements of your Kibo Composable Commerce Platform tenant. Even for OMS-only implementations, a catalog is required to perform customer service actions such as adding line items to an order or applying discounts. While catalogs are easily managed in the user interface as shown here, there are a number of [Catalog APIs](/api-overviews/openapi_catalog_admin_overview) that can be used to interface with different aspects of the catalog.
## Catalogs and Sites
Refer to the following table for more information about master catalogs, catalogs, and sites:
| Element | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Master catalog | A master catalog is a set of products that multiple catalogs can inherit from, with or without overridden properties. You can set global product properties that are shared across all associated catalogs at the master catalog level. |
| Catalog | A catalog is a subset of products tied to a specific site. You can override global product properties at the catalog level, such as price and description. |
| Sites | Sites are places from which you conduct transactions. You must tie each site to one and only one catalog. |
For example, you have multiple catalogs—one for each of your sites—and you have one master catalog with which each catalog is associated. This allows you to easily share products across all your catalogs. Within each catalog, you can override certain properties of a product, such as price and description.
## System Structure Settings
Go to **System** > **Structure** in the Admin UI to find three sections.
* **Sites:** Lists your sites that are currently tied to a catalog.
* **Catalogs:** Lists your master catalogs and catalogs.
* **Channels:** Lists the channels your sites are associated with, such as online, kiosk, brick and mortar, etc.
Refer to [Channel Settings](/pages/channel-settings) for more information about channel settings.
Your master catalogs, catalogs, and sites are all named after the tenant as it was named in Dev Center during provisioning. You can edit the names by expanding the actions menu and selecting **Rename**.
Do not delete a master catalog from your tenant if you only have one master catalog. If you need to delete a master catalog, ensure that you have an additional master catalog before deleting the master catalog. If you delete the only master catalog in your tenant, the tenant will no longer function properly and you will need to have an entire new tenant provisioned. Doing so will result in this error:
## Create Catalogs and Sites
You can create additional catalogs within your master catalog, or additional master catalogs with as many catalogs as you like. For each catalog, you must create a corresponding site.
### Create Master Catalogs
To create master catalogs:
1. Go to **System** > **Structure** > **Catalogs**.
2. Click **Create New Catalog**.
3. From the **Catalog Type** drop-down menu, choose **Master Catalog**.
4. Enter a **Master Catalog Name**.
5. Select a **Default Locale Code**.
6. Select all additional **Supported Locales** that child catalogs will be able to localize product data for.
7. Select a **Currency Code**.
8. Click **Save**.
### Create a Child Catalog
To create a child catalog:
1. Go to **System** > **Structure** > **Catalogs**.
2. Click **Create New Catalog**.
3. From the **Catalog Type** drop-down menu, choose **Catalog**.
4. Select a **Master Catalog** for the catalog to inherit.
5. Enter a **Catalog Name**.
6. Select a **Default** **Locale Code**. This must be one of the locales supported by the master catalog.
7. Select a **Currency Code**.
8. Click **Save**.
If you select a **Currency Code** that differs from the master catalog's currency, you must also set a localized price for every product variation in that currency. Configurable products whose variations are not priced in the child catalog's currency will not appear on the storefront. Refer to [Multi-Currency Catalogs](/pages/multi-currency-catalogs "Multi-Currency Catalogs") for the required steps.
### Create a Site
To create a site:
1. Go to **System** > **Structure** > **Sites**.
2. Click **Create New Site**.
3. Enter a **Site Name**.\
You use this value to identify the site in the context switcher throughout Admin.
4. Choose whether or not the site represents a storefront that online shoppers can visit.
5. Choose a **Catalog** to associate with the site.
6. Choose a **Country Code**.
7. Select a **Locale Code**. This must be one of the locales supported by the catalog.
8. Click **Save**.
Although you can only associate one catalog with any given site, you can associate as many sites as you like with any given catalog. In many modules in Admin, there's a context switcher in the top left that allows you to select which site you want to view or edit.
After creating a new site, it may take up to 30 minutes before the cache refreshes and the site settings are available for configuration.
# Catalog Structure
Source: https://docs.kibocommerce.com/pages/catalog-structure
Catalogs are at the core of your business: they list all the products you offer to shoppers and store details about every one of your products such as: name, price, product code, images, etc.
Learn about product catalog architecture and management
See how to create a new catalog in Kibo
## Types of Catalogs
There are two types of catalogs:
* **Master Catalogs:** Specific to your tenant and contain all the products in your child catalogs that belong to them, which enables you to share products across all child catalogs.
* **Catalogs:** Specific to each of your sites or storefronts and only contain the products in them that you wish to sell in their associated storefronts.
## Catalog Example
Imagine that your business includes a brick and mortar store in Austin, a kiosk in San Antonio, and a website, and you sell the following products:
| Product | Location Available |
| ---------- | ------------------------ |
| Shirt | Austin store and website |
| Pants | Austin store and website |
| Skirts | Austin store and website |
| Sunglasses | San Antonio kiosk only |
| Bags | Austin store and website |
Given this situation, you would configure your catalogs in the following way:
| Catalog Name | Catalog Type | Description |
| ------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Master Apparel Catalog | Master catalog | Includes all of your products, including all the shirts, pants, skirts, sunglasses, and bags you sell. |
| Austin Store Catalog | Catalog | Includes a subset of all your products. You only sell shirts, skirts, pants, and bags in your Austin store. |
| San Antonio Kiosk Catalog | Catalog | Includes a limited subset of the products that you sell at your kiosk. You only sell sunglasses at the kiosk. |
| Website Catalog | Catalog | Includes a subset of all products that you sell online. You only sell shirts, pants, skirts, and bags on your website. |
See the Admin Catalog API documentation for programmatic access
# Catalogs Template
Source: https://docs.kibocommerce.com/pages/catalogs-template
The Catalogs template for the import/export tools is the largest of the import/export template files, and is likely the one you will use the most. Together, the sheets of the Catalogs template represent your entire catalog structure for all the sites on your tenant. You can use this template to add or update master catalogs, sub-catalogs, product types, product attributes and options, images, inventory, and discounts. If you are preparing your initial data import for a new tenant, import contacts *before* you import products.
As you work with this file, you will enter information about a single product across multiple sheets. A a combination of IDs, codes, names, and catalog information are used to make the proper data connections. For example, most sheets require a ProductCode to bind the data the sheet contains to the correct product.
## Access the Tools
With the [Import-Export Application](/pages/import-and-export-tools) installed and enabled, go to **Main** > **Sell** > **Import/Export** in the Admin.
## Supported File Formats
* **CSV (.csv):** Each sheet is a separate CSV file. For both imports and exports, sheets are compressed into a ZIP file. When importing, the ZIP file can have any file name but each individual CSV file name must match the export file name and the sheet. You can remove CSV files for data you do not want to import.
These CSV files should not be opened in Excel, as that may cause errors with their formatting. Instead, use a different CSV editing program to make changes to the data.
You should only use the default Windows zipper to zip the files, as using different software may cause errors. You can upload multiple files at once as long as they all are zipped.
## Template Key
For each sheet, we define each column and describe valid values for the column. If you have questions or concerns specific to your data, please contact your integration partner or [Kibo Support](https://help.kibocommerce.com/).
| | Information Provided for Each Sheet of the Template |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Corresponding REST API Resource | Every column in a sheet corresponds to a property in the REST API. For each sheet, we provide a link to any API resources that contain properties in the sheet. |
| Column Name | The name of the column in the sheet. |
| Description | A description of the data a column contains. |
| Valid Values | Lists valid values for the column. |
## Sheets
### Attributes
Corresponding REST API Resource: [commerce/catalog/admin/attributedefinition/attributes](/api-overviews/openapi_catalog_admin_overview)
Required With: [AttributeValues](#attributevalues)
Product attributes are the variable properties that define a product. Attributes can be options (such as size or color), properties (such as the brand of the product), or extras (such as custom printing or warranties). Because many products share common attributes, you define general attributes before you apply them to specific products.
| Column Name | Description | Valid Values |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AttributeCode | The unique code that identifies the attribute. Once an attribute is created, you cannot change its AttributeCode. | Any string. The string must be unique to a single attribute in the master catalog. |
| MasterCatalogName | The name of the master catalog that includes the attribute. All attributes are defined on the master catalog level, and populate down to sub-catalogs within the master catalog. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| Namespace | The namespace to which the attribute belongs. All attributes you create through Admin have a namespace of `Tenant`. Attributes that custom applications create through the API might have a custom namespace. | Any string that is a valid, registered namespace. If empty, the default is `Tenant`.
**Note:** To avoid overwriting attributes created by custom applications, the Import/Export Tool only processes attributes with a namespace of `Tenant`. If you want to edit attributes in another namespace, you must use the API. |
| SearchableInAdmin | Specifies whether the attribute Value (specified on the [AttributeValues](#attributevalues) sheet) is included in product search results in Admin. If an attribute has multiple values, this setting applies to all the values. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| SearchableInStorefront | Specifies whether the attribute (specified on the [AttributeValues](#attributevalues) sheet) is included in product search results on the public storefront. If an attribute has multiple values, this setting applies to all the values. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| SearchDisplayValue | Specifies whether the display value or the canonical value of an attribute with a DataType of `String` is indexed for searching. If `Yes`, the system indexes the display value. If `No`, it indexes the canonical value. The default is `No`. | A Boolean value, specified as `Yes` or `No`.
This value is ignored if the DataType of the attribute is anything other than `String`. |
| AttributeName | The name of the attribute as it appears to customers. For example: `Size`
This value corresponds to the **Attribute Label** in Admin. If you are creating a new attribute, this value is used for the **Administration Name** that Admin users see. | Any string. The string must be unique to a single attribute in the master catalog. |
| DataType | The type of data the user must select or enter for the attribute. | A string matching one of the following: `String`, `Number`, `Bool`, `Product`
Valid data types depend on the InputType. For example, an InputType of `YesNo` must have a DataType of `Bool`.
`Product` is only valid for an InputType of `List`. |
| Description | A text description for the attribute. | Any string. |
| InputType | The format in which the attribute is displayed to customers. The best InputType to use often depends on whether the attribute is a Property, an Option, or an Extra. For example, a selectable Option, such as size or color, must be a `List`. An Extra, such as a monogram or custom print, is typically displayed as a `TextBox` or `TextArea`. | A string matching one of the following: `YesNo`, `Date`, `DateTime`, `List`, `TextBox`, `TextArea` |
| IsExtra | Specifies whether the attribute type is Extra. An Extra is an add-on configuration that the customer can select or configure, such as a monogram or warranty. | A Boolean value, specified as `Yes` or `No`. If IsExtra is `Yes`, IsOption and IsProperty must be `No`. |
| IsOption | Specifies whether the attribute type is Option. An Option is a product detail that a customer can select, such as size or color. Options generate product variations, which have unique product codes. | A Boolean value, specified as `Yes` or `No`. If IsOption is `Yes`, IsExtra and IsProperty must be `No`.
If IsOption is `Yes`, InputType must be `List`. |
| IsProperty | Specifies whether the attribute type is Property. A Property is a product detail that a customer cannot configure, such as brand or material. | A Boolean value, specified as `Yes` or `No`. If IsProperty is `Yes`, IsExtra and IsOption must be `No`. |
| AvailableForOrderRouting | Specifies whether the attribute is enabled for use in routing filters through [Extensible Order Routing](/pages/extensible-order-routing). | A Boolean value, specified as `Yes` or `No`. |
| \[ Locale ] | This sheet can include a series of columns for all supported locales, such as en-US and fr-CA. The values within this column will be the localized version of the attribute. | Any string or number. |
### AttributeValues
Corresponding REST API Resource: [commerce/catalog/admin/attributedefinition/attributes](/api-overviews/openapi_catalog_admin_overview)
Required With: [Attributes](#attributes)
Attribute values define what customers see for a given attribute. A single attribute can have multiple values. For example, if an attribute has an InputType of `List` in the [Attributes](#attributes) sheet, every item in the list is a value of the attribute. Attribute values are mapped to attributes by the AttributeCode.
| Column Name | Description | Valid Values |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AttributeCode | A unique code that identifies the attribute to which the attribute value belongs. Once an attribute is created, you cannot change its AttributeCode. | Any string. The string must be unique to a single attribute in the master catalog. |
| DataType | The type of data the user must select or enter for the attribute value. | A string matching one of the following: `String`, `Number` |
| DisplayOrder | The order in which attribute values display within a product and in Admin. | Any unique number in a sequential order. |
| MasterCatalogName | The name of the master catalog that includes the attribute with which the value is associated. All attributes are defined on the master catalog level, and populate down to sub-catalogs within the master catalog. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| Name | The name of the attribute value as it is displayed in Admin | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to escape spaces or characters. |
| Label | The description for the value in US English. This string defines how the Value appears to customers on the storefront and to users in Admin.
**Note:** This column only appears when you have more than one language associated with your tenant. | Any string. |
| Namespace | The namespace to which the attribute values belongs. All attributes you create through Admin have a namespace of `Tenant`. Attributes that custom applications create through the API might have a custom namespace. | Any string that is a valid, registered namespace. If empty, the default is `Tenant`.
**Note:** To avoid overwriting attributes created by custom applications, the Import/Export Tool only processes attributes with a namespace of `Tenant`. If you want to edit attributes in another namespace, you must use the API. |
| Value | The actual value for the attribute value. This is not the string that a customer sees, but rather the value as it appears in the **Value** column of the **Values** table for the attribute in `Admin`. This value must be unique within the vocabulary for a single attribute and match the DataType of the attribute. If an attribute has multiple values, each Value is specified on a separate row in this sheet. | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to escape spaces or characters. |
| \[ Locale ] | This sheet can include a series of columns for all supported locales, such as en-US and fr-CA. The values within this column will be the localized value of the attribute. | Any string or number. |
### ProductContent
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
This template contains localized product and SEO content for locales other than the default master catalog locale. For more information about this catalog structure, see the [Multi-Locale Catalogs documentation](/pages/multi-locale-catalogs "Multi-Locale Catalogs").
| Column Name | Description | Valid Values |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product. Products are defined on the master catalog level. After you define a product in the master catalog, you can use the [ProductCatalog](#productcatalog) sheet to add it to sub-catalogs. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the product. | Any number that is unique among all product codes in the master catalog. Character limit: 3-30. |
| ContentLocaleCode | The locale code that you are localizing this content into. | An ISO locale code. for example, `en-US`. |
| ProductName | The name the customer sees for the product, in the language specified by the ContentLocaleCode. | Any string. |
| ProductShortDescription | A short (260 characters) description for the product. This value is typically used when the product is displayed in a list of search results. | Any string. Character limit: 260. HTML tags are supported, and are not counted in the description character limit. |
| ContentFullProductDescription | The full description to display on the details page for the product. | Any string. HTML tags are supported. |
| SEOMetaTagTitle | Maps to the HTML meta title tag. While most search engines place little value on this tag, most themes inject the value of the meta title tag into the HTML title tag.
The HTML title tag is used by search engines and browsers to display the title of the page, and is critical to SEO. Search engines place very high importance on the correlation between a page's title tag and its content. | Any string. |
| SEOMetaTagDescription | Maps to the HTML meta description tag, which is used by search engines to summarize the content of the page. | Any string. |
| SEOMetaTagKeywords | Maps to the HTML meta keywords tag, which is used to tell search engines what the page is about. From an SEO-perspective, search engines place little value on this tag, but the search implementation uses these keywords to help construct search results for pages on your storefront. | Any string. |
| SEOFriendlyURL | The default URL structure for products is `yourSite.com/{slug}/p/{productCode}` and for categories is `yourSite.com/{slug}/c/{categoryId}`. The slug (or SEO-friendly URL) gives you the ability to add a meaningful component to the URL structure in order to boost search results. | Any string. |
### ProductTypes
Corresponding REST API Resource: [commerce/catalog/admin/attributedefinition/producttypes](/api-overviews/openapi_catalog_admin_overview)
Required With: [ProductTypeAttributes](#producttypeattributes), [ProductTypeAttributeValues](#producttypeattributevalues)
A product type is a template of settings and attributes you create for a specific set of products. Every product in your catalog has a single product type associated with it. The ProductTypes sheet simply specifies the usage type(s) and master catalog for the product type. You specify details for product types on the [ProductTypeAttributes](#producttypeattributes) and [ProductTypeAttributeValues](#producttypeattributevalues) sheets.
A single product type can support multiple usage types. For example, a shirt can be Configurable and a Component of a larger Bundle.
| Column Name | Description | Valid Values |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product type. All product types are defined on the master catalog level, and populate down to sub-catalogs within the master catalog. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductType | The name of the product type. This name appears whenever a user is working with product types in Admin, so it should be meaningful and human-readable. | Any string. |
| Bundle | Specifies whether the product type supports the Bundle usage type. Bundles are collections of products sold as a single entity. For example, a suit Bundle can contain a shirt, pants, and a jacket. | A Boolean value, specified as `Yes` or `No`. |
| Component | Specifies whether the product type supports the Component usage type. Components can belong to Bundles. For example, a shirt can be a Component of a suit Bundle. | A Boolean value, specified as `Yes` or `No`. |
| Configurable | Specifies whether the product type supports the Configurable usage type. Configurable products allow the user to specify a product variation based on product options. For example, a shirt in size Small. | A Boolean value, specified as `Yes` or `No`. |
| GoodsType | The type of goods the product type contains. This value distinguishes between physical items, digital items, and digital store credits (such as gift cards). The default is `Physical`. | A string matching one of the following: `Physical`, `Digital`, `DigitalCredit` |
| Standard | Specifies whether the product type supports the Standard usage type. Standard products are not configurable and do not have variations. | A Boolean value, specified as `Yes` or `No`. |
### ProductTypeAttributes
Corresponding REST API Resource: [commerce/catalog/admin/attributedefinition/producttypes](/api-overviews/openapi_catalog_admin_overview)
Required With: [ProductTypes](#producttypes), [ProductTypeAttributeValues](#producttypeattributevalues-8)
Attributes are linked to products at the product type level. The ProductTypeAttributes sheet ties the attributes you define on the [Attributes](#attributes) and [AttributeValues](#attributevalues) sheets to the product types you define in the [ProductTypes](#producttypes) sheet. You must define your attributes, either on the Attributes sheet or from the UI itself, before you can connect them to product types. Multiple product types can share the same attributes.
| Column Name | Description | Valid Values |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AttributeCode | The unique code that identifies the attribute. | Any string. This value must match the AttributeCode value on the [Attributes](#attributes) sheet and be unique to a single attribute in the master catalog. |
| MasterCatalogName | The name of the master catalog that includes the product type. All product types are defined on the master catalog level, and populate down to sub-catalogs within the master catalog. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductType | The name of the product type. | Any string. This value must match the ProductType value on the [ProductTypes](#producttypes) sheet. |
| IsHiddenProperty | Specifies whether the attribute is hidden from customers on the storefront. This value only applies if Type is `Property`. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| IsMultiValueProperty | Specifies whether the attribute can have more than one possible value for a single product. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| IsRequiredByAdmin | Specifies whether the attribute is required on products of this product type in Admin. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| Order | Specifies the order in which the attribute appears in a list of all attributes on the product type. | Any integer value, such as `1` or `3`. |
| Type | The type of the attribute. | A string matching one of the following: `Property`, `Option`, `Extra`
The attribute type you specify must be enabled for the attribute. For example, if you set this Type to `Property`, the IsProperty column on the [Attributes](#attributes) sheet must have a value of `Yes`. |
### ProductTypeAttributeValues
Corresponding REST API Resource: [commerce/catalog/admin/attributedefinition/producttypes](/api-overviews/openapi_catalog_admin_overview)
Required With: [ProductTypes](#producttypes), [ProductTypeAttributes](#producttypeattributes)
The attribute values you specify for a given product type define what users and customers see for that product type. These values might differ from the values defined on the [AttributeValues](#attributevalues) sheet. For example, your store might include a line of shirts that are only available in sizes Small, Medium, and Large. However, your `Size` attribute from the AttributeValues sheet has possible values of `XS`, `S`, `M`, `L`, and `XL`. You can still use your `Size` attribute for the shirts by giving them their own ProductType and only enabling the three relevant values for `Size` on this sheet.
| Column Name | Description | Valid Values |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AttributeCode | The unique code that identifies the attribute. This value must match the AttributeCode value on the [Attributes](#attributes) and [ProductTypeAttributes](#producttypeattributes) sheets. | Any string. The string must be unique to a single attribute in the master catalog. |
| MasterCatalogName | The name of the master catalog that includes the attribute. This value must match the MasterCatalogName value on the [ProductTypes](#producttypes) and [ProductTypeAttributes](#producttypeattributes) sheets. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| Order | Determines the order in which attributes are displayed on a product type. For instance, an attribute with three values should order them as 0, 1, and 2. | Any integer. |
| ProductType | The name of the product type. This value must match the ProductType value on the [ProductTypes](#producttypes) and [ProductTypeAttributes](#producttypeattributes) sheets. | Any string. |
| Type | The type of the attribute. | A string matching one of the following: `Property`, `Option`, `Extra`
The attribute type you specify must be enabled for the attribute. For example, if you set this Type to `Property`, the IsProperty column on the [Attributes](#attributes) sheet must have a value of `Yes`. |
| VocabularyValue | The value the customer sees for the attribute, in the language specified by VocabularyValueLocaleCode. This value does not have to match a description from the AttributeValues sheet, but any new values you define here will only apply to this ProductType. | Any string. If empty, this value is inherited from values specified on the AttributeCode in the master catalog. You might see an entry on export of "Inherited from Base. Do not add values here." |
### CategoriesContent
Corresponding REST API Resource: [commerce/catalog/admin/categories](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
This template contains localized category and SEO content for locales other than the default master catalog locale. For more information about this catalog structure, see the [Multi-Locale Catalogs documentation](/pages/multi-locale-catalogs "Multi-Locale Catalogs").
| Column Name | Description | Valid Values |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| CatalogName | The name of the catalog this category is mapped to. You can define catalogs on the [ProductCatalog](#productcatalog) sheet. | A string matching any valid catalog name. |
| CategoryCode | The unique, alphanumeric identifier for the category. You use the CategoryCode to map categories to catalogs, discounts, and other categories.
**Note:** This code does not have to map to the ID that the system generates for categories created in Admin. This code must simply be unique to the category and must match across all sheets that refer to the category. | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to separate string phrases. |
| ContentLocaleCode | The locale code that you are localizing this content into. | An ISO locale code. for example, `en-US`. |
| CategoryName | The name of the category, in the language specified by the ContentLocaleCode. | Any string. |
| MetaTagTitle | Maps to the HTML meta title tag. While most search engines place little value on this tag, most themes inject the value of the meta title tag into the HTML title tag.
The HTML title tag is used by search engines and browsers to display the title of the page, and is critical to SEO. Search engines place very high importance on the correlation between a page's title tag and its content. | Any string. |
| MetaTagDescription | Maps to the HTML meta description tag, which is used by search engines to summarize the content of the page. | Any string. |
| PageTitle | By default, this value is not used by the system. However, your theme developer has access to this value through a Hypr variable, so with minor theme changes, you can expose a different page title on your storefront than the title you supply for the meta title. | Any string. |
| CategoryDescription | The description of the category. | Any string. |
| MetaTagKeyWords | Maps to the HTML meta keywords tag, which is used to tell search engines what the page is about. From an SEO-perspective, search engines place little value on this tag, but the search implementation uses these keywords to help construct search results for pages on your storefront. | Any string. |
| SEOUrl | The default URL structure for products is `yourSite.com/{slug}/p/{productCode}` and for categories is `yourSite.com/{slug}/c/{categoryId}`. The slug (or SEO-friendly URL) gives you the ability to add a meaningful component to the URL structure in order to boost search results. | Any string. |
### Categories
Corresponding REST API Resource: [commerce/catalog/admin/categories](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
Product categories group similar items so that you can display them together in sections on your site. Categories help you create faceted navigation for your customers. For example, Women's Apparel can be its own category as well as a parent category of Shirts, Pants, and Dresses. Categories map to catalogs, and you can define them on the master catalog or only on a specific sub-catalog. A single product can belong to multiple categories.
This template contains category content for the default master catalog locale. To define localized category content used for other locales in multi-locale catalog setups, use the [CategoriesContent](#categoriescontent) sheet.
| Column Name | Description | Valid Values |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CatalogName | The name of the catalog this category is mapped to. You can define catalogs on the [ProductCatalog](#productcatalog) sheet. | A string matching any valid catalog name. |
| CategoryCode | The unique, alphanumeric identifier for the category. You use the CategoryCode to map categories to catalogs, discounts, and other categories.
**Note:** This code does not have to map to the ID that the system generates for categories created in Admin. This code must simply be unique to the category and must match across all sheets that refer to the category. | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to separate string phrases. |
| CategoryDescription | The description of the category as it appears in Admin. Depending on your theme, you can also make this description visible to customers on your storefront. | Any string. |
| CategoryId | The unique, numeric identifier for the category. | Any number. This value must be unique among all categories on your site. |
| CategoryName | The name of the category. If IsDisplayed is `Yes`, this is the name that appears to customers on the storefront. | Any string. |
| CategoryType | The type of the category. | A string matching one of the following: `Static`, `DynamicPreComputed`, `DynamicRealTime`
**Note:** You cannot change the CategoryType of an existing category. |
| Expression | The expression that controls the product membership of the dynamic category. This column is required only when CategoryType is `DynamicPreComputed` or `DynamicRealTime`.
If you intend to import files with minimal columns to make small changes (such as disabling a category or changing its parents), then please contact [Kibo Support](https://help.kibocommerce.com/) to have your tenant configurations adjusted for this behavior. Otherwise, expressions will always be required in dynamic category import files. | A string that is a valid [dynamic category expression](/pages/dynamic-categories-api-overview). |
| IsDisplayed | Specifies whether the category is visible to customers on the storefront. | A Boolean value, specified as `Yes` or `No`. |
| IsActive | Species whether or not the category is active. | A Boolean value, specified as `Yes` or `No`. |
| MetaTagDescription | Maps to the HTML meta description tag, which is used by search engines to summarize the content of the page. | Any string. |
| MetaTagKeyWords | Maps to the HTML meta keywords tag, which is used to tell search engines what the page is about. From an SEO-perspective, search engines place little value on this tag, but the search implementation uses these keywords to help construct search results for pages on your storefront. | Any string. |
| MetaTagTitle | Maps to the HTML meta title tag. While most search engines place little value on this tag, most themes inject the value of the meta title tag into the HTML title tag.
The HTML title tag is used by search engines and browsers to display the title of the page, and is critical to SEO. Search engines place very high importance on the correlation between a page's title tag and its content. | Any string. |
| PageTitle | By default, this value is not used by the system. However, your theme developer has access to this value through a Hypr variable, so with minor theme changes, you can expose a different page title on your storefront than the title you supply for the meta title. | Any string. |
| ParentCategoryCode | The category code that identifies the parent category of this category. If the category has multiple parents, create a new row to define each parent/child relationship, and ensure that all other values match between the rows. | A number that matches a valid category code. |
| SEOUrl | The default URL structure for products is `yourSite.com/{slug}/p/{productCode}` and for categories is `yourSite.com/{slug}/c/{categoryId}`. The slug (or SEO-friendly URL) gives you the ability to add a meaningful component to the URL structure in order to boost search results. | Any string. |
| Sequence | The order in which categories display on the storefront. This helps you order your top-level categories in navigation, and order how child categories display within a parent category. | Any number. Must be unique for categories on the same node. |
### CategoryImages
Corresponding REST API Resource: [commerce/catalog/admin/categories](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
Category images are the images associated to a product category. Images display with the category on the storefront depending on how you set up your theme. Each image includes a name, label, alt text, and other properties.
| Column Name | Description | Valid Values |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| CatalogName | The name of the catalog of the category the image is mapped to. You can define catalogs on the [ProductCatalog](#productcatalog) sheet. | A string matching any valid catalog name. |
| CategoryCode | The unique, alphanumeric identifier for the category the image is mapped to. You use the CategoryCode to map categories to catalogs, discounts, and other categories.
**Note:** This code does not have to map to the ID that the system generates for categories created in Admin. This code must simply be unique to the category and must match across all sheets that refer to the category. | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to separate string phrases. |
| AltText | The text to display when a shopper hovers over an image or when an image does not render. This field is also useful for including SEO keywords. | Any string. |
| ImageLabel | The title of an image that can display on your storefront, depending on your theme. | Any string. |
| ImageName | The name of an image as it displays in Admin (for example, in File Manager). This name is not exposed to shoppers. | Any string. |
| LocaleCode | The locale code used to decide the language in which to display content. | An ISO locale code. for example, `en-US`. |
| Order | A number that determines what order images display in if they are assigned to the same category. | Any number. Must be unique for images in the same category. |
### Products
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [ProductCatalog](#productcatalog), [ProductOptions](#productoptions), [ProductExtras](#productextras), [ProductBundles](#productbundles-14), [ProductImages](#productextras), [ProductPropertyLocale](#productpropertylocale), [ProductOptionsLocale](#productoptionslocale), [ProductContent](#productcontent)
Once you have created attributes, product types, and categories, you can add products to your store. Do not try to add products to your store before building out the catalog infrastructure that the previous tabs describe. Your products will be missing required data and the import will not work. However, once your catalog infrastructure is set, you can fill out just the product-related sheets when you are adding or updating product data.
This template contains product content for the default master catalog locale. To define localized product and SEO content used for other locales in multi-locale catalog setups, use the [ProductContent](#productcontent) sheet.
When you export Products, the Import-Export Application provides a **Filters** pane that allows you to filter which products to export based on catalog, product name, product type, price range, and other properties.
| Column Name | Description | Valid Values |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| MasterCatalogName | The name of the master catalog that includes the product. Products are defined on the master catalog level. After you define a product in the master catalog, you can use the [ProductCatalog](#productcatalog) sheet to add it to sub-catalogs. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the product. | Any number that is unique among all product codes in the master catalog. Character limit: 3-30. |
| CategoryCodes | A list of categories the product belongs to, specified using the relevant category codes. | Any list of strings composed of valid category codes, separated by a comma. For example, `CategoryA, Category B, Category C`. |
| ContentFullProductDescription | The full description to display on the details page for the product. | Any string. HTML tags are supported. |
| Cost | The cost of the product to the merchant. | Any decimal value. |
| DistributorPartNumber | The distributor's part number for the product. | Any string. |
| FulfillmentTypes | The fulfillment types supported for shipping the product to customers. | A string matching one of the following: `DirectShip`, `InStorePickup`, `Digital`
If multiple fulfillment types are supported, use an ampersand (&) to include additional types. For example: `DirectShip & InStorePickup` |
| IsTaxable | Specifies whether the product is subject to taxation. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| ManageStock | Specifies whether to track inventory levels for the product. If you want to manage stock (recommended), you can use the [LocationInventory](#locationinventory) sheet to set inventory levels for the product. | A Boolean value, specified as `Yes` or `No`. |
| ManufacturerPartNumber | The manufacturer's part number for the product. | Any string. |
| MAP | The MAP, or minimum advertised price for the product, as specified by the product supplier. If MAP pricing is in effect, this value overrides all other prices you specify for the product. However, you can still apply a discount to a product with MAP pricing. | Any decimal value. |
| MAPEffectiveStartDate | The effective start date for MAP pricing. The system ignores the MAP value if this date is in the future. | A date and time in UTC format. If this value is empty and the MAPEffectiveEndDate is set and has not yet passed, the MAP price applies. |
| MAPEffectiveEndDate | The effective end date for MAP pricing. The system ignores the MAP value if this date has passed. | A date and time in UTC format. If MAPEffectiveStartDate is specified and this value is empty, the MAP price applies indefinitely. |
| MSRP | The manufacturers suggested retail price for the product. | Any decimal value. |
| OutOfStockBehavior | If ManageStock is `Yes`, specifies the action to take if the product is out of stock. You can display an out-of-stock message to the customer, allow the customer to back-order the product, or hide the product from the storefront. | A string matching one of the following: `DisplayMessage` (Default), `HideProduct`, `AllowBackorder` |
| PackageHeight | The height of the product when packaged, in imperial units (feet and inches). This value is used to calculate shipping costs. | Any decimal value. |
| PackageLength | The length of the product when packaged, in imperial units (feet and inches). This value is used to calculate shipping costs. | Any decimal value. |
| PackageWeight | The weight of the product when packaged, in imperial units (pounds and ounces). This value is used to calculate shipping costs. | Any decimal value. |
| PackageWidth | The width of the product when packaged, in imperial units (feet and inches). This value is used to calculate shipping costs. | Any decimal value. |
| Price | The unit price for the product if no sale or discount is applied. | Any decimal value. |
| ProductName | The name the customer sees for the product. | Any string. |
| ProductShortDescription | A short (260 characters) description for the product. This value is typically used when the product is displayed in a list of search results. | Any string. Character limit: 260. HTML tags are supported, and are not counted in the description character limit. |
| ProductType | The name of the product type associated with the product. | Any string that is a valid product type name. This value should match a ProductType on the [ProductTypes](#producttypes) sheet. |
| ProductUsage | The product usage type this product supports. | A string matching one of the following: `Standard`, `Configurable`, `Bundle`, `Component`
The usage type you specify must be enabled for the product type on the [ProductTypes](#producttypes) sheet. |
| RestrictDiscount | Specifies whether discounts are restricted on the product. If `Yes`, the system cannot apply any discounts to the product. | A Boolean value, specified as `Yes` or `No`. |
| RestrictDiscountEndDate | If RestrictDiscount is `Yes`, specifies the end date for the restriction. | A date and time in UTC format. If RestrictDiscountStartDate is specified and this value is empty, the restriction applies indefinitely. |
| RestrictDiscountStartDate | If RestrictDiscount is `Yes`, specifies the start date for the restriction. | A date and time in UTC format. If this value is empty and the RestrictedDiscountEndDate is set and has not yet passed, the restriction applies. |
| SalePrice | The sale price for the product. If set, this value overrides the Price. | Any decimal value. |
| SEOFriendlyURL | The default URL structure for products is `yourSite.com/{slug}/p/{productCode}` and for categories is `yourSite.com/{slug}/c/{categoryId}`. The slug (or SEO-friendly URL) gives you the ability to add a meaningful component to the URL structure in order to boost search results. | Any string. |
| SEOMetaTagDescription | Maps to the HTML meta description tag, which is used by search engines to summarize the content of the page. | Any string. |
| SEOMetaTagKeywords | Maps to the HTML meta keywords tag, which is used to tell search engines what the page is about. From an SEO-perspective, search engines place little value on this tag, but the search implementation uses these keywords to help construct search results for pages on your storefront. | Any string. |
| SEOMetaTagTitle | Maps to the HTML meta title tag. While most search engines place little value on this tag, most themes inject the value of the meta title tag into the HTML title tag.
The HTML title tag is used by search engines and browsers to display the title of the page, and is critical to SEO. Search engines place very high importance on the correlation between a page's title tag and its content. | Any string. |
| UPC | The universal product code (UPC) for the product. | Any string. A valid UPC must be unique across all sales channels. |
| VariationPricingMethod | Specifies the pricing method for variations associated with the product, either relative to the base product through a delta, or by providing a explicit, fixed value for the variation. | One of two string values: `Delta` or `Fixed`. |
### ProductPropertyLocale
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [Products](#products), [ProductCatalog](#productcatalog), [ProductOptions](#productoptions), [ProductExtras](#productextras), [ProductBundles](#productbundles), [ProductImages](#productimages), [ProductOptionsLocale](#productoptionslocale)
This sheet allows you to specify different product property values across locales.
| Column Name | Description | Valid Values |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product property. | A string matching any valid master catalog name. |
| ProductCode | The unique identifier for the product the property is mapped to. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on [Products](#products) sheet. Character limit: 3-30. |
| Attribute Name | The name of the attribute as it appears to customers. For example: `Size`
This value corresponds to the **Attribute Label** in Admin. If you are creating a new attribute, this value is used for the **Administration Name** that Admin users see. | Any string. The string must be unique to a single attribute in the master catalog. |
| AttributeCode | The unique identifier of the attribute as used by the system. | Any string that is a valid attribute code. |
| Value | The actual value for the attribute. This is not the string that a customer sees, but rather the value as it appears in the **Value** column of the **Values** table for the attribute in Admin. This value must be unique within the vocabulary for a single attribute and match the DataType of the attribute. If an attribute has multiple values, each Value is specified on a separate row in this sheet. | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to escape spaces or characters. |
| \[ Locale ] | This sheet will include a series of columns for all relevant locales, such as en-US and fr-CA. The values within this column will be the localized label of the attribute. | Any string or number. |
### ProductCatalog
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [Products](#products), [ProductOptions](#productoptions), [ProductExtras](#productextras), [ProductBundles](#productbundles), [ProductImages](#productimages), [ProductPropertyLocale](#productpropertylocale), [ProductOptionsLocale](#productoptionslocale)
This sheet maps product codes to catalogs within a master catalog. The ProductCode must match the product definition in the master catalog, or as specified on the [Products](#products) sheet. All other data can differ from the master catalog. For example, in a specific sub-catalog, a product could belong to different categories or have different prices.
| Column Name | Description | Valid Values |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product. Products are defined on the master catalog level. After you define a product in the master catalog, you can use the [ProductCatalog](#productcatalog) sheet to add it to sub-catalogs. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| CatalogName | The name of the catalog that includes the product. To add a product to multiple catalogs, create a new row for each catalog. | A string matching any valid catalog name. This should be a sub-catalog. Products are mapped to a master catalog when they are created, or on the [Products](#products) sheet. |
| ProductCode | The unique identifier for the product. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on [Products](#products) sheet. Character limit: 3-30. |
| CategoryCodes | A list of categories the product belongs to, specfied using the relevant category codes. | Any list of strings composed of valid category codes, separated by a comma. For example, `CategoryA, Category B, Category C`. |
| IsActive | Specifies whether the product is active in the catalog. If `No`, the product is hidden from customers on the storefront. | A Boolean value, specified as `Yes` or `No`. |
| MAP | The MAP, or minimum advertised price for the product, as specified by the product supplier. If MAP pricing is in effect, this value overrides all other prices you specify for the product. However, you can still apply a discount to a product with MAP pricing. | Any decimal value.
This value overrides the MAP on the [Products](#products) sheet. |
| MAPEffectiveEndDate | The effective end date for MAP pricing. The system ignores the MAP value if this date has passed. | A date and time in UTC format. If MAPEffectiveStartDate is specified and this value is empty, the MAP price applies indefinitely.
This value overrides the MAPEffectiveEndDate on the [Products](#products) sheet. |
| MAPEffectiveStartDate | The effective start date for MAP pricing. The system ignores the MAP value if this date is in the future. | A date and time in UTC format. If this value is empty and the MAPEffectiveEndDate is set and has not yet passed, the MAP price applies.
This value overrides the MAPEffectiveStartDate on the [Products](#products) sheet. |
| MSRP | The manufacturers suggested retail price for the product. | Any decimal value.
This value overrides the MSRP on the [Products](#products) sheet. |
| IsPriceOverridden | Specifies that the price overrides the default master catalog price. | A Boolean value, specified as `Yes` or `No`. |
| IsContentOverridden | Specifies that the content overrides the default master catalog content. | A Boolean value, specified as `Yes` or `No`. |
| IsSEOOverridden | Specifies that the SEO data overrides the default master catalog SEO data. | A Boolean value, specified as `Yes` or `No`. |
| DateFirstAvailableInCatalog | The date the product either becomes or became first available in the catalog. | A string matching a `Date` or `DateTime`. |
| Price | The unit price for the product if no sale or discount is applied. | Any decimal value.
This value overrides the Price on the [Products](#products) sheet. |
| SalePrice | The sale price for the product. If set, this value overrides the Price. | Any decimal value.
This value overrides the SalePrice on the [Products](#products) sheet. |
### ProductBundles
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [Products](#products), [ProductCatalog](#productcatalog), [ProductOptions](#productoptions), [ProductExtras](#productextras), [ProductImages](#productimages), [ProductPropertyLocale](#productpropertylocale), [ProductOptionsLocale](#productoptionslocale)
This sheet defines products that are bundles, or collections of other products.
| Column Name | Description | Valid Values |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product. Products are defined on the master catalog level. After you define a product in the master catalog, you can use the [ProductCatalog](#productcatalog) sheet to add it to sub-catalogs. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the product bundle.
This is the code for the bundle itself, not for individual products in the bundle. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on the [Products](#products) sheet. Character limit: 3-30. |
| Code | The unique identifier for a product within the bundle. If the bundle contains multiple products, each component product Code is specified on a separate row in this sheet. | Any number that is unique among all product codes in the master catalog. This value must match a ProductCode in the master catalog, or on the [Products](#products) sheet. |
| Name | The name of the bundle as it appears to customers on the storefront. | Any string. |
| Quantity | The quantity of the component product (specified by Code) that the bundle includes. For example, a phone bundle might include two chargers. | Any integer. The default is `1`. |
### ProductOptions
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [Products](#products), [ProductCatalog](#productcatalog), [ProductExtras](#productextras), [ProductBundles](#productbundles), [ProductImages](#productimages), [ProductPropertyLocale](#productpropertylocale), [ProductOptionsLocale](#productoptionslocale)
The sheet defines the options, such as different sizes or colors, that a customer can select for a product. Every product option creates a variation of the base product. Note that you must upload all possible combinations of a configurable product when updating values on variants, even if all possible variants are not enabled.
In addition to the columns described in the following table, the ProductOptions sheet includes columns for all the attributes you create that can be options on a product (IsOption is `Yes` on the [Attributes](#attributes) sheet).
| Column Name | Description | Valid Values |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the base product. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on the [Products](#products) sheet. Character limit: 3-30. |
| VariationCode | The unique identifier for the variation of the product that includes this option. | Any string. For simplicity, this string is typically created by appending a hyphen and number to the ProductCode. For example, ProductCode `133188` can have a VariationCode of `133188-1`.
**Note:** If you add a new option list to a product, you must create new variation codes for the product. For example, if you have a VariationCode that maps to a shirt in size Small, and you add an additional option from a *different* option list to indicate the shirt is also Blue, you must create a new VariationCode to represent the Small and Blue variation. |
| DistPartNo | The distributor's part number for this specific product option. | Any string. |
| Enabled | Specifies whether the option is enabled for the product. If `No`, the option does not appear for customers to select. The default is `No`. | A Boolean value, specified as `Yes` or `No`.
As a best practice, set this option to `No` only if a product option is permanently unavailable. Enable ManageStock on the [Products](#products) sheet to handle a temporary inventory shortage. |
| ExtraCost | The additional cost the supplier charges for this option. | Any decimal value. This value has no impact on the price of the product. |
| ExtraPrice | The amount added to the base product price or sale price for this option. For example, you might charge an extra \$5.00 for an unusual size. | Any decimal value. |
| ExtraWeight | The amount this option adds to the base package weight, in imperial units (pounds and ounces). This value is used to calculate shipping costs. | Any decimal value. |
| FixedListPrice | If the product is in Explicit pricing mode, this is the list price of the option. | Any decimal value. This value has no impact on the price of the product. |
| FixedSalePrice | If the product is in Explicit pricing mode, this is the sale price of the option. | Any decimal value. This value has no impact on the price of the product. |
| FixedWeight | If the product is in Explicit pricing mode, this is the weight of the option. | Any decimal value. |
| FulfillmentTypes | The fulfillment types supported for this option. This value overrides the fulfillment types on the base product. | A string matching one of the following: `DirectShip`, `InStorePickup`, `Digital`
If multiple fulfillment types are supported, use an ampersand (&) to include additional types. For example: `DirectShip & InStorePickup` |
| MfgPartNo | The manufacturer's part number for this specific product option. | Any string. |
| UPC | The universal product code (UPC) for this specific product option. | Any string. A valid UPC must be unique across all sales channels. |
### ProductExtras
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [Products](#products), [ProductCatalog](#productcatalog), [ProductOptions](#productoptions), [ProductBundles](#productbundles), [ProductImages](#productimages), [ProductPropertyLocale](#productpropertylocale), [ProductOptionsLocale](#productoptionslocale)
This sheet defines the extras, such as monograms, warranties, and so on, that a customer can add to a product. Each product code can have multiple extras.
| Column Name | Description | Valid Values |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AttributeCode | The unique code for the attribute that defines the extra. | Any string. To be a valid extra, the attribute this code identifies must be enabled as an extra, or have IsExtra set to `Yes` on the [Attributes](#attributes) sheet. |
| MasterCatalogName | The name of the master catalog that includes the product. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the product. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on the [Products](#products) sheet. Character limit: 3-30. |
| Defaulted | Specifies whether the value for the extra is selected by default. If `Yes`, the customer cannot specify the value for the extra. | A Boolean value, specified as `Yes` or `No`. |
| MultiSelect | Specifies whether the customer can select more than one value from a predefined list for this extra. | A Boolean value, specified as `Yes` or `No`. For `Yes` to be valid, the attribute that defines the extra must have an InputType of `List`. |
| Quantity | Specifies a quantity of extras that the customer can select. For example, if a lamp is available with extra lamp shades, you can specify how many shades the customer can add to their order. | Any integer. |
| RequiredByShopper | Specifies whether the customer must select or specify the extra to purchase the product. For example, if you are selling a monogrammed towel, you can require the customer to enter the monogram. The default is `No`. | A Boolean value, specified as `Yes` or `No`. |
| Value | The value for the extra. This value must be a valid Value for the AttributeCode, as defined on the [AttributeValues](#attributevalue) sheet. | A string or number. The value cannot contain spaces or special characters. You can use a hyphen (-) to escape spaces or characters. |
### ProductOptionLocalization
Corresponding REST API Resource: [commerce/catalog/admin/products](/api-overviews/openapi_catalog_admin_overview)
Required With: [Products](#products), [ProductCatalog](#productcatalog), [ProductExtras](#productextras), [ProductBundles](#productbundles), [ProductImages](#productimages), [ProductPropertyLocale](#productpropertylocale)
The sheet defines how options may differ across different locales.
| Column Name | Description | Valid Values |
| ------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the base product. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on the [Products](#products) sheet. Character limit: 3-30. |
| VariationCode | The unique identifier for the variation of the product that includes this option. | Any string. For simplicity, this string is typically created by appending a hyphen and number to the ProductCode. For example, ProductCode `133188` can have a VariationCode of `133188-1`.
**Note:** If you add a new option list to a product, you must create new variation codes for the product. For example, if you have a VariationCode that maps to a shirt in size Small, and you add an additional option from a *different* option list to indicate the shirt is also Blue, you must create a new VariationCode to represent the Small and Blue variation. |
| Currency | The currency in which to show the price of the product. | Any three-character ISO currency code. For example, `USD`. |
| Extra Credit Value | The additional credit value for this digital gift card option in the locale. | Any decimal value. |
| Extra MSRP | The amount added to the MSRP price for this option in this locale. | Any decimal value. |
| Extra Price | The amount added to the base product price or sale price for this option in this locale. | Any decimal value. |
| Fixed List Price | The fixed list price of the product in this locale. | Any decimal value. |
| Fixed Sale Price | The fixed sale price of the product in this locale. | Any decimal value. |
### ProductImages
Corresponding REST API Resource: [commerce/catalog/storefront/products](/api-overviews/openapi_catalog_storefront_overview)
Required With: [Products](#products), [ProductCatalog](#productcatalog), [ProductOptions](#productoptions), [ProductExtras](#productextras), [ProductBundles](#productbundles), [ProductPropertyLocale](#productpropertylocale), [ProductOptionsLocale](#productoptionslocale)
This sheet maps images and videos to product codes so you can use the media on the product pages of your storefront. A single product code can have multiple images and videos associated with it.
For import operations, this sheet handles file-mapping only. Use the [Images](#images) sheet to upload actual image files to the CMS.
| Column Name | Description | Valid Values |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the product. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on the [Products](#products) sheet. Character limit: 3-30. |
| AltText | The plain text that appears when the customer hovers over the file, or that appears in place of the file if the file does not load. | Any alphanumeric string. This string should not include any special characters or HTML. |
| CmsId | The unique identifier for the file in your CMS. | Any string. |
| ImageUrl | The full URL path to an image file. | Any string that is a valid, accessible URL. |
| ImageLabel | The label for the image that appears on the storefront, in the language specified by the LocaleCode. | Any string. |
| Name | The filename, including type extension, of the image or video. | Any string that matches a valid image or video filename. |
| Sequence | For products with multiple images or videos, specifies where in the order or all image/video files the one in this row appears on the product page. | Any integer. |
| VideoUrl | The full URL path to an accessible video file.
**Note:** You can only associate external videos, as you cannot upload video files to the CMS. | Any string that is a valid, accessible URL. |
| LocaleCode | The locale code that this image is used in. | Any string that is a valid locale (such as en-US). |
| ProductImageGroupId | The unique identifier for an image group that this file belongs to. This is currently export-only. | Any string. |
| ProductImageGroupTagFqn | The fully-qualified name of a tag for the image group tag, such as tenant\~rom. This is currently export-only. | Any string. |
| ProductImageGroupTagValue | The value of the image group's tag. This is currently export-only. | Any string. |
### LocationTypes
Corresponding REST API Resource: [commerce/catalog/admin/locationtypes](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
This sheet associates product codes with location types, which you use to manage the types of locations your tenant maintains, such as warehouses, physical storefronts, and kiosks.
| Column Name | Description | Valid Values |
| ---------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| LocationTypeCode | The unique identifier for the location type. | Any string that is a valid location type code for your tenant. |
| LocationTypeName | The name of the location type as it appears in Admin. | Any string. |
### Locations
Corresponding REST API Resource: [commerce/catalog/admin/locations](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
This sheet manages physical locations associated with a tenant, so you can specify the relevant addresses, shipment types, and inventory settings for each location.
| Column Name | Description | Valid Values |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| LocationCode | The unique identifier for the location. | Any string that is a valid location code for your tenant. |
| LocationTypes | The location types that the location supports. | A list of strings of valid location types, separated by commas. For example, `Warehouse, Kiosk, RetailStore`. |
| Address1 | Physical or mailing address line one. Usually includes the street number and street name or it could be a P.O. Box. | Any string up to 200 characters in length. |
| Address2 | Physical or mailing address line two. Usually supplements the main street address with apartment, floor, suite, building, or unit information. | Any string up to 200 characters in length. |
| Address3 | Physical or mailing address line three, if needed. | Any string up to 200 characters in length. |
| Address4 | Physical or mailing address line four, if needed. | Any string up to 200 characters in length. |
| Address Type | The type of address. | Either `Commercial` or `Residential`. |
| AllowFulfillmentWithNoStock | Specifies whether you can fulfill an order when inventory is less than the quantity requested in the order. | A Boolean value, specified as `Yes` or `No`. For this value to take effect, you must set `SupportsInventory` to `Yes`. |
| CityOrTown | The city or town for the location address. | Any string. |
| CountryCode | The 2-letter geographic code representing the country for the physical or mailing address. | Currently limited to `US`. |
| Description | The description of the location as it appears to Admin users. | Any string. |
| Fax | The fax number associated with the location. | A formatted fax number, such as `512-555-5555`. |
| FulfillmentTypes | The fulfillment types supported at this location. | A string matching one of the following: `DirectShip`, `InStorePickup`, `Digital`
If multiple fulfillment types are supported, use an ampersand (&) to include additional types. For example: `DirectShip & InStorePickup` |
| Hours of operation - Friday | The Friday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Hours of operation - Monday | The Monday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Hours of operation - Saturday | The Saturday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Hours of operation - Sunday | The Sunday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Hours of operation - Thursday | The Thursday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Hours of operation - Tuesday | The Tuesday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Hours of operation - Wednesday | The Wednesday business hours for the location. | Any string that describes your operating hours. For example, `8a-3p`, `10:30 AM - 7:30 PM`, or `Closed`. |
| Last Modified Date | The last time the location was updated. | A date in UTC format. |
| Latitude | The location latitude in degrees. | A decimal number representing the latitude. |
| Longitude | The location longitude in degrees. | A decimal number representing the longitude. |
| Name | The name of the location, used for identification purposes, as it appears to Admin users. | Any string. |
| Notes | General comments associated with the location that are only visible to Admin users. | Any string. |
| Phone | The phone number associated with the location. | A formatted phone number, such as `512-555-5555`. |
| PostalOrZipCode | The zip or postal code of the location address. | A number representing the zip or postal code. |
| Shipping Contact OrganizationOrCompany | The company name used to assemble contact details for the location. | Any string. |
| Shipping Contact Email | The email used to assemble contact details for the location. | Any string. |
| Shipping Contact FirstName | The first name used to assemble contact details for the location. | Any string. |
| Shipping Contact LastNameOrSurname | The last name used to assemble contact details for the location. | Any string. |
| Shipping Contact MiddleNameOrInitial | The middle name or initial used to assemble contact details for the location. | Any string. |
| Shipping Contact PhoneNumber | The phone number used to assemble contact details for the location. | Any string. |
| StateOrProvince | The state or province of the location address. | Any string. |
| Status | Specifies whether the location is enabled. | Either `Active` or `Disabled`. |
| SupportsInventory | Specifies whether the location maintains product inventory. If thel location supports the direct ship fulfillment type, it must also support inventory. | A Boolean value, specified as `Yes` or `No`. |
| Tags | A list of tags associated with the location. | Any string. |
### LocationGroup
Corresponding REST API Resource: [commerce/catalog/admin/locationgroups](/api-overviews/openapi_catalog_admin_overview)
This sheet describes [location groups](/pages/location-groups "Location Groups") on a per-location basis.
| Column Name | Description | Valid Values |
| ------------------ | ----------------------------------------------------------------------------------- | -------------------------------------- |
| LocationGroupCode | The unique identifier for the location group. | Any string. |
| Name | The name of the location group. | Any string. |
| LocationCodes | A list of unique identifiers for each location that belongs to the group. | Strings that are valid location codes. |
| SiteIds | A list of unique identifiers for each site that this location group is used within. | Strings that are valid Site IDs. |
| Last Modified Date | The last time the location was updated. | A date in UTC format. |
### LocationGroupConfiguration
Corresponding REST API Resource: [commerce/catalog/admin/locationgroupconfiguration](/api-overviews/openapi_catalog_admin_overview)
This sheet describes location group configurations on a per-location basis.
| Column Name | Description | Valid Values |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LocationGroupCode | The unique identifier for the location group. | Any string that is a valid location group. |
| Customer Failed To Pickup After Action | The behavior that should be taken to handle a shipment that has not been picked up by the customer after a deadline. | A string that is a valid after-action in [location group configurations](/pages/location-groups#configure-a-location-group "Location Groups"), such as "Customer Care." |
| Customer Failed To Pickup Deadline | The number of days without pickup at which point after-actions are performed for a BOPIS shipment. | Any integer. |
| Send Customer Pickup Reminder | The length of time at which point a reminder is sent to the customer after a shipment has begun awaiting Customer Pickup. | A string that is a valid options in [location group configurations](/pages/location-groups#configure-a-location-group), such as "2 days" |
| Default Carrier | The default shipping carrier used by locations in this group. | A string that matches a valid shipping carrier. |
| Print Return Label | Indicates whether return labels are printed alongside shipping labels or not. | A Boolean value, specified as `Yes` or `No`. |
| Default Printer Type | The type of printer that shipping labels are printed on by default. | A string for a valid printer type such as "Laser." |
| Last Modified Date | The last time the location was updated. | A date in UTC format. |
### LocationGroupConfigurationBoxType
Corresponding REST API Resource: [commerce/catalog/admin/locationgroupconfiguration](/api-overviews/openapi_catalog_admin_overview)
This sheet describes location group box type configurations on a per-location basis.
| Column Name | Description | Valid Values |
| ----------------- | --------------------------------------------- | ------------------------------------------ |
| LocationGroupCode | The unique identifier for the location group. | Any string that is a valid location group. |
| Name | The name of the box type. | Any string. |
| Height | The height of the package dimensions. | Any decimal. |
| Length | The length of the package dimensions. | Any decimal. |
| Width | The width of the package dimensions. | Any decimal. |
### LocationGroupConfigurationCarrier
Corresponding REST API Resource: [commerce/catalog/admin/locationgroupconfiguration](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
This sheet describes location group carrier configurations on a per-location basis.
| Column Name | Description | Valid Values |
| ---------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| LocationGroupCode | The unique identifier for the location group. | Any string that is a valid location group. |
| SiteId | A unique identifiers for the site that this location group is being configured for. | Any string that is a valid Site Id. |
| CarrierType | The carrier type being configured. | Any string that is a valid carrier. |
| isEnabled | Indicates whether this carrier is enabled for the location group or not. | A Boolean value, specified as `Yes` or `No`. |
| Enable Smart Post | Indicates whether to enable Smart Post for this carrier or not. | A Boolean value, specified as `Yes` or `No`. |
| Express 1 Day Default | The service type that this carrier uses as its default 1 Day shipping option. | Any string that is a valid [shipping method code](/pages/shipping-method-codes "Shipping Method Codes"). |
| Express 2 Day Default | The service type that this carrier uses as its default 2 Day shipping option. | Any string that is a valid [shipping method code](/pages/shipping-method-codes "Shipping Method Codes"). |
| Express 3 Day Default | The service type that this carrier uses as its default 3 Day shipping option. | Any string that is a valid [shipping method code](/pages/shipping-method-codes "Shipping Method Codes"). |
| Return Label Shipping Method | The type of shipping method that is associated with return labels. | Any string that is a valid [shipping method code](/pages/shipping-method-codes "Shipping Method Codes"). |
| Shipping Methods | All shipping methods supported by this carrier. | A list of strings that are valid [shipping method codes](/pages/shipping-method-codes "Shipping Method Codes"). |
| Standard Default | The service type that this carrier uses as its default standard shipping option. | Any string that is a valid [shipping method code](/pages/shipping-method-codes "Shipping Method Codes"). |
### LocationInventory
Corresponding REST API Resource: [commerce/catalog/admin/locationinventory](/api-overviews/openapi_catalog_admin_overview)
Required With: NA
This sheet describes inventory levels on a per-location basis. Locations can be either warehouses or brick and mortar businesses with stock on-hand. This sheet associates product codes and quantities with the locations.
You cannot use this sheet to create locations. Use the [Locations](#locations) sheet before you try to import new or updated inventory.
| Column Name | Description | Valid Values |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| MasterCatalogName | The name of the master catalog that includes the product. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| ProductCode | The unique identifier for the product. | Any number that is unique among all product codes in the master catalog. This value must match the ProductCode in the master catalog, or on the [Products](#products) sheet. The product also must have ManageStock set to `Yes` on the Products sheet. Character limit: 3-30. |
| LocationCode | The unique identifier for the location that has the inventory. You specify this code when you create the location. | Any string that is a valid location code for your tenant. |
| ParentProductCode | The unique identifier for the parent product, if applicable. | Any string that is a valid product code. Character limit: 3-30. |
| StockAvailable | The quantity of stock of the ProductCode that is available at this location. This value may differ from the StockOnHand if orders are pending. This value is read-only, and is determined based on the number of pending product reservations. | Any integer. (Read-Only) |
| StockOnBackOrder | The quantity of stock of the ProductCode that is on back order (or reserved) at this location. This value is read-only, and is determined based on the number of pending product reservations. | Any integer. (Read-Only) |
| StockOnHand | The quantity of stock of the ProductCode that is on-hand and available at this location. | Any integer. |
| StockUpdateOption | Specifies whether the stock numbers are updated when purchases complete or new inventory is received. | A Boolean value, specified as `Yes` or `No`. |
### Images
Corresponding REST API Resources: [commerce/catalog/storefront/products](/api-overviews/openapi_catalog_storefront_overview), [commerce/catalog/storefront/categories](/api-overviews/openapi_catalog_storefront_overview), [content/documentlists/documents](/api-overviews/openapi_content_overview)
Required With: NA
This sheet describes all the image files that exist in the database for your tenant. You can use this sheet independent of other sheets to upload new images to your tenant. Use the [ProductImages](#productimages-18) and [Categories](#categories) sheets to associate images with specific products or categories.
Because images can be large files, uploading them can add significant time to an import operation. If you are updating products and know that you do not need to add or change media, clear this sheet prior to importing the file.
| Column Name | Description | Valid Values |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MasterCatalogName | The name of the master catalog that includes the product or category with which the image is associated. | A string matching the name of the master catalog as it appears at **Settings** > **System Administration** > **Catalog and Site Structure** in Admin. |
| Id | The document identifier for the image in the CMS. You do not need to provide this value for imports unless you are moving an existing image from one tenant to another and you want the image to retain the same ID. | A 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example: `bba0a1a885e2413bb097ceacf7bac366` or `bba0a1a8-85e2-413b-b097-ceacf7bac366`. |
| Path | The URL for the image file. For export operations, this is the file location in the CMS. For import operations, this can be any URL that is accessible, such as a Dropbox URL. | Any string that is a valid, accessible URL. |
| Name | The filename, including type extension, of the image. | Any string that matches a valid image filename. |
| Tags | Tags associated with the image. These tags appear in the **File Manager** in `Admin`. You can use them to group and filter your files in Admin. | Any string. You can use commas to separate multiple tags. For example: `shoes, wedges` |
# Category Attributes
Source: https://docs.kibocommerce.com/pages/category-attributes
You can add customized attributes to static and dynamic categories to further define their characteristics. This is useful for identifying special categories or supporting your catalog/storefront design.
Learn about product catalog architecture and management
See the Admin Catalog API documentation for programmatic access
Get an introduction to categories in Kibo
For example, you could use attributes to identify some categories as best-sellers or seasonal. If you are using categories to represent different locations, you could use attributes to define an address for each category.
## Create a Category Attribute
To create a category attribute:
1. Go to **System** > **Schema** > **Category** **Attributes**.
2. Click **Create New Category Attribute**.
3. Enter an **Attribute Label** that has meaning to you.
Keep in mind that it appears on the storefront if you later specify it to display there.
1. If you want to give it a different name for administration purposes, edit the **Administration Name**.
The default name is the **Attribute Label**.
2. If you want to customize the **Attribute Code**, edit the value accordingly.
This field automatically populates based on the **Attribute Label**.
4. Select a **Display Group**.
This field determines where the attribute displays: either in the Admin only, or in the Admin and on the storefront.
5. Select an **Input Type**. Depending on your selection, additional configurations may appear.
1. If you choose **List**, select a **Data Type** and enter the selection options in the **Values** field.
2. If you choose **Text box**, select a **Data Type**. Optionally, you can define input parameters in the **Min char/val** and **Max char/val** fields, or enter a regular expression in the **Input validation** field.
3. If you choose **Text area**, you can optionally define a **Max char** value.
4. If you choose **Date**, you can optionally define a start and/or end date for the selectable range.
5. If you choose **Yes/No**, there are no additional configurations.
You can edit existing attributes from the Category Attributes page by clicking any attribute in the table, but you will not be able to change the input type or code. You can edit the label, name, whether it is currently enabled or disabled, and most additional configurations specific to the input type.
## Apply a Category Attribute
To apply a category attribute:
1. Go to **Main** > **Sell** > **Categories**.
2. Select the category to which you want to apply the attribute.
3. In the **Category** **Attributes** section, all available attributes will be displayed. Select the value of your choice for any given attribute (or leave it blank if you don't want to use it for this category). This example shows four different attributes available for a category.
## Filter on Category Attributes
You can use these attributes as filters when searching categories in the Admin UI or Category APIs.
At **Main** > **Sell** > **Categories**, use the search bar's Advanced Filter dropdown to search for categories based on attributes. You should select both an Attribute Name and Attribute Value. The allowed input type (such as true/false or a string) will depend on the selected attribute and an error message will be displayed if you enter an invalid value.
To filter the Category API, you must use a [dedicated endpoint](/api-reference/categories/search-category-attributes) that wraps around the Get Categories call. Attempts to apply an attribute filter to the [basic Get Categories call](/api-reference/categories/get-categories) will be ignored. You can either apply the prefix `tenant~` to the attribute or leave it off and the system will automatically add it for you. This will return the same response as Get Categories, but only include categories with that attribute value.
Note that the syntax for this endpoint requires you to specify the attribute name and value at the same time. This means that your query will include three fields joined by equals (=) signs: the attribute's fully qualified name (or attribute code), the value, and the attribute type (string, number, datetime, bool, or productCode). See the following example, querying for a "seasonal" attribute:
```text theme={null}
GET .../commerce/catalog/admin/categories/searchCategoryAttributes?filter=tenant~attribute eq seasonal=true=bool
GET .../commerce/catalog/admin/categories/searchCategoryAttributes?filter=attribute eq seasonal=true=bool
```
Note that whenever you make a call to the Category API, you must include the `includeAttributes=true` query parameter in order to see any attribute information in that response.
# Category Overview
Source: https://docs.kibocommerce.com/pages/category-overview
Categories organize products into divisions that control where they appear on your site. After you build the category hierarchy, you can add individual products to categories and subcategories in the hierarchy.
Get an introduction to categories in Kibo
For example, if your online store sells a mixture of women's wear, men's wear, and accessories you might create the following top-level categories:
* Women's
* Men's
* Accessories
Then, you might create the following subcategories for the women's and men's category:
* Separates
* Swimwear
So your final category hierarchy would look like:
You can also use product categories to apply discounts to a specific group of products.
## Category Types
Kibo eCommerce allows you to create three types of product categories:
* [Static](/pages/static-categories): Allow you to manually specify the individual products that belong to them. To do this, assign the category for each individual product [in its product settings](/pages/configure-products).
* [Dynamic precomputed](/pages/dynamic-categories#precomputed_categories): Allow you to specify dynamic expressions that control the products that belong to them. The product membership is calculated when products are indexed in the catalog.
* [Dynamic realtime](/pages/dynamic-categories#realtime_categories): Allow you to specify dynamic expressions that control the products that belong to them. The product membership is calculated in realtime and on demand when a shopper navigates to the realtime category page.
Refer to the following table for more information about the differences between the three types of categories:
| Feature | Category Type Static? | Category Type Dynamic Precomputed? | Category Type Dynamic Realtime? |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------- | ------------------------------- |
| Can have products statically assigned | Yes | No | No |
| Can have child categories | Yes | No | No |
| Can have products assigned via a membership expression | No | Yes | Yes |
| Can evaluate a product's Sale Price and Sale Price Type (price after discount applied) as part of membership expression | No | No | Yes |
| Can evaluate catalog list prices as part of the membership expression | No | Yes | Yes |
| Can evaluate product properties as part of the membership expression | No | Yes | Yes |
| Navigating to a parent category displays products included in the child category | Yes | Yes | No |
| Can be used as target criteria for a discount | Yes | Yes | No |
| Becomes a complex search filter at runtime | No | No | Yes |
Refer to [Dynamic Category Expressions](/pages/dynamic-category-expressions) for more information about the two types of dynamic categories and creating expressions for them.
## View Types
| View Type | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tree | This view is the default view when you first navigate to the Beta Categories module. The Tree view shows your categories hierarchically organized, which is useful to quickly view the relationships between categories, such as parent-child relationships. It also loads categories incrementally as needed, instead of at the same time, resulting in faster loading and a smoother viewing experience even with a large amount of categories. |
Refer to [Tree View](#tree-view) for more information about this view. |
\| Grid | The Grid view shows your categories in a flat list, regardless of hierarchy or relationship. This is useful to quickly view a total list of all your categories, and you can use this view to search, sort, and filter categories.
Refer to [Grid View](#grid-view) for more information about this view. |
## Tree View
The Tree view shows your categories hierarchically organized, as well as loads categories incrementally as needed. This is useful to quickly view the relationships between categories, such as parent-child relationships:
To navigate to this view, click the Indented List icon in the top right of the page:
### View Sub-Categories
When a category has sub-categories (children), the parent category has a caret icon next to it. You can click the caret to expand the parent category and view its sub-categories:
### Show/Hide Disabled Categories
The Tree view automatically hides disabled categories; however, you can still show disabled categories in the Tree view by expanding the menu to the right of the tree icon and clicking **Show Disabled**:
If you want to hide disabled categories, you can click the same button and select **Hide Disabled.**
### Drag and Drop
This view supports drag and drop capabilities, so you can quickly change parent child relationships in the category tree.
## Grid View
The Grid view shows your categories in a flat list, regardless of hierarchy or relationship:
This is useful to quickly view a list of all your categories. You can also use this view to search, sort, and filter categories.
To navigate to this view, click the Flat List icon in the top right of the page:
The Grid view hides disabled categories; however, you can use the **Status** filter in the search bar's Advanced Filter menu to show Active, Disabled, or All categories:
Note that when searching for categories with the Advanced Filter, you can also filter based on any configured [category attributes](/pages/category-attributes).
# Category Pages (After)
Source: https://docs.kibocommerce.com/pages/category-pages-after
This action manipulates the HTTP request or response after a Category page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.category.request.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Category Pages (Before)
Source: https://docs.kibocommerce.com/pages/category-pages-before
This action manipulates the HTTP request or response before a Category page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.category.request.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Category View
Source: https://docs.kibocommerce.com/pages/category-view
The Category view provides dimensions and measures for the product category data model.
The supported filters that can be applied to this view are:
| Name | Data Type | Description |
| --------------- | --------- | ------------------------------------------- |
| Category Filter | String | Use to filter results by the category name. |
The measures calculated by this view are:
| Name | Measure Type | Description |
| -------------- | ------------ | ------------------------------ |
| Category Count | Count | Count of all category records. |
The dimensions included in this view are:
| Name | Data Type | Description |
| -------------------------- | --------- | ---------------------------------------------------------------------------------- |
| Catalog ID | Number | Unique identifier for the product catalog to which the product category belongs. |
| Category Code | String | External unique identifier of the category. |
| Category Created Date | Datetime | The timestamp of the date and time the product category was created. |
| Category ID | Number | Internal unique identifier of the category. |
| Category Last Updated Date | Datetime | The timestamp of the date and time the product category was most recently updated. |
| Category Name | String | The user supplied name for the product category. |
| Parent Category ID | Number | If the category has a parent, the identifier of the category's parent category. |
# Change Password (After)
Source: https://docs.kibocommerce.com/pages/change-password-after
**Related API:** This extension modifies the [Change Password](/api-reference/customeraccount/change-password) operation.
This action manipulates the HTTP request or response after the ChangePassword operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.accounts.changePassword.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The following methods and objects are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/changePassword](/api-reference/customeraccount/change-password) operation.
**HTTP Request**
POST `api/commerce/customer/accounts/{accountId}/Change-Password?unlockAccount={unlockAccount}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
No response body content for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Change Password (Before)
Source: https://docs.kibocommerce.com/pages/change-password-before
**Related API:** This extension modifies the [Change Password](/api-reference/customeraccount/change-password) operation.
This action manipulates the HTTP request or response before the ChangePassword operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.accounts.changePassword.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/changePassword](/api-reference/customeraccount/change-password) operation.
**HTTP Request**
POST `api/commerce/customer/accounts/{accountId}/Change-Password?unlockAccount={unlockAccount}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
No response body content for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Channel Dashboard
Source: https://docs.kibocommerce.com/pages/channel-dashboard
The Channel dashboard breaks down metrics by specific channels, displaying performance for a particular channel or comparing performance across multiple channels. This can be viewed under the orders topic at **Kibo Standard Reports** > **Order** > **Channel Dashboard** in the navigation menu.
Learn how to configure and manage channels
The supported filters that can be applied to this dashboard are:
| Name | Description | Default |
| ------------------ | ------------------------------------------------------------ | --------------- |
| Site Name | Restrict results to one or more of your sites. | All |
| Order Created Date | Limit results to only orders created within this time range. | Past five weeks |
The measures that are calculated by this dashboard are:
| Name | Description |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| Total Collected | Sum of the total for all valid orders. |
| Order Count | Count of all valid orders. |
| Average Order Value | The order total divided by the valid order count. |
| Items Per Order | The count of all order items associated with valid orders divided by the count of all valid orders. |
The tiles that make up this dashboard are:
| Name | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------- |
| Order Count By Channel | The count of valid orders for each channel. |
| Total Collected By Channel | The total collected for each channel. |
| AOV By Channel | The average order value for each channel. |
| IPO By Channel | The items per order for each channel. |
| Percentage Of Orders By Channel | The order count for each channel as a percentage of the order count for all channels. |
| Percentage Of Revenue By Channel | The total collected for each channel as a percentage of the total collected for all channels. |
| Channel Summary | The total collected, order count, average order value, and items per order for each channel. |
# Channel Settings
Source: https://docs.kibocommerce.com/pages/channel-settings
Kibo eCommerce uses channels to track where orders originate from. Your business may receive a mixture of orders that originate from different sources. Defining these sources helps you determine an order’s point of origin when you view it in the Orders module and also when you view details about your business performance in the Reporting module.
Learn how to configure and manage channels
See how to configure site-specific settings
Learn how to configure and manage sites
Once you create a channel you can then associate that channel with an individual site. Refer to the [General Settings](/pages/general-settings) for more information about associating a channel with an individual site.
You associate each channel with a site, and a site can only have one channel associated with it.
For example, your company Mystic Sports includes retail kiosks across the United States and an online store, MysticSports.com. You create the following channels:
| Code | Name | Country |
| --------- | -------------------- | ------- |
| MS-Kiosk | Mystic Sports Kiosk | US |
| MS-Online | Mystic Sports Online | US |
## Create a Channel
To create a channel:
1. Go to **System** > **Structure** > **Channels**.
2. Click **Create New Channel**.
3. Enter a **Code**.
4. Enter a **Name**.
5. Select a **Country**.
6. Click **Save**:
# ChannelAdvisor Application
Source: https://docs.kibocommerce.com/pages/channeladvisor-application
![ChannelAdvisor logo]() |
| Platforms: KCCP OMS + Catalog |
[ChannelAdvisor](http://www.channeladvisor.com/) is cloud-based eCommerce software that connects retailers and manufacturers to multiple online sales channels, including Amazon, Google, eBay, and more. The ChannelAdvisor application syncs your eCommerce products, orders, and customers with any number of third-party marketplaces to optimize sell-through and customer reach. For more details about ChannelAdvisor, refer to their [user guides](https://knowledge.channeladvisor.com/kc) and [API documentation](https://knowledge.channeladvisor.com/kc?id=kb_article_view\&sys_kb_id=66ec1bc52fd15994cffb5ff62799b61a).
### Application Features
It's important to understand that Kibo is the system of record for products and inventory, which flow from Kibo to ChannelAdvisor. Meanwhile, ChannelAdvisor aggregates orders from your marketplace and passes them to Kibo for fulfillment. Shipment updates made in Kibo will send details like the tracking number and carrier to ChannelAdvisor, which then relays it to the associated marketplace to share with the customer.
The application maintains these connections with the following features:
* Map sites on your tenant to one or many ChannelAdvisor marketplaces.
* Automatically send the following data to ChannelAdvisor whenever changes are made in Kibo:
* Product creates, updates, or deletes
* Inventory changes
* Order status changes
* Schedule regular order imports from ChannelAdvisor to ensure timely fulfillment.
## Install the App
For assistance installing the application, please reach out to your SI partner or Kibo's professional services and enablement team.
## Configuration Requirements
Before you use the application, ensure you have the following requirements:
* The ChannelAdvisor Application must be installed on your tenant.
* You must have a ChannelAdvisor developer account.
## Configure the Application
Once the application is installed, you will need to configure the mappings and sync process between ChannelAdvisor and Kibo. You can set up different configurations for specific sites on the same tenant if needed.
1. In Admin, go to **System** > **Customization** > **Applications**.
2. Click the **ChannelAdvisorOmsConnector** app.
3. Click **Configure Application** in the top right. This will open a modal displaying a list of existing site configurations, if any.
4. Click **Create a new Site Configuration**.
5. Ensure the **Kibo Tenant** field is prepopulated with the current tenant ID.
6. Enter a **Kibo Site** ID for site-specific settings, or enter "All" if you want to use the same configurations across all sites on your tenant. If you choose All, you will still be able to map specific ChannelAdvisor channels to specific Kibo sites.
7. Expand the **Channel Advisor Settings** tab.
8. Enter your **Channel Advisor Refresh Token**. You typically generate this within the [developer console](https://api.channeladvisor.com/DeveloperConsole/Account/DevLogin) according to [ChannelAdvisor's documentation](https://knowledge.channeladvisor.com/kc?id=kb_article_view\&sys_kb_id=f2139601339696905ee4e7382e5c7bc3).
9. Enter the **Kibo Catalog Site Id** that you want to use as the source for the product catalog. This is required for syncing products and their associated pricing from Kibo to ChannelAdvisor.
10. In the table below, use the dropdown menus to map each ChannelAdvisor **Channel** to their corresponding **Kibo Site** and **Distribution Center**. These mappings dictate inventory sources/destinations and order routing. Use meaningful Kibo Site names that help you identify their purpose, such as those that align with the channel or fulfillment center.
* For example, you may map the Kibo site "Amazon Fulfillment" to the ChannelAdvisor channel "Amazon Seller Central" and the ChannelAdvisor distribution center "Primary DC." The inventory sync respects these mappings, meaning that inventory updates on Amazon Fulfillment will update that DC linked to the Amazon Seller Central channel.
* After making a row of selections, click the **plus** button on the right to add it to the table. Remove existing mappings with the trash button if needed.
11. In the **Workflows** section, check the boxes to enable the order, product, and inventory synchronizations that you want automatically performed. Kibo recommends using all of these, but you can also initiate syncs manually if needed.
* Orders created in ChannelAdvisor will be automatically synced into Kibo after a few minutes if the sync job is enabled. The order's External ID displayed in Kibo will match its ChannelAdvisor ID.
12. To **Schedule** a sync, enter its desired frequency using standard cron syntax (such as `0 */15 * * * *` to run every 15 minutes). Leave blank if you only plan to run that sync manually.
13. In the Shipping Methods section, click **Add Shipping Method**.
14. Map a ChannelAdvisor **Shipping Class** to its corresponding [Kibo Shipping Method Code](/pages/shipping-method-codes) and repeat for all necessary shipping methods. This is required if you plan to fulfill orders with Kibo. Remove any mappings with the trash button if needed.
15. Click **Save Changes**.
Once created, you can edit these site configurations again by clicking **Edit/View** from the initial site configurations page.
## Configure Product Attribute
In order to sync a product, you must create a ChannelAdvisor Label product attribute for it. When product data syncs from Kibo to ChannelAdvisor, the value assigned to this attribute is used to populate the "Label" field within ChannelAdvisor. These labels act as tags that help you categorize products and control which are listed on specific marketplaces.
By assigning a value like "Amazon-Marketplace-US" to this attribute in Kibo, ChannelAdvisor will tag that product with the "Amazon-Marketplace-US" label, which can then be used in ChannelAdvisor rules or templates to push that product to your Amazon storefront.
Follow the instructions in the [Property Attributes documentation](/pages/property-attributes) to set the `channeladvisorlabel` attribute with appropriate values for the channel labels you want to use on products.
## Product Synchronization
Your product catalog originates in Kibo and is synchronized with the below file upload process. The connector application ensures this data is accurately reflected in ChannelAdvisor, as long as the label attribute has a value assigned on the product.
1. **Export from Kibo**: Scheduled jobs (`channelAdvisorProductStartSyncJob` and `channelAdvisorProductFinishSyncJob`) trigger a product export from Kibo, referencing the Catalog Site ID specified in the configuration for product and pricing data.
2. **Process and Format**: The connector retrieves the exported Kibo product data, filters by products with a value for the `channeladvisorlabel` attribute, maps fields (including label values) to ChannelAdvisor's template, and generates a CSV.
3. **Upload to ChannelAdvisor**: The connector uploads the CSV to ChannelAdvisor for processing. ChannelAdvisor uses the label information in the file to tag the products accordingly.
The initial export syncs all designated products upon application installation. Subsequent syncs are typically incremental updates. For very large catalogs, discuss FTP options with ChannelAdvisor Support if needed.
## Inventory Synchronization
Inventory levels originate in Kibo and are synchronized with scheduled file uploads and real-time API updates. For a file upload:
1. The `inventorySync` workflow exports inventory from mapped Kibo Sites, such as Amazon Fulfillment.
2. These exports are configured to output to an S3 bucket.
3. The connector processes data, associates quantities with the correct ChannelAdvisor distribution center based on your mappings, and uploads the file.
For real-time API updates:
1. The `inventorySync` workflow listens for Kibo inventory events (such as InStock and OutofStock) on your Kibo Sites.
2. Upon receiving an event, it fetches the current inventory level for the specific product from Kibo and makes an API call to update the quantity in the site's mapped ChannelAdvisor distribution center.
## Order Synchronization
The following example shows how orders are synchronized and fulfilled.
1. **Order Placed**: The customer places an order on Amazon.
2. **Order in ChannelAdvisor**: ChannelAdvisor imports the order from the "Amazon Seller Central" channel.
3. **Connector Polls**: The `channelAdvisorOrderSync` job finds the new Ready order.
4. **Connector Retrieves and Maps**: The connector retrieves order details and uses mapping configurations to determine the destination Kibo Site ("Amazon Fulfillment").
5. **Order Created in Kibo**: An order is created in the Amazon Fulfillment site on Kibo.
6. **Order Acknowledged**: ChannelAdvisor marks the order as "Exported."
7. **Fulfillment in Kibo**: The order appears in Kibo's Order Admin UI under the Amazon Fulfillment site for processing.
8. **Shipment Update**: Shipping updates in Kibo (such as moving into the Fulfilled shipment status) trigger the connector to send shipping details to ChannelAdvisor, which creates corresponding shipment records and then relays it to Amazon.
Cancellations and returns flow bidirectionally between Kibo and ChannelAdvisor to keep order statuses synchronized. These will require [additional webhook configuration](https://knowledge.channeladvisor.com/kc?id=kb_article_view\&sys_kb_id=e31d9f891bd5d1d42d9eea40604bcb2f) to enable the "cancelled finalized" and "refund finalized" events.
The `channelAdvisorOrderSync` job listens for these events originating in either Kibo or ChannelAdvisor and will perform the corresponding action in the other platform to synchronize order records.
## Manual Sync and Monitoring
If you are not automatically syncing products or orders from ChannelAdvisor or if you want to sync data in between scheduled imports, you can force a sync from the application configurations:
1. In the application configuration modal, click the site configuration.
2. In the **Workflows** section, click the play button to the right of the appropriate sync job.
3. Click **Run** in the pop-up that appears to confirm the action.
To check the progress of a sync, click the history button to the left of the play button shown above. This will display a log of all events with their status (Success or Failure).
If you encounter a system outage or an error with the initial export, you might need to repeat the export process. Be sure to check the error log and resolve any issues before re-exporting data.
### View Product Inventory in ChannelAdvisor
After a sync, the current inventory of the product will be updated in the ChannelAdvisor products table. Note that any configurable parent products won't display inventory or pricing, as those values are tracked on their child variants instead.
## Enable the App
Complete the following steps to enable the ChannelAdvisor application:
1. In Admin, go to **System** > **Customization** > **Applications**.
2. Click the **ChannelAdvisorOmsConnector** app.
3. Toggle on **Enable App** in the top right.
You can now sell your products on third-party marketplaces through ChannelAdvisor.
# Checkout Pages (After)
Source: https://docs.kibocommerce.com/pages/checkout-pages-after
This action manipulates the HTTP request or response after a Checkout page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.checkout.request.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Checkout Pages (Before)
Source: https://docs.kibocommerce.com/pages/checkout-pages-before
This action manipulates the HTTP request or response before a Checkout page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.checkout.request.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create From Cart (After)
Source: https://docs.kibocommerce.com/pages/checkouts-create-from-cart-after
**Related API:** This extension modifies the [Create Checkout From Cart](/api-reference/checkout/create-checkout-from-cart) operation.
This action occurs after a checkout is created from the cart. Changes made to the order items in this action persist in Kibo.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.checkouts.createFromCart.after |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = _function_(_context_, _callback_) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Checkout
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that creates checkouts from the cart.
## Get
### get.checkout
Obtains a response that includes information about the current checkout.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.checkout();
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setItemAllocation
Sets soft allocation information on an order item.
| Parameter | Type | Description |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the order item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for an order item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setAttribute
Sets an attribute from the checkout.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute Must apply to an existing attribute. |
| value | object | Value or values to set on for the specified attribute. |
Example:
```
context.exec.setAttribute("attributeName", value);
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeAttribute
Removes an attribute from the checkout.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute. Must apply to an existing attribute. |
Example:
```
context.exec.removeAttribute("attributeName");
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setData
Sets custom key/value data on the current checkout.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------- |
| key | string | Key of the data to set on the checkout. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the current checkout.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from checkout. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on an order item.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| key | string | Key of the data to set on the order item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the order item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from an order item.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the order item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from an order item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setDutyAmount
Sets the duty amount applied to a checkout.
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------- |
| dutyAmount | number | The duty amount to set. |
| groupId | string | The checkout group, if applicable. |
Example:
```
context.exec.setDutyAmount(8, group1);
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create From Cart (Before)
Source: https://docs.kibocommerce.com/pages/checkouts-create-from-cart-before
**Related API:** This extension modifies the [Create Checkout From Cart](/api-reference/checkout/create-checkout-from-cart) operation.
This action occurs before a checkout is created from the cart. Changes made to the order items in this action persist in Kibo.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.checkouts.createFromCart.before |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = _function_(_context_, _callback_) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Checkout
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that creates checkouts from the cart.
## Get
### get.checkout
Obtains a response that includes information about the current checkout.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.checkout();
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setItemAllocation
Sets soft allocation information on an order item.
| Parameter | Type | Description |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the order item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for an order item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setAttribute
Sets an attribute from the checkout.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute Must apply to an existing attribute. |
| value | object | Value or values to set on for the specified attribute. |
Example:
```
context.exec.setAttribute("attributeName", value);
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeAttribute
Removes an attribute from the checkout.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute. Must apply to an existing attribute. |
Example:
```
context.exec.removeAttribute("attributeName");
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setData
Sets custom key/value data on the current checkout.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------- |
| key | string | Key of the data to set on the checkout. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the current checkout.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from checkout. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on an order item.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| key | string | Key of the data to set on the order item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the order item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from an order item.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the order item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from an order item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setDutyAmount
Sets the duty amount applied to a checkout.
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------- |
| dutyAmount | number | The duty amount to set. |
| groupId | string | The checkout group, if applicable. |
Example:
```
context.exec.setDutyAmount(8, group1);
```
Response:
```
{
"id": "string",
"siteId": 0,
"tenantId": 0,
"number": 0,
"originalCartId": "string",
"submittedDate": "2025-02-18T02:41:59.345Z",
"type": "string",
"items": [
{
"id": "string",
"destinationId": "string",
"originalCartItemId": "string",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"dutyAmount": 0,
"expectedDeliveryDate": "2025-02-18T02:41:59.345Z",
"subscription": {
"required": true,
"frequency": {
"unit": "string",
"value": 0
},
"trial": {
"enabled": true,
"duration": 0,
"substituteProductCode": "string",
"substituteProductQuantity": 0,
"substituteVariationProductCode": "string",
"substituteProductOptions": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
]
}
},
"isReservationEnabled": true,
"giftInfo": {
"isGiftItem": true,
"giftMessage": "string"
},
"priceMode": "string",
"returnRuleInfo": {
"isReturnable": true,
"maxQty": 0,
"maxDays": 0,
"ruleCode": "string"
},
"localeCode": "string",
"purchaseLocation": "string",
"lineId": 0,
"product": {
"mfgPartNumber": "string",
"upc": "string",
"sku": "string",
"fulfillmentTypesSupported": [
"string"
],
"imageAlternateText": "string",
"imageUrl": "string",
"variationProductCode": "string",
"options": [
{
"name": "string",
"attributeFQN": "string",
"dataType": "string",
"stringValue": "string"
}
],
"properties": [
{
"attributeFQN": "string",
"name": "string",
"dataType": "string",
"isMultiValue": true,
"values": [
{
"stringValue": "string"
}
]
}
],
"categories": [
{
"id": 0,
"parent": {}
}
],
"price": {
"price": 0,
"salePrice": 0,
"tenantOverridePrice": 0,
"msrp": 0,
"creditValue": 0,
"priceListCode": "string",
"priceListEntryMode": "string",
"isOverRidePriceSalePrice": true
},
"discountsRestricted": true,
"discountsRestrictedStartDate": "2025-02-18T02:41:59.345Z",
"discountsRestrictedEndDate": "2025-02-18T02:41:59.345Z",
"isRecurring": true,
"isTaxable": true,
"productType": "string",
"productUsage": "string",
"serialNumber": "string",
"condition": "string",
"bundledProducts": [
{
"quantity": 0,
"optionAttributeFQN": "string",
"creditValue": 0,
"deltaPrice": 0,
"imageUrl": "string",
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
}
],
"fulfillmentFields": [
{
"name": "string",
"required": true
}
],
"productCode": "string",
"name": "string",
"description": "string",
"goodsType": "string",
"isPackagedStandAlone": true,
"stock": {
"manageStock": true,
"isOnBackOrder": true,
"availableDate": "2025-02-18T02:41:59.345Z",
"stockAvailable": 0,
"aggregateInventory": 0,
"futureInventories": [
{
"futureInventoryID": 0,
"onhand": 0,
"available": 0,
"allocated": 0,
"pending": 0,
"deliveryDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z"
}
],
"availableFutureInventories": 0,
"totalAvailableStock": 0,
"isSubstitutable": true
},
"productReservationId": 0,
"allocationId": 0,
"allocationExpiration": "2025-02-18T02:41:59.345Z",
"measurements": {
"height": {
"unit": "string",
"value": 0
},
"width": {
"unit": "string",
"value": 0
},
"length": {
"unit": "string",
"value": 0
},
"weight": {
"unit": "string",
"value": 0
}
},
"fulfillmentStatus": "string"
},
"quantity": 0,
"isRecurring": true,
"isTaxable": true,
"subtotal": 0,
"extendedTotal": 0,
"taxableTotal": 0,
"discountTotal": 0,
"discountedTotal": 0,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"feeTotal": 0,
"total": 0,
"unitPrice": {
"extendedAmount": 0,
"listAmount": 0,
"saleAmount": 0,
"overrideAmount": 0
},
"productDiscount": {
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"productDiscounts": [
{
"appliesToSalePrice": true,
"discountQuantity": 0,
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
},
"discountQuantity": 0,
"impactPerUnit": 0
}
],
"data": {},
"taxData": {},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 0,
"totalWithoutWeightedShippingAndHandling": 0,
"weightedOrderTax": 0,
"weightedOrderShipping": 0,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 0,
"weightedOrderHandlingAdjustment": 0,
"autoAddDiscountId": 0,
"isAssemblyRequired": true,
"childItemIds": [
"string"
],
"parentItemId": "string",
"inventoryTags": [
{
"name": "string",
"value": "string"
}
],
"lineItemAdjustment": 0,
"substituteInfo": {
"optIn": "string",
"substituteProductCode": "string",
"substituteVariantCode": "string"
}
}
],
"groupings": [
{
"id": "string",
"destinationId": "string",
"fulfillmentMethod": "string",
"orderItemIds": [
"string"
],
"shippingMethodCode": "string",
"shippingMethodName": "string",
"standaloneGroup": true,
"shippingDiscounts": [
{
"methodCode": "string",
"discount": {
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
}
],
"handlingDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"dutyAmount": 0,
"dutyTotal": 0,
"shippingAmount": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTax": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingAmount": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTax": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"taxData": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"destinations": [
{
"id": "string",
"destinationContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isDestinationCommercial": true,
"data": {}
}
],
"payments": [
{
"id": "string",
"groupId": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"paymentServiceTransactionId": "string",
"availableActions": [
"string"
],
"orderId": "string",
"paymentType": "string",
"paymentWorkflow": "string",
"externalTransactionId": "string",
"billingInfo": {
"paymentType": "string",
"paymentWorkflow": "string",
"billingContact": {
"id": 0,
"email": "string",
"firstName": "string",
"middleNameOrInitial": "string",
"lastNameOrSurname": "string",
"companyOrOrganization": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
},
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"cityOrTown": "string",
"stateOrProvince": "string",
"postalOrZipCode": "string",
"countryCode": "string",
"addressType": "string",
"isValidated": true
}
},
"isSameBillingShippingAddress": true,
"card": {
"paymentServiceCardId": "string",
"isUsedRecurring": true,
"nameOnCard": "string",
"isCardInfoSaved": true,
"isTokenized": true,
"ccLastFour": "string",
"paymentOrCardType": "string",
"cardNumberPartOrMask": "string",
"expireMonth": 0,
"expireYear": 0,
"bin": "string"
},
"token": {
"paymentServiceTokenId": "string",
"type": "string"
},
"purchaseOrder": {
"purchaseOrderNumber": "string",
"paymentTerm": {
"code": "string",
"description": "string"
},
"customFields": [
{
"code": "string",
"label": "string",
"value": "string"
}
]
},
"check": {
"checkNumber": "string"
},
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"storeCreditCode": "string",
"storeCreditType": "string",
"customCreditType": "string",
"externalTransactionId": "string",
"isRecurring": true,
"recurringTransactionId": "string",
"data": {}
},
"data": {},
"status": "string",
"subPayments": [
{
"status": "string",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"amountRefunded": 0,
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
}
}
],
"interactions": [
{
"id": "string",
"gatewayInteractionId": 0,
"paymentId": "string",
"orderId": "string",
"target": {
"targetType": "string",
"targetId": "string",
"targetNumber": 0
},
"currencyCode": "string",
"interactionType": "string",
"checkNumber": "string",
"status": "string",
"paymentEntryStatus": "string",
"isRecurring": true,
"isManual": true,
"isPending": true,
"gatewayTransactionId": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayResponseData": [
{
"key": "string",
"value": "string"
}
],
"paymentTransactionInteractionIdReference": 0,
"amount": 0,
"note": "string",
"interactionDate": "2025-02-18T02:41:59.345Z",
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"returnId": "string",
"refundId": "string",
"capturableShipmentsSummary": [
{
"shipmentNumber": 0,
"shipmentTotal": 0,
"amountApplied": 0
}
]
}
],
"isRecurring": true,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 0,
"changeMessages": [
{
"id": "string",
"correlationId": "string",
"userId": "string",
"userFirstName": "string",
"userLastName": "string",
"userScopeType": "string",
"appId": "string",
"appKey": "string",
"appName": "string",
"subjectType": "string",
"success": true,
"identifier": "string",
"subject": "string",
"verb": "string",
"message": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"attributes": {}
}
],
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"gatewayGiftCard": {
"id": "string",
"cardNumber": "string",
"cardPin": "string",
"amount": 0,
"currencyCode": "string"
},
"installmentPlanCode": "string"
}
],
"amountRemainingForPayment": 0,
"acceptsMarketing": true,
"customerAccountId": 0,
"email": "string",
"alternateContact": {
"firstName": "string",
"lastNameOrSurname": "string",
"emailAddress": "string",
"phoneNumber": "string"
},
"customerTaxId": "string",
"isTaxExempt": true,
"currencyCode": "string",
"priceListCode": "string",
"attributes": [
{
"auditInfo": {
"updateDate": "2025-02-18T02:41:59.345Z",
"createDate": "2025-02-18T02:41:59.345Z",
"updateBy": "string",
"createBy": "string"
},
"fullyQualifiedName": "string",
"attributeDefinitionId": 0,
"values": [
null
]
}
],
"shopperNotes": {
"giftMessage": "string",
"comments": "string",
"deliveryInstructions": "string"
},
"availableActions": [
"string"
],
"data": {},
"taxData": {},
"channelCode": "string",
"locationCode": "string",
"ipAddress": "string",
"sourceDevice": "string",
"visitId": "string",
"webSessionId": "string",
"customerInteractionType": "string",
"orderDiscounts": [
{
"impact": 0,
"discount": {
"id": 0,
"name": "string",
"itemIds": [
"string"
],
"expirationDate": "2025-02-18T02:41:59.345Z",
"hasMultipleTargetProducts": true
},
"couponCode": "string",
"excluded": true,
"data": {}
}
],
"couponCodes": [
"string"
],
"invalidCoupons": [
{
"couponCode": "string",
"reasonCode": 0,
"reason": "string",
"createDate": "2025-02-18T02:41:59.345Z",
"discountId": 0
}
],
"suggestedDiscounts": [
{
"productCode": "string",
"autoAdd": true,
"discountId": 0,
"hasMultipleProducts": true,
"hasOptions": true
}
],
"discountThresholdMessages": [
{
"discountId": 0,
"message": "string",
"thresholdValue": 0,
"showOnCheckout": true,
"showInCart": true,
"requiresCouponCode": true
}
],
"dutyTotal": 0,
"feeTotal": 0,
"subTotal": 0,
"itemLevelProductDiscountTotal": 0,
"orderLevelProductDiscountTotal": 0,
"itemTaxTotal": 0,
"itemTotal": 0,
"shippingSubTotal": 0,
"itemLevelShippingDiscountTotal": 0,
"orderLevelShippingDiscountTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"handlingSubTotal": 0,
"itemLevelHandlingDiscountTotal": 0,
"orderLevelHandlingDiscountTotal": 0,
"handlingTaxTotal": 0,
"handlingTotal": 0,
"total": 0
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Child Shipment Number View
Source: https://docs.kibocommerce.com/pages/child-shipment-number-view
The Child Shipment Number view allows a parent shipment to be connected to one or more child shipments.
The measures calculated by this view are:
| Name | Measure Type | Description |
| --------------------------- | ------------ | ------------------------------------------- |
| Child Shipment Number Count | Count | Count of all child shipment number records. |
The dimensions included in this view are:
| Name | Data Type | Description |
| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
| Child Shipment Number | String | Identifier for the child shipment. |
| Child Shipment Number Created Date | Datetime | The timestamp of the date and time the child shipment number was created within the system. |
| Child Shipment Number Updated Date | Datetime | The timestamp of the date and time the child shipment number was updated within the system. |
| Site ID | Number | Unique identifier for the site. |
# Close a Return
Source: https://docs.kibocommerce.com/pages/close-a-return
Close a return by canceling or rejecting it:
Understand return processing and reverse logistics
1. Go to **Main** > **Orders** > **Returns**.
2. Click the return you want to cancel or reject.
3. In the **Items** tab, click the **Close** drop-down menu.
4. Choose to **Cancel** or **Reject** the return.
## Cancelled Return Limitations
After a return has been cancelled, you will be unable to perform the following actions on it:
* Receive Package
* Print Return Label
* Resend Email
* Refund to New Gift Card
## Rejected Item Quantity
Note that when a return is rejected, those items are no longer considered "returnable" on the order. Where the Returns tab of order details lists item quantities, items will be moved from the Qty Returnable column to the Qty Rejected column after a return is rejected. This means that a new return will not be able to be made for that quantity.
# Cloud Event Notification Services
Source: https://docs.kibocommerce.com/pages/cloud-event-notification-services
Cloud Event Notification services offer an alternative to webhooks for receiving event messages. There are two cloud services to configure with your Kibo application.
1. Google Cloud Platform
2. AWS EventBridge
The configuration process within Kibo is similar to setting up a webhook listener. Cloud services use a platform-specific URL instead of an HTTP URL.
## Google Cloud Platform
This section explains how to configure Google Cloud Platform (GCP) with the Kibo application.
### Prerequisites
To configure GCP, you must have the following:
* **GCP Account:** Ensure you have an active Google Cloud Platform (GCP) account.
* **GCP Pub/Sub Topic:** Create a Pub/Sub topic for handling event notifications.
#### Set Up GCP Pub/Sub Topic
To create a Pub/Sub topic, follow the [Google Cloud](https://cloud.google.com/pubsub/docs/create-topic) instructions. Once your GCP Pub/Sub topic is created, grant publish permissions to Kibo’s Google Cloud Platform account. Use the following email to provide permissions at [events@kibocommerce-public.iam.gserviceaccount.com](mailto:events@kibocommerce-public.iam.gserviceaccount.com).
### Application Configuration
To configure cloud event notifications for your Kibo application, follow these steps:
1. Log in to the Kibo [Dev Center](http://developer.mozu.com/login).
2. Subscribe to events in the Kibo application. See the [Subscribe to Events](/pages/get-started-with-applications#subscribe-to-events) topic for more details on the subscription steps.
3. In the “URL” field, enter the URI in the following format:`gcppubsub://{gcp-project-id}/{gcp-topic-id}`
* Example: `gcppubsub://my-gcp-project/my-pub-sub-topic`
4. Install the configured Kibo application to the desired tenant. See the [Install the Application](/pages/get-started-with-applications#install-the-application) topic for more details on the installation steps.
5. Make sure you enable the installed application to activate event notifications.
#### Event Message Structure
The event message is an object that contains `data` and `attributes` properties.
* The `data` property is an object identical to the body of the webhook event as described in the [Webhooks](/api-overviews/openapi_event_overview) documentation.
* The `attributes` property is an object that matches the headers present in the [Webhooks](/api-overviews/openapi_event_overview) documentation.
See this example for the event message structure:
```
{
"data": {
"eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"topic": "product.created",
"entityId": "shoe",
"timestamp": "2024-05-17T19:14:36.478Z",
"correlationId": "guid",
"isTest": false
},
"attributes": {
"tenantId": "12345",
"siteId": "1235",
"masterCatalogId": "1",
"catalogId": "1",
"currencyCode": "usd",
"priceListCode": "savings",
"pricePlanCode": "savings",
"purchaseLocation": "10",
"correlationId": "guid",
"localeCode": "en-US"
}
}
```
## AWS EventBridge
This section explains how to configure AWS EventBridge with the Kibo application.
### Prerequisites
To configure AWS EventBridge, you must have the following:
* **AWS Account:** Ensure you have an active AWS account.
* **AWS Event Bus:** Create an Event Bus in AWS for handling event notifications.
#### Set Up AWS Event Bus
To create an AWS Event Bus follow the [AWS](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-event-bus) instructions. Once your AWS Event Bus is created, grant "PutEvents" permission to Kibo’s AWS account.
Use the following policy example to configure cross-account permissions:
```
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "KiboCrossAccountPublish",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::812040210293:root"
},
"Action": "events:PutEvents",
"Resource": "arn:aws:events:us-east-1:{MY_AWS_ACCOUNT_ID}:event-bus/{MY_EVENT_BUS_NAME}"
}]
}
```
### Application Configuration
To configure AWS EventBridge with your Kibo application, follow these steps:
1. Log in to the Kibo [Dev Center](http://developer.mozu.com/login).
2. Subscribe to events in the Kibo application. See this [Subscribe to Events](/pages/get-started-with-applications#subscribe-to-events) topic for more details on the subscription steps.
3. In the “URL” field, enter the ARN in the following format: `awseventbridge://{aws-event-bus-arn}`.
* For example: `awseventbridge://arn:aws:events:us-east-1:123:event-bus/central-event-bus.`
4. Install the configured Kibo application to the desired tenant. See [Install the Application](/pages/get-started-with-applications#install-the-application) topic for more details on the installation steps.
5. Make sure you enable the installed application to activate event notifications.
#### Event Message Structure
The event message is an object in the AWS EventBridge structure. Refer to the [AWS EventBridge](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ev-events) documentation for more details. The AWS EventBridge structure includes the following important fields.
* The `detail-type`field matches the Kibo event topic for which the subscription was created (e.g., "product.updated").
* The `source` field should be "com.kibocommerce".
* The `detail` property contains two objects `data` and `attributes`.
* The `data` property is an object identical to the body of the webhook event as described in the [Webhooks](/api-overviews/openapi_event_overview) documentation.
* The `attributes` property matches the headers present in the [Webhooks](/api-overviews/openapi_event_overview) documentation.
See this example for the event message structure:
```
{
"detail-type": "event.topic", // This matches the Kibo topic, such as "product.updated"
"source": "com.kibocommerce",
"detail": {
"data": {
"eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"topic": "product.created",
"entityId": "shoe",
"timestamp": "2024-05-17T19:14:36.478Z",
"correlationId": "guid",
"isTest": false
},
"attributes": {
"tenantId": "string",
"siteId": "string",
"masterCatalogId": "string",
"catalogId": "string",
"currencyCode": "string",
"priceListCode": "string",
"pricePlanCode": "string",
"purchaseLocation": "string",
"correlationId": "string",
"localeCode": "string"
}
},
"version": "0",
"id": "17793124-05d4-b198-2fde-7ededc63b103",
"account": "111122223333",
"time": "2021-11-12T00:00:00Z",
"region": "ca-central-1",
"resources": [
"arn:aws:s3:::DOC-EXAMPLE-BUCKET1"
]
}
```
# Access Management
Source: https://docs.kibocommerce.com/pages/cms-access-management
Learn how access to Kibo CMS is controlled through Kibo account roles.
Access to Kibo CMS is managed through your Kibo account. Users log into Kibo CMS using their existing Kibo credentials — there are no separate CMS user accounts to provision or manage within the CMS.
## Role Mapping
Kibo account roles are automatically mapped to Kibo CMS access levels:
| Kibo Role | CMS Access Level |
| --------------- | ---------------- |
| SuperAdmin | Full Access |
| Admin | Full Access |
| Content Manager | Full Access |
| Content Editor | Editor |
| Content Viewer | Viewer |
## Access Levels
* **Full Access** — Can create, edit, publish, and unpublish all content entries, pages, and assets. Can also manage content models and tenant settings.
* **Editor** — Can create and edit content entries and pages, with limited access to publishing workflows and administrative settings.
* **Viewer** — Read-only access to content entries and pages. Cannot create, edit, or publish.
Role assignments are managed through the Kibo platform, not within Kibo CMS. Contact your Kibo administrator to request a role change.
# Add Validator to Fields
Source: https://docs.kibocommerce.com/pages/cms-add-validator-to-fields
Learn how to add a validator to a content model's field in Kibo CMS.
A field validator helps you ensure the user input meets specific requirements and matches the expected format for a field.
In this tutorial, we will learn how to add validators to a content model's fields.
As an example, we will add validators to the **LONG TEXT** and **NUMBER** fields used in the **Product** content model that we created in the [Create Content Model](/pages/cms-create-content-model) tutorial.
## Step 1: Add `Required` and `Min length` validators to a LONG TEXT field
In this step we will:
* make the **Description** field required.
* set the minimum length for the input the **Description** field to **20 characters**.
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
2. Hover over the **Product** content model.
3. Click **Edit**.
> Screen to configure the **Product** content model's fields opens.
4. Click the **Edit Field** icon on the **Description** field.
> **Field Settings - Long Text** screen opens.
5. Click the **Validations** tab.
6. Enable the **Required** validation by toggling the **Enabled** button. This will make the **Description** field mandatory.
> **Message** textbox will appear to set the error message.
7. In the **Message** textbox, type **Please enter the product description**.
8. Enable the **Min length** validation by toggling the **Enabled** button.
> **Message** and **Value** textboxes will appear to set the error message and minimum value.
9. In the **Message** textbox, type **Description cannot be less than 20 characters**.
10. In the **Value** textbox, type **20**.
11. Click **Save Field**.
> Screen to configure the **Product** content model's fields opens.
12. Click **Save**.
> The message "Your content model was saved successfully!" displays.
## Step 2: Test the validators
1. On the screen to configure the **Product** content model's fields, click the **Preview** tab.
2. Click the **Description** textbox.
3. Click anywhere outside the **Description** textbox.
> The message "Please enter the product description" appears.
4. In the **Description** textbox, type **Top sweatshirt**.
5. Click anywhere outside the **Description** textbox.
> The message "Description cannot be less than 20 characters" appears.
# Clone Content Model
Source: https://docs.kibocommerce.com/pages/cms-clone-content-model
Learn how to clone a content model in Kibo CMS.
Kibo CMS allows you to create a new content model by cloning an existing content model. All the fields, validations, and other settings are copied over from the original content model to the clone content model.
In this tutorial, we will learn how to clone a content model. As an example, we will create a content model with the following attributes by cloning an existing content model:
| Attribute | Value |
| :---------- | :------------------------------------------------------------ |
| Name | **Virtual Product** |
| Group | **E-Commerce** |
| Description | **Demo Virtual Product Content Model for E-Commerce project** |
## Prerequisites
To follow this tutorial, you need the **Product** content model to clone it.
If you don't have the **Product** content model, please follow the [Create Content Model](/pages/cms-create-content-model) tutorial to create it.
## Clone Content Model
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
2. Click the **Kebab Menu Icon** ( ⁝ ) on the **Product** content model.
> Menu opens with **Clone**, **Export**, and **Delete** options.
3. Click **Clone**.
> The **Clone Content Model** screen opens.
4. In the **Name** textbox, type **Virtual Product**.
5. In the **Singular API Name** textbox, type **VirtualProduct**.
6. In the **Plural API Name** textbox, type **VirtualProducts**.
7. In the **Content model group** drop-down, if you have the **E-Commerce** group, click it, else click **Ungrouped**.
8. In the **Icon** dropdown, click **globe** icon.
9. In the **Description** textbox, type **Demo Virtual Product Content Model for E-Commerce project**.
10. Click **+ Clone**.
> **Virtual Product** content model is created.
# Content Entry Revisions
Source: https://docs.kibocommerce.com/pages/cms-content-entry-revisions
Learn how to publish a specific version of a content entry, and create a new version of a content entry by deriving from a previous revision.
In Kibo CMS, each modification in a content entry that is saved or published is stored as a separate revision.
In this tutorial, we will learn how to create multiple revisions of a content entry and publish a specific revision.
We will also learn how to create a new content entry version from a previous revision.
As an example, we will use the **Product** content model that we created in the [Create Content Model](/pages/cms-create-content-model) tutorial.
We will do this in 3 steps:
* Step 1: Create a content entry in the **Product** content model and make multiple revisions.
* Step 2: Publish a previous revision of the content entry.
* Step 3: Create a new content entry version from a previous revision.
## Step 1: Create a Content Entry and Its Revisions
If you are not familiar with how to create a content entry, please follow the [Create Content Entry](/pages/cms-create-content-entry) tutorial.
1. Create a content entry in the **Product** content model with the following attributes:
| Field | Value |
| :---------- | :---------------------------------------------------------------- |
| Name | **Men's Blue T-Shirt** |
| Description | **Half Sleeved, Regular fit, Cotton blend, Blue T-shirt for Men** |
| Price | **15** |
| Category | **Clothes** |
**Note**: If you haven't added the **Category** field to the **Product** content model, skip it (or add it by following the [Reference Field](/pages/cms-reference-field) tutorial).
2. Now, update the **Name** and **Description** textboxes with the following values:
| Field | Value |
| :---------- | :----------------------------------------------------------------------- |
| Name | **Men's Solid Blue T-Shirt** |
| Description | **Half Sleeved, Regular fit, Cotton blend, Solid, Blue T-shirt for Men** |
3. Click **SAVE & PUBLISH**.
**Note**: Clicking **SAVE** will create a new version of the content entry with updated field values and save it as a draft.
Whereas clicking **SAVE & PUBLISH** will create a new version and publish it.
4. Create another revision by updating the **Name** and **Description** textboxes with the following values:
| Field | Value |
| :---------- | :----------------------------------------------------------------------------------- |
| Name | **Men's Solid Round Neck Blue T-Shirt** |
| Description | **Round Neck, Half Sleeved, Regular fit, Cotton blend, Solid, Blue T-shirt for Men** |
5. Click **SAVE & PUBLISH**.
## Step 2: Publish a Previous Revision
1. In the **Men's Round Neck Solid Blue T-Shirt** content entry, click the **Kebab Menu Icon** ( ⁝ ).
> Menu opens with **Trash Entry**, **Schedule unpublish**, and **Show entry revisions** options.
2. Click **Show entry revisions**.
> The **Entry revisions** section opens.
3. To publish the previous **Men's Solid Blue T-Shirt** revision, click the **Kebab Menu Icon** on it ( ⁝ ).
> Menu opens with **New revision from current** and **Publish revision** options.
4. Click **Publish revision**.
> The **Publish Product** confirmation screen appears.
5. Click **Yes, publish!**
> The **Men's Solid Blue T-Shirt** revision gets published.
## Step 3: Create a new content entry version from a previous revision
1. In the **Men's Solid Blue T-Shirt** content entry, click the **Kebab Menu Icon** ( ⁝ )
> Menu opens with **Trash Entry**, **Schedule unpublish**, and **Show entry revisions** options.
2. Click **Show entry revisions**.
> The **Entry revisions** section opens.
3. To create a new entry version from the previous **Men's Blue T-Shirt** revision, click the **Kebab Menu Icon** on it ( ⁝ ).
> Menu opens with **New revision from current** and **Publish revision** options.
4. Click **New revision from current**.
> A new draft of the previous **Men's Blue T-Shirt** revision gets created.
**Optional**: Make the desired change(s) in the respective field(s).
5. Click **Save & Publish**.
> The **Publish Product** confirmation screen appears.
6. Click **Yes, publish!**
> A new content entry revision of the **Men's Solid Blue T-Shirt** entry gets published.
# Content Models and Content Entries
Source: https://docs.kibocommerce.com/pages/cms-content-models-and-entries
Understanding the foundation of Kibo CMS — content models and entries.
In this guide, we'll explore the foundational concepts of Kibo CMS: content models and content entries. Understanding these concepts is essential for working with any headless CMS, and Kibo CMS provides a powerful and flexible implementation.
**What you'll learn:**
* What content models are and how they work
* What content entries are
* The relationship between models and entries
## What Are Content Models?
A **content model** is a blueprint or schema that defines the structure of your content. Think of it as a template that specifies what fields your content will have and what type of data each field can contain.
Content models are similar to:
* **Database tables** in traditional databases (defining columns and their types)
* **Classes** in object-oriented programming (defining properties and their types)
* **Schemas** in GraphQL (defining types and their fields)
### Example: Blog Post Content Model
Let's say you're building a blog. Your "Blog Post" content model might include:
* **Title** (Text field)
* **Slug** (Text field)
* **Author** (Reference to an Author model)
* **Featured Image** (File field)
* **Body** (Rich text field)
* **Category** (Reference to a Category model)
* **Tags** (Multiple references to a Tag model)
* **Published Date** (DateTime field)
* **Is Featured** (Boolean field)
This model defines the structure, but it doesn't contain any actual blog posts — it just defines what a blog post should look like.
Content models are reusable blueprints. Once you create a "Blog Post" model, you can create
hundreds or thousands of individual blog posts (entries) based on that model.
## What Are Content Entries?
A **content entry** is an instance of a content model — it's the actual content created using the structure defined by the model.
Using our blog post example:
* The **content model** defines what fields a blog post has (title, body, author, etc.)
* Each **content entry** is an actual blog post with real values for those fields
### Example: Blog Post Entries
Based on the "Blog Post" model above, you might have entries like:
**Entry 1:**
* Title: "Getting Started with Kibo CMS"
* Slug: "getting-started-with-kibo-cms"
* Author: "John Doe"
* Body: "In this post, we'll explore..."
* Published Date: "2024-01-15"
**Entry 2:**
* Title: "Advanced Headless CMS Patterns"
* Slug: "advanced-headless-cms-patterns"
* Author: "Jane Smith"
* Body: "Let's dive into advanced patterns..."
* Published Date: "2024-01-20"
Each entry contains actual data that follows the structure defined by the model.
## The Relationship Between Models and Entries
The relationship is straightforward:
```mermaid theme={null}
flowchart TD
model["Content Model
(Blueprint)"]
entries["Content Entries
(Instances)"]
model --> entries
```
* **One model** → **Many entries**
* The model defines the structure
* Entries contain the actual data
Think of it like a form:
* The **model** is the blank form template
* Each **entry** is a filled-out form
Content models are like cookie cutters — they define the shape. Content entries are like the
actual cookies — each one has the same shape but different flavor, size, or decorations.
## Field Types in Kibo CMS
Kibo CMS provides a rich set of field types you can use in your content models:
### Basic Fields
* **Text** — Short text (single line)
* **Long Text** — Multi-line text
* **Rich Text** — Formatted text with headings, lists, links, etc.
* **Number** — Numeric values
* **Boolean** — True/false values
* **DateTime** — Dates and times
### Advanced Fields
* **File** — Upload and reference files (images, PDFs, etc.)
* **Reference** — Link to entries from other models
* **Object** — Nested field groups
* **Dynamic Zone** — Flexible content blocks (great for page builders)
### List Fields
Most field types can be configured as lists (arrays) to store multiple values. For example:
* A list of tags
* Multiple authors
* A gallery of images
## Why This Matters
Understanding content models and entries is crucial because:
1. **Structure First** — You define your content structure (models) before creating content (entries)
2. **Type Safety** — Models ensure your content has the correct structure and data types
3. **API Generation** — Kibo CMS automatically generates GraphQL APIs based on your models
4. **Validation** — Models define validation rules that entries must follow
5. **Reusability** — One model can be used to create thousands of entries
When you create a content model in Kibo CMS, the system automatically generates GraphQL queries
and mutations for creating, reading, updating, and deleting entries. You don't need to write any
backend code.
## Content Models in Practice
In the real world, you might have content models for:
* **E-commerce:** Product, Category, Brand, Review, Order
* **Blog:** Post, Author, Category, Tag, Comment
* **Documentation:** Article, Section, Code Example, Tutorial
* **Marketing:** Landing Page, Feature, Testimonial, Case Study
* **Media:** Video, Podcast, Episode, Playlist
Each of these models would define the structure, and you'd create individual entries for each product, blog post, article, etc.
## Next Steps
Now that you understand the basics of content models and entries, you're ready to:
* [Create your first content model](/pages/cms-create-content-model) through the UI
* [Create a content entry](/pages/cms-create-content-entry) using your model
* Explore [content entry revisions](/pages/cms-content-entry-revisions) to understand how Kibo CMS tracks changes
## Summary
* **Content models** are blueprints that define structure and field types
* **Content entries** are instances containing actual data
* **One model** can have many entries
* Kibo CMS provides rich field types for building flexible content structures
* Models automatically generate GraphQL APIs
# Create Content Entry
Source: https://docs.kibocommerce.com/pages/cms-create-content-entry
Learn how to create a content entry in Kibo CMS.
In the previous tutorial, we learned how to create a [content model](/pages/cms-create-content-model), and
in this tutorial, we will explore how to create a [content entry](/pages/cms-glossary#content-entry).
As an example, we will create a **Product** content entry with the following attributes:
| Field | Value |
| :---------- | :--------------------------------------------- |
| Name | Relaxed Sweatshirt |
| Description | Top sweatshirt fabric made from a cotton blend |
| Price | 10 |
## Prerequisites
To create a content entry, the prerequisite is to have a content model.
If you don't have any content model yet, please follow this [tutorial](/pages/cms-create-content-model) to create a content model.
## Create Content Entry
1. From the **Side Menu**, Click **Content** > **Ungrouped** > **Product**.
> The **Product** content entry screen opens.
> OR
> From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
1. Hover over the **Product** content model.
2. Click **View entries**.
2. Click **+ New Product**.
> The **New Product** entry screen opens.
3. In the **Name** textbox, type **Relaxed Sweatshirt**.
4. In the **Description** textbox, type **Top sweatshirt fabric made from a cotton blend**.
5. In the **Price** textbox, type **10**.
6. Click **Save & Publish**.
> The **Publish Product** confirmation screen appears.
7. Click **Yes, publish!**
> The message "Relaxed Sweatshirt was published successfully!" displays.
Congratulations! You have created your first content entry.
Field validation runs when you publish an entry, not when you save a draft. See [Entry Validation](#entry-validation) below.
## Additional Information
### Entry Validation
Validation rules defined on a content model are enforced when an entry is **published**, not when a draft is saved. Clicking **Save** on a draft entry does not trigger validation, so a required field can be left empty and the draft will still save. This includes a Text field that has both pre-defined values and a required validator.
The required-field check runs only on **Save & Publish**. A draft saved in an incomplete state still appears on the entries page, identified by its `objectId#revision` value rather than by the empty field.
To review or change the rules that are enforced at publish time, see [Field Validation](/pages/cms-create-content-model#field-validation) on the Create Content Model page.
### Content Revision
Every time you save any content entry, a new revision is created. You can see all the content revisions in the **REVISONS** tab.
# Create Content Model
Source: https://docs.kibocommerce.com/pages/cms-create-content-model
Learn how to create a content model in Kibo CMS.
In this tutorial, we will learn how to create a [content model](/pages/cms-glossary#content-model).
As an example, we will create a Product content model with the following fields:
| Field | Field Type |
| :---------- | :--------- |
| Name | Text |
| Description | Long text |
| Price | Number |
Content model creation is a two-step process: in step 1, we will create the model, and in step 2,
we will define model [fields](/pages/cms-glossary#field-field-type).
## Step 1: Create Content Model
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
2. Click **+ New**.
> The **New Content Model** screen opens.
3. In the **Name** textbox, type **Product**.
4. In the **Singular API Name** textbox, type **Product**.
5. In the **Plural API Name** textbox, type **Products**.
6. In the **Content model group** drop-down, if you have already created a group, click that group, else click **Ungrouped**.
7. In the **Icon** dropdown, click the **box** icon.
8. In the **Description** textbox, type **Demo Product Content Model**.
9. Unselect the **Create model with default fields** checkbox.
10. Click **+ Create Model**.
> Screen to configure the **Product** content model's fields opens.
## Step 2: Define fields
1. Drag and drop the **Text** field in the **Edit** tab.
> **Field Settings - Text** screen opens.
2. In the **Label** textbox, type **Name** and click **Save Field**.
3. Drag and drop the **Long Text** field in the **Edit** tab.
> **Field Settings - Long Text** screen opens.
4. In the **Label** textbox, type **Description** and click **Save Field**.
5. Drag and drop the **Number** field in the **Edit** tab.
> **Field Settings - Number** screen opens.
6. In the **Label** textbox, type **Price** and click **Save Field**.
7. Click **Save**.
> The message "Your content model was saved successfully!" displays.
8. Congratulations! You have created your first content model.
## Additional Information
### Field Validation
You can add various validations to a field from the **VALIDATORS** tab on the **Field Settings** screen.
Depending on the field type, you can add different types of validations to your field.
Validators are enforced when an entry is published, not when a draft is saved. A required field can be left empty on a saved draft without raising an error. See [Entry Validation](/pages/cms-create-content-entry#entry-validation) for details.
# Create Content Model Group
Source: https://docs.kibocommerce.com/pages/cms-create-content-model-group
Learn how to create a content model group in Kibo CMS.
Content model groups help in organizing content models. With groups, you can organize your models efficiently.
For example, all the content models related to E-Commerce can be grouped together,
and they will be shown in the side navigation bar under the E-Commerce heading. There are two main uses of
the content model group.
* Organization of content models
* Restrict the content models access scope based on the content model group
In this tutorial, we will learn how to create a content model group.
As an example, we will create a E-Commerce content group with the following values:
| Attribute | Value |
| :---------- | :--------------------- |
| Name | E-Commerce |
| Group icon | shopping-cart |
| Description | E-Commerce Model Group |
1. From the **Side Menu**, Click **Content Modeling** > **Groups**.
> The **Content model groups** screen opens.
2. Click **+ New**.
> The **New content model group** section opens.
3. In the **Name** textbox, type **E-Commerce**.
4. In the **Slug** textbox, type **e-commerce**.
5. In the **Group icon** dropdown, click the **shopping-cart** icon.
6. In the **Description** textbox, type **E-Commerce Model Group**.
7. Click **Save**.
> The message "Content model group saved successfully!" displays.
8. Congratulations! You have created your first content model group.
# Create Page
Source: https://docs.kibocommerce.com/pages/cms-create-page
Learn how to create a page in Kibo CMS Website Builder.
Kibo CMS Website Builder incorporates a drag-and-drop visual editor that allows you to easily create and edit web pages without requiring any coding skills.
In this tutorial, we will learn how to create a Page using the Kibo CMS Website Builder. As an example, we will create a page with the section shown in the image below:
We will do this in 12 steps:
* Step 1: Add a new Page
* Step 2: Add and edit a Box
* Step 3: Add and edit Rich Text
* Step 4: Add and edit a Grid
* Step 5: Add and adjust an Image
* Step 6: Add a complex custom Element
* Step 7: Use the Navigator
* Step 8: Review Settings
* Step 9: Preview the Breakpoints and adjust
* Step 10: Preview
* Step 11: Publish
* Step 12: Organize content in Folders
## Step 1: Add a New Page
1. From the **Side Menu**, click **Kibo CMS Website Builder** > **Pages**.
> The **Pages** screen opens.
2. Click **+ NEW PAGE**.
> The pop-up to select a Page type opens, e.g., Static Page.
3. Add the **Title** of the Page.
> The **Path** is automatically generated.
The path you set must be supported by your frontend application — your storefront must have a route that handles that URL for the page to render correctly. Coordinate with your development team before creating pages at new paths.
4. Click **CREATE**.
> The new Page edit screen appears.
## Step 2: Add and Edit a Box
1. Drag and drop a **Box** Element into the container and click on it to select it.
> The right-side **Element** and **Style** menus now control the selected Box element.
2. Explore the **Style** tab; you can change Layout, Margin & Padding, Background, and control the Visibility of the component.
3. Change the **Background** of the Box.
> The Box changes color in the Page area in the center of the screen.
**Note**: Boxes could be used as building blocks of a Page. A Page may be built with multiple Boxes to group Elements together easily share Style, move around together, or delete in one go. A Box can contain Elements like Grids, Images, Rich Text, etc.
## Step 3: Add and Edit Rich Text
1. Drag and drop a **Rich Text** Element to the Box.
> Placeholder text appears on the Page.
2. Select the text and, using the **Element** tab on the right, add and edit the text as needed. You can also open it in a larger pop-up for precise editing.
> Formatting reflects in the Page preview area.
## Step 4: Add and Edit a Grid
1. Add a **Grid** to the Box element and select it. Note: avoid adding the Grid to the **Main Content** area to keep the same Background and Style, it should be in the Box.
> The Grid shows with sample content in the main Page area.
2. In the **Element** tab layout options, click the **four-column-layout, single-row**.
> The Grid updates content in the main Page area.
3. Drag and drop **Rich Text** Elements into Column 3 and 4.
> Sample text populates in these Cells.
4. Populate and edit the text to explore the Rich Text editor.
**Note**: Grids are also powerful Page building blocks made of one or more Cells. Elements like Images and Rich Text can be placed inside their Cells.
## Step 5: Add and Adjust an Image
1. Drag and drop an **Image** Element.
> Placeholder Image element appears on the Page.
2. Select the Image from the **Element** tab by clicking **SELECT FROM LIBRARY**.
> File Manager screen pops up.
a. Find and click the desired Image.
> Selected asset adds to the Page.
b. OR click **UPLOAD**.
> File explorer opens to select the Image you want to use. Here is the image used in this example:
3. In the **Style** tab of the Image element, click **Layout** and adjust Width to 80%, for example. Then adjust Alignment to centered. Use Margin & Padding as needed.
## Step 6: Add a Complex Custom Element
1. Drag and drop a **Hero #1** element onto the Page.
> Complex element with child components appears.
2. Child elements are not editable in this example, but custom components can specify inputs like button labels, etc so this is completely customizable.
3. Adjust the **Style** for this element and the changes apply to the element as a whole and not to its individual parts.
## Step 7: Use the Navigator
1. From the **Navigator** tab on the left of the Page, click to access structure and components.
> Navigator opens.
2. Click parent Elements to explore children, e.g., Box > Grid > Column (first) > Rich Text.
> Element highlights on the Page for editing so that users can find it quickly and start editing it.
**Note**: Navigator excels for complex Pages with lots of components. Use it for precise selection of composites like Grids. Another way to make a precise selection is to use the bread crumb at the bottom of the screen. It allows you to go up the hierarchy in a single click.
## Step 8: Review Settings
1. Click the **SETTINGS** icon.
> **General Settings** tab in **Page Settings** opens.
2. In **SEO** and **Social** tabs, add info from the content on the Page itself or any test content.
3. Click **SAVE SETTINGS** before closing. Unlike the changes on the Page, which are automatically saved, here the user needs to actually save them to ensure no accidental changes are made.
> Page Settings are updated.
## Step 9: Preview Breakpoints and Adjust
1. At the top of the Page, you have some quick actions, click on the tablet or mobile icon to see how the content will look.
> Center preview updates to different sizes.
2. When you click on the Mobile, you will notice the content in the Grid is not showing properly. The Grid has a built-in functionality that you can use to quickly fix this. Select Grid, **Element** tab, set **Stack at breakpoint** to **Mobile**.
**Note**: Selecting **Tablet** stacks for tablets and all smaller size screens like Mobile automatically.
## Step 10: Preview
1. Click **PREVIEW** in a new tab.
> Page opens in new tab as on Next.js site so that you can check how it will look once published.
## Step 11: Publish
1. Click **PUBLISH**.
> The pop-up will ask you to confirm that you really want to publish this Page.
2. Click **YES, PUBLISH THE PAGE!**.
> Page goes live on website.
## Step 12: Organize Content in Folders
1. On Pages list, click **+ NEW FOLDER**.
> The pop-up will ask you to confirm the Title of the Page and the Slug will automatically be populated.
2. Use top Search to find the relevant records and multi-select the Pages, then use the top menu **Bulk Actions** > **Move** to target Folder, e.g., **Features**.
> A confirmation report in the end of the successful action. If there are any issues with the Move this report will inform you.
**Note**: If you want to build a hierarchy of Folders (nested in other Folders) then you could change the default **Home** location (the root folder) to whatever folder that already exists in your Kibo CMS Website Builder. Organizing your content in Folders can help end users find content quickly and efficiently, but keep in mind the **Search** functionality at the top can also help when looking for the right content.
# Custom Components
Source: https://docs.kibocommerce.com/pages/cms-custom-components
Learn how to add custom components in the Next.js starter kit with Kibo CMS Website Builder.
In this tutorial, we explain how to create, register and use custom components in this Kibo CMS Website Builder project.
* Step 1: Add a React component file
* Step 2: Register the component
* Step 3: Ensure the group matches the one registered
* Step 4: Open the editor to verify the component appears in the chosen group
## Overview
* Custom components live in the `src/editorComponents` folder and are provided to the renderer via `editorComponents` exported from `src/editorComponents/index.tsx`.
* The page renderer (`src/components/DocumentRenderer.tsx`) passes `editorComponents` to `DocumentRenderer` from `@webiny/website-builder-nextjs`.
* Component groups (used in the editor UI) are registered in `src/contentSdk/initializeContentSdk.ts` using `registerComponentGroup`.
## Files to inspect
* `src/editorComponents/index.tsx` — the central list of editor components and input definitions
* `src/components/DocumentRenderer.tsx` — how components are provided to the renderer
* `src/contentSdk/initializeContentSdk.ts` — where component groups are registered
## Step-by-step: Create a new custom component
### Step 1: Add a React component file
Add a React component file under `src/editorComponents` (or a subfolder). In this tutorial we will create `CalloutBox` component.
* Prefer exporting a named component (e.g. `export const CalloutBox = () => { ... }`).
* Keep the component as a standard React functional component.
Example minimal component:
```diff-tsx src/editorComponents/CalloutBox.tsx theme={null}
"use client"
import type { ComponentProps } from "@webiny/website-builder-nextjs";
interface LineProps {
text: string
highlighted: boolean
breakAfter?: boolean
}
type CalloutBoxProps = ComponentProps<{
"line-1": string
"line-2": string
style: 'default' | "primary"
}>
export function CalloutBox({ inputs }: CalloutBoxProps) {
const lines = [
{ text: inputs['line-1'], highlighted: true },
{ text: inputs['line-2'], highlighted: false },
];
return (
{lines.map((line, index) => {
return (
{line.text}
)
})}
)
}
```
### Step 2: Register the component
Define editor inputs and register the component in `src/editorComponents/index.tsx`.
* Use `createComponent` from `@webiny/website-builder-nextjs` to register the component with `name`, `label`, `group` and `inputs`.
* Use input helpers such as `createTextInput`, `createLongTextInput`, `createLexicalInput`, `createFileInput`, `createSelectInput`, `createSlotInput`.
Example registration snippet (add to `src/editorComponents/index.tsx`):
```tsx theme={null}
import {
createComponent,
createTextInput,
createLongTextInput
} from "@webiny/website-builder-nextjs";
import {CalloutBox} from "./CalloutBox";
createComponent(CalloutBox, {
name: "Webiny/CalloutBox",
label: "Callout Box",
group: "basic",
inputs: [
createLongTextInput({
name: "line-1",
label: "Line 1 Text",
defaultValue: "Your Ultimate",
required: true
}),
createLongTextInput({
name: "line-2",
label: "Line 2 Text",
defaultValue: "Headless CMS",
required: true
})
]
}),
```
Notes:
* The `name` property defines the unique editor identifier (used by the editor to save/load the block).
* The `group` should match a component group registered in `src/contentSdk/initializeContentSdk` (e.g., `custom`, `basic`).
**How inputs map to component props**
* When the editor renders the page, the `DocumentRenderer` will render your component and pass the block data as props.
* Typical convention: input names map to prop names. For example, `title` becomes `props.title` inside your component.
* For slot inputs (`createSlotInput`) the renderer will pass an array of nested blocks which you should render using `children` or a dedicated renderer.
### Step 3: Ensure the group matches the one registered
* Component groups (editor categories) are registered in `src/contentSdk/initializeContentSdk.ts` with `registerComponentGroup`.
* Pick an existing group (`basic`, `sample`) or add a new one in `initializeContentSdk.ts`.
In this tutorial, we used an existing group, but if you need to create a new one, for example, a new `Demo Group` add the following to `initializeContentSdk.ts`:
```tsx theme={null}
registerComponentGroup({
name: "demo",
label: "Demo Group",
description: "Demo components"
});
```
Note: the order in which the Component groups show in the Kibo CMS Website Builder depends on the order in which they were added to the file above.
* Keep components presentation-focused; prefer receiving plain data from inputs rather than coupling to editor APIs inside the component.
* For rich text, prefer `createLexicalInput` where content is saved as Lexical nodes and will be rendered by `DocumentRenderer`.
* Use `createSlotInput` to allow nesting arbitrary content inside your block.
* Keep components SSR-friendly. Use client-only code (like browser-only libs) inside a child component or guarded by dynamic import to avoid SSR issues.
### Step 4: Open the editor to verify the component appears in the chosen group and that it is functional.
* Run the site and open a new Page in the editor to verify the component appears in the chosen group.
* Drag and drop the new component in the Page to validate it is functional.
# Kibo CMS Glossary
Source: https://docs.kibocommerce.com/pages/cms-glossary
Learn about the Kibo CMS terminologies.
## Content Model
The first step to storing information in a Kibo CMS is to create your content model.
If you're new to the Kibo CMS world, this term may be unfamiliar to you, but it's simple to understand.
Let's understand the content model with an example.
Let's say you want to store all the products in your shop in a CMS. As a first step, you will need to define all the
product attributes and their types. For example, a product may have the following attributes ([fields](#field-field-type)):
* Name (Text Type)
* Description (Long Text)
* Price (Number)
The collection of these attributes (fields) will be referred to as the "content model."
As per the example above, the Product content model will have three fields: name, description,
and price, with field types of text, long text, and number, respectively.
Below is the actual screenshot of the Kibo CMS user interface for a content model.
## Field / Field Type
As mentioned in the content model section, every content model is a collection of fields, and each field has a type.
The field type defines the kind of content you want to store. Kibo CMS supports the following field types:
| Field Type | Description |
| :---------- | :----------------------------------------------------------------------------------------- |
| `Text` | Titles, names, single line values. |
| `Long text` | Long comments, notes, multi line values. |
| `Rich text` | Text formatting with references and media. |
| `Number` | Store numbers. |
| `Boolean` | Store boolean ("yes" or "no" ) values. |
| `Date/Time` | Store date and time. |
| `Files` | Images, videos and other files. |
| `Reference` | Reference existing content entries. For example, a book can reference one or more authors. |
| `Object` | Store nested data structures. |
## Content Entry
Each record that you store in the content model is a content entry. For example, a new product record
created with the following information is a content entry.
| Field | Value |
| :---------- | :--------------------------------------------- |
| Name | Relaxed Sweatshirt |
| Description | Top sweatshirt fabric made from a cotton blend |
| Price | 10 |
This one record is a content entry, and each content model will contain multiple content entries.
# Import/Export Content Models
Source: https://docs.kibocommerce.com/pages/cms-import-export-content-models
Learn how to import and export content models in Kibo CMS.
Kibo CMS allows you to export all your content models as a JSON file. This is useful if you want to migrate your content models to another project or if you want to share them with other developers.
Similarly, you can use the generated JSON file to import those same content models into your project.
This tutorial will guide you through the process of exporting and importing content models.
## Exporting Content Models
To export one or more content models navigate to your Content Models view inside the Kibo CMS application.
1. From the **Side Menu**, Click **Content Modeling** >**Models**.
> The Content Models screen opens.
2. Click the **Export all models** icon.
> The export action will generate a JSON file containing all your content models.
>
>
## Importing Content Models
To import content models, navigate to your Content Models view inside the Kibo CMS application.
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The Content Models screen opens.
2. Click the **Import models** icon.
> The system will ask you to provide an export file.
>
>
3. Select the file you want to import and click **Validate file**.
> The validation action will check the file and display a list of content models that can be imported.
4. Click the **Model will be skipped** label in front of the title of the Content Models you want to import. From the list you can choose which content model you want to import and which ones you want to skip.
Note that if you select to import a specific content model that references one or more content models that are also part of the export file, the system will automatically select those referenced content models as well. If you wish to skip them, you can just go back and exclude them from the import.
All the content models are grouped in their respective content model groups. Those groups will be automatically created for you upon importing the file if such a group already doesn't exist.
Inside the group section, you will have a list of individual content models that belong to that group. You can select which content models you want to import and which ones you want to skip by clicking the button on the right-hand side.
Also, underneath the content model name you will have a status for the content model. This status tells you if this content model will be `updated` (meaning the content model already exists) or `created` (meaning the content model currently doesn't exist).
5. Finally, once you have selected which content models you want to import. Click Import to start the import process.
> The import process can take a few seconds to finish as it needs to validate all the information. Once the process is done you will see the status screen with the results of the import process.
From the same status screen, you can proceed to import additional content models just by selecting them and clicking the **Import** button again. In case you want to finish the import process, just click outside the content model dialog.
# Kibo CMS Integration Overview
Source: https://docs.kibocommerce.com/pages/cms-integration-overview
How Kibo CMS integrates with the Kibo Composable Commerce Platform — covering architecture, multi-tenancy, commerce data, and content delivery.
Kibo CMS is the content management layer within the Kibo Composable Commerce Platform. It provides headless CMS capabilities and a visual Website Builder alongside Kibo's commerce APIs, enabling teams to manage content and commerce data from a unified platform.
This page explains the key integration points between Kibo CMS and the broader Kibo platform for implementation engineers and solution architects.
## Architecture Overview
Kibo CMS operates as a composable layer that sits alongside the rest of Kibo's commerce services. Content is authored and managed through the Kibo CMS admin interface, then delivered to storefronts and other consumers via a GraphQL API.
The platform consists of three main functional areas:
* **Website Builder** — A visual page editor for building and publishing web pages, including dynamic pages that pull live data from the Kibo Commerce catalog.
* **Headless CMS** — A structured content management system with a GraphQL API, content models, and revision history for managing arbitrary content types.
* **File Manager** — Centralized asset storage and management for images and other media used across pages and content entries.
Kibo CMS is designed to be consumed headlessly. Frontend applications query the GraphQL API to retrieve published content, and the platform does not prescribe a specific rendering framework.
## Multi-Tenant Model
Kibo CMS uses an isolated multi-tenant architecture. Each company or brand is provisioned as its own tenant with a dedicated content space — content, users, roles, and configuration in one tenant are completely isolated from all others.
To provision a new Kibo CMS tenant, raise a support request with Kibo Support. Support will establish the isolated workspace and install default configuration for your company.
## Kibo Commerce Integration
The Kibo CMS Website Builder connects directly to the Kibo Commerce product catalog. This allows content authors to create dynamic pages that render live product and category data rather than static copies.
### Dynamic Page Types
Two dynamic page types are available in the Website Builder:
| Page Type | Label | Commerce Data |
| :----------------- | :----------------- | :------------------------------------------- |
| `kiboProductPage` | Kibo Product Page | Renders product information by `productCode` |
| `kiboCategoryPage` | Kibo Category Page | Renders category browsing by `categoryCode` |
These pages are bound to a specific product or category record at authoring time. In the page editor, authors use built-in product and category pickers to select the record. The picker supports free-text search by product name, product code, category name, or category code.
At render time, the storefront receives the page configuration including the bound product or category identifier, then fetches the corresponding data from the Kibo Commerce API to populate the page.
### Product Data Mapping
When a product is resolved from the Kibo Commerce catalog, the following fields are used by the Website Builder:
| Kibo Commerce Field | Website Builder Mapping |
| :---------------------------------- | :---------------------- |
| `productCode` | `id`, `handle` |
| `content.productName` | `title` |
| `content.productImages[0].imageUrl` | `image.src` |
### Category Data Mapping
When a category is resolved from the Kibo Commerce catalog, the following fields are used:
| Kibo Commerce Field | Website Builder Mapping |
| :----------------------------------- | :---------------------- |
| `categoryCode` | `id` |
| `content.name` | `title` |
| `content.slug` | `handle` |
| `content.categoryImages[0].imageUrl` | `image.src` |
## Content Delivery
Published content from both the Website Builder and Headless CMS is delivered through a **GraphQL API**. Consumer applications — storefronts, mobile apps, or third-party systems — query this API to retrieve content.
Key characteristics of the content delivery API:
* All content is returned as structured JSON via GraphQL queries.
* Published and draft content states are tracked separately; consumers typically query published content only.
* The API supports filtering, sorting, and pagination for content entry lists.
* Responses include revision metadata, enabling consumers to implement caching strategies tied to content version.
## Getting Started
| Resource | Description |
| :-------------------------------------------------------- | :-------------------------------------------------------------------------- |
| [Kibo CMS Overview](/concept-guides/cms-overview) | Introduction to the main capabilities of Kibo CMS |
| [Kibo CMS Glossary](/pages/cms-glossary) | Definitions for content models, fields, entries, and other core concepts |
| [Create a Content Model](/pages/cms-create-content-model) | Step-by-step guide to defining your first content model in the Headless CMS |
# Manage Content Model Settings
Source: https://docs.kibocommerce.com/pages/cms-manage-content-model-settings
Learn how to manage content model settings in Kibo CMS.
In this tutorial, we will learn how to manage a content model general settings.
As an example, we will update the description of **Product** content model that we created in the [Create Content Model](/pages/cms-create-content-model) tutorial.
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
2. Hover over the **Product** content model.
3. Click **Edit**.
> Screen to configure the **Product** content model's fields opens.
4. Click the **Settings** icon.
> The **Content model settings** screen opens.
5. In the **General settings** section, in the **Content model description** textbox, update the text:
from **Demo Product Content Model**
to **Demo Product Content Model for E-Commerce project**.
6. In the **Content model group** drop-down, click **E-Commerce**.
**Note**: Similarly, you can update the **Content model name**, **Content model group**, **Icon**, and **Tags**.
7. Click **Save**.
> Screen to configure the **Product** content model's fields opens with a notification "Content model settings updated successfully."
8. Click **Save**.
> The message "Your content model was saved successfully!" displays.
# Kibo CMS Website Builder - Next.js Starter Kit
Source: https://docs.kibocommerce.com/pages/cms-nextjs-starter-kit
Learn how to integrate our Next.js starter kit with Kibo CMS Website Builder.
Kibo CMS Website Builder incorporates a drag-and-drop visual editor that allows you to use a custom front end of your choice. We recommend Next.js. To get our users up and running as quickly as possible we put together a sample Next.js project.
In this tutorial, we will learn how to link your Kibo CMS project to the [Next.js starter kit](https://github.com/webiny/website-builder-nextjs)
We will do this in a few simple steps:
* Step 1: Fork the Next.js starter kit repository
* Step 2: Switch to the appropriate branch
* Step 3: Create and populate your .env file
* Step 4: Establish connection
* Step 5: Validate connection
* Optional information and actions
## What's Included in the Starter Kit
* TypeScript
* Tailwind CSS
* Sample ecommerce API
* Sample components
* Sample component groups
This project uses [Next.js App Router](https://nextjs.org/docs/app)!
## Step 1: Clone the repository
Use your tools of choice and clone the [Next.js Starter Kit repository](https://github.com/webiny/website-builder-nextjs.git)
> The project structure should be already visible in your editor.
## Step 2: Switch to the appropriate branch
Pick the right branch for your Kibo CMS project! If your Kibo CMS project runs on the latest version, check out the latest branch from this Next.js repo, for example for "Kibo CMS v6.0.0" use the "v6.0.0" branch. If this is not available use the closest matching version and update `@webiny/website-builder-nextjs` in `package.json` in the Next.js project.
## Step 3: Create and populate your .env file
1. Create a new file in your project root called `.env`
2. Add the correct variables from your Kibo CMS project.
A user can find them in the Kibo CMS Admin app, click on the **Support** link in the bottom left corner, and then select **Configure Next.js**. This is a configuration specifically generated for the Kibo CMS Website Builder Next.js starter kit. Simply copy the values in your `.env` file in the Next.js starter kit and SAVE.
> The following environment variables are saved in the `.env` file:
```diff-tsx .env theme={null}
NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY: {YOUR_API_KEY}
NEXT_PUBLIC_WEBSITE_BUILDER_API_HOST: {YOUR_API_HOST}
NEXT_PUBLIC_WEBSITE_BUILDER_API_TENANT: {YOUR_API_TENANT}
# Optional, check "Cross-Origin Configuration" section below.
NEXT_PUBLIC_WEBSITE_BUILDER_ADMIN_HOST: {YOUR_ADMIN_HOST}
```
3. Ensure that in the `package.json` the `"@webiny/website-builder-nextjs":` has the right version against it, e.g. "6.0.0"
## Step 4: Establish the connection
In the Next.js project root, run:
```tsx theme={null}
yarn && yarn dev
```
> This will build your dependencies.
> It establishes the connection between your Next.js app and the Kibo CMS project thanks to your env variables.
> It starts the Next.js in development mode on `localhost:3000`. It enables hot reloading, detailed error overlays, and source maps for fast iteration on your project.
## Step 5: Validate connection
In the Kibo CMS Website Builder, try creating a new page. If the default components and header load properly, then the connection is established properly.
Note: If there are any issues, ensure that there are no warnings in the Next.js project after the start of the dev mode. For example, if you are running something else on `http://localhost:3000` the app will automatically use a different port. If this is the case you need to align your Kibo CMS Website Builder settings to the same port.
## Optional information and actions for developers and advanced users
### Kibo CMS Admin app host URL
If you're using your Next.js project in an editor that is hosted on a domain different from your Next.js domain, you'll have to whitelist the editor's domain. You can do that via the `NEXT_PUBLIC_WEBSITE_BUILDER_ADMIN_HOST` env var (see "Cross-Origin Configuration" section below).
A simple way to retrieve your Admin app host URL is to log in to your Kibo CMS Admin app, and copy the URL from your browser's address bar (for example: [https://dxhy1vkapexg1.cloudfront.net](https://dxhy1vkapexg1.cloudfront.net)) or using the **Support** link described above.
### Content SDK
The Kibo CMS Content SDK is located in `src/contentSdk` folder. The `initializeContentSdk.ts` file contains the SDK initialization, and editor component group registration. Customize your component groups here.
### Custom components
Custom components are passed directly to the `DocumentRenderer` (see the example in `./src/app/[[...slug]]/page.tsx`).
To create custom components, see examples in `./src/editorComponents/index.tsx`. We also have a more detailed article here covering Custom Components.
### Cross-Origin Configuration
If you're using your Next.js project in an editor that is hosted on a domain different from your Next.js domain, you'll have to whitelist the editor's domain.
Open `next.config.ts`, and add your domain to the `Content-Security-Policy` header. For example:
```
{
key: "Content-Security-Policy",
value: "frame-ancestors http://localhost:3001 https://d3fak6u4cx01ke.cloudfront.net"
}
```
### Sample Routes
* `src/app/[[...slug]]` - this directory contains an example of simple static page generation, using pages from the Kibo CMS Website Builder
* `src/app/product/[slug]` - this directory contains an example of Product Details Page (PDP) generation, using a combination of a remote ecommerce API, and optional editorial content.
## Kibo CMS Website Builder SDK
When you initially clone this repo, `@webiny/website-builder-nextjs` package in the `package.json` will be set to `*`. We recommend you set the version to whatever is the latest version at the time of cloning. Also, keep in mind that it's preferable to keep this version in sync with your actual Kibo CMS Admin app version, so the Editor SDK and the Content SDK are on the same version.
Inspect the sample code for more inline comments!
## Ecommerce Integrations and Component Inputs
This section is closely connected to, and depends on, ecommerce integrations in your Kibo CMS Admin app. If you don't have any ecommerce integrations, you can skip this part.
Kibo CMS Website Builder provides a way to integrate with your ecommerce platform of choice. Once an integration is enabled in Kibo CMS Admin app, you get access to specialized component input renderers, which allow you to browse and select your ecommerce resources (products, categories, etc.) to assign them to your components in the editor.
To use a specific renderer in your component inputs definition, you need to follow a naming convention.
Here's an example, which creates a "text" input, which contains a list of string values, and uses a renderer called `SampleEcommerce/Product/List`.
### Single Resource Picker
```
createTextInput({
name: "productId",
renderer: "SampleEcommerce/Product",
label: "Product"
})
```
### Multiple Resources Picker
```
createTextInput({
name: "productIds",
list: true,
renderer: "SampleEcommerce/Product/List",
label: "Products"
})
```
# Organizing Files
Source: https://docs.kibocommerce.com/pages/cms-organizing-files
Learn how to organize files in folders and sub-folders in Kibo CMS File Manager.
Kibo CMS simplifies content organization by allowing users to create folders and sub-folders, making it easier to manage. In this tutorial, we will learn how to organize your files in folders and sub-folders in the Kibo CMS File Manager. We will do this in a few steps:
* Step 1: Create a folder
* Step 2: Create a sub-folder
* Step 3: Move a folder into a parent folder
* Step 4: Upload an image
## Step 1: Create a folder
1. From the **Side Menu**, click **File Manager**.
> The **File Manager Home** screen opens.
2. In the navigation panel on the left, click **CREATE NEW FOLDER**
(Or, in the header section, click **NEW FOLDER**).
> The **Create a new folder** screen opens.
3. In the **Title** textbox, type **Sport**.
4. In the **Slug** textbox, type **sport**.
5. Click **CREATE FOLDER**.
> The message "Folder created successfully!" displays.
## Step 2: Create a sub-folder
1. In the navigation panel on the left, click **Create new folder**.
> The **Create a new folder** screen opens.
2. In the **Title** textbox, type **Snow**.
3. In the **Slug** textbox, type **snow**.
4. In the **Parent folder** menu, click **Sport**.
5. Click **CREATE FOLDER**.
> The message "Folder created successfully!" displays.
## Step 3: Move a folder into a parent folder
1. In the navigation panel on the left, click **Create new folder**.
> The **Create a new folder** screen opens.
2. In the **Title** textbox, type **Water**.
3. In the **Slug** textbox, type **water**.
4. Click **CREATE FOLDER**.
> The message "Folder created successfully!" displays.
5. Use the drag handle to drag and drop the newly created folder into the folder **Sport**
> The child folder shows up in the parent one.
## Step 4: Upload an image
We will upload the following image in this step. Please save it on your computer to upload.
1. In the navigation panel on the left, click on **Sport** and then on **Snow**.
> The **Snow** folder opens.
**Note**: You can go to any folder by clicking its title in the navigation panel on the left.
2. Click **UPLOAD**.
> The file explorer screen opens.
3. From the file explorer, upload the image.
> The message "File upload complete." displays at the bottom.
# CMS Page Loads (After)
Source: https://docs.kibocommerce.com/pages/cms-page-loads-after
This action manipulates the HTTP request or response after a CMS page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.cmspage.request.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# CMS Page Loads (Before)
Source: https://docs.kibocommerce.com/pages/cms-page-loads-before
This action manipulates the HTTP request or response before a CMS page loads on the live site.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.storefront.pages.cmspage.request.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**Storefront Operation**\
This action occurs during the storefront operation that obtains and renders view and model data from Hypr particular to the requested page.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------- |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the [API operation associated with this action](#api). |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
### items.siteContext
Accesses the current site context.
| Property | Type | Description |
| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. |
| hashString | string | A string to append to URLs that will change when cache is invalidated, either by a change to catalog or a publish of content. |
| labels | object | The theme labels, which are key-value pairs used for localization. |
| themeId | string | Unique identifier for the theme. |
| generalSettings | GeneralSettings | |
| An object the includes the following properties: | | |
* `websiteName` (string)—Name of the site as configured in the Admin general settings.
* `timeZone` (string)—The site time zone as configured in general settings in admin. Stored as human-readable string, e.g. “Mountain Standard Time”.
* `allowInvalidAddresses` (Boolean)—TRUE if address validation is enabled and invalid addresses are allowed, as configured in the Admin general settings.
* `googleAnalyticsEcomEnabled` (Boolean)—TRUE if Google Analytics is enabled and Google Analytics eCom tracking parameters are also enabled. In the Core theme and Core-derived themes, this results in a set of extra calls to the Google Analytics tracking beacon on the Order Confirmation page.
* `googleAnalyticsEnabled` (Boolean)—TRUE if Google Analytics is enabled. In the Core theme and Core-derived themes this results in a call to the Google Analytics tracking beacon on every page.
* `googleAnalyticsId` (string)—The UA number provided by the Google Analytics account as configured by the site.
* `isAddressValidationEnabled` (Boolean)—TRUE if address validation is enabled as configured in the Admin general settings.
|
\| checkoutSettings | CheckoutSettings |
An object with the following properties:
* `payByMail` (Boolean)—TRUE if pay-by-mail is enabled in the Admin checkout settings.
* `isPayPalEnabled` (Boolean)—TRUE if PayPal Express is enabled in Admin checkout settings.
* `supportedCards` (Dictionary\)—List of credit cards enabled in the Admin checkout settings.
|
\| themeSettings | object | An object that contains the theme settings available in `theme.json`. |
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| cdnPrefix | string | The URL prefix for CDN content, composed of the host name plus a unique CDN identifier for the site. |
\| secureHost | string | *HTTPS* version of the requested host name. |
\| supportsInStorePickup | Boolean | TRUE if store pickup is enabled in the Admin location settings. |
\| domains | siteDomains |
An object that lists the Current domain and the Primary domain, each of which has the following properties:
* `domainName` (string)—the name of the domain.
* `isPrimary` (Boolean)—TRUE if the given domain is the primary one.
|
\| currencyInfo | Currency |
An object with the following properties:
* `EnglishName` (string)—the currency name.
* `symbol` (string)—the currency symbol.
* `precision` (integer)—the number of digits to display after the period.
* `roundingType` (string)—the rounding type value: "UpToCurrencyPrecision", "NearestNickel", "DownToNearestNickel", "DownToCurrencyPrecisionMinusOne", or "NearestHalfUnit".
* `currencyCode` (string)—for example, "USD" for U.S. dollars. Other values include: "EGP", "GBP", "TZS", "UYU", "UZS", "WST", "YER", "ZMK", "TWD", "GHS", "VEF", "SDG", "RSD", "MZN", and "AZN".
|
Example:
```
context.items.siteContext.siteId;
```
### items.pageContext
Accesses the current page context.
| Property | Type | Description |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | object | Read-only object of the key-value pairs in the current URL. |
| themeId | string | Unique identifier for the theme. |
| isDebugMode | Boolean | Indicates whether debug mode is enabled. |
| cdnCacheBustKey | string | The randomly generated number appended to the URL of CDN content. This number changes in order to refresh cached content every time a Kibo eCommerce Admin user clicks the Bust Cache button available in the General Settings. |
| isSecure | Boolean | |
| TRUE if the current page is a secure (HTTPS) page. | | |
|
\| pageType | string | The `documentType` of the current page, such as "web\_page", "cart", "search", etc. |
\| isCrawler | Boolean | TRUE if the current page is requested by a search engine crawler. |
\| isMobile | Boolean | TRUE if the current page is requested by a mobile device. |
\| isTablet | Boolean | TRUE if the current page is requested by a tablet. |
\| isDesktop | Boolean | TRUE if the visitor’s browser does not identify itself as a mobile or tablet device. |
\| cmsContext | CmsPageContext |
An object with the following the `Page`, `Template`, and `Site`, which each have the following properties:
* `path` (string)—name or ID of the CMS document.
* `documentTypeFQN` (string)—the `documentType` such as "web\_page".
* `document` (pointer)—a pointer to the CMS document.
|
\| search | SearchContext |
An object related to URL paging and URL queries of product collections on Search pages and Category pages. It contains the following properties:
* `pageSize` (int)—the maximum number of items to return in the collection.
* `query` (string)—A filter expression for Kibo eCommerce collections. You can [filter products](/pages/sorting-and-filtering-apis) based on their properties by writing a string expression as your argument. For example: `properties.firstname eq "Brenda"`.
* `sortBy` (string)—A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
* `categoryId` (int)—the category to facet products for.
* A keyed collection of facets to filter on.
|
\| visit | Visit | The unique visitor ID. |
\| title | string | The title of the current page. |
\| metaDescription | string | The contents of the description field entered into the SEO settings for the current page. |
\| metaTitle | string | The contents of the title field entered into the SEO settings for the current page. |
\| metaKeywords | string | The contents of the keywords field entered into the SEO settings for the current page. |
\| user | User |
An object with the following properties:
* `isAuthenticated` (Boolean)—TRUE if the user is logged in.
* `userId` (string)—the unique identifier for the user.
* `firstName` (string)—the user's first name.
* `lastName` (string)—the user's last name.
* `email` (string)—the user's email address.
* `isAnonymous` (Boolean)—TRUE if the user is not logged in.
* `accountId` (int)—the unique identifier of the user's account.
|
\| isEditMode | Boolean | TRUE if the current site is being rendered inside an editor frame. Use this to display preview content in widgets or templates that would not work properly in an editing session. |
\| url | string | The canonical URL for the current page. |
\| dataViewMode | string | Either "live" or "pending". |
\| secureHost | string | The fully-qualified secure CDN domain for the site. |
\| now | DateTime | The current server date/time when the page is viewed. |
\| categoryCode | string | The category code for the current page if the page is a Category page or Search page. |
\| categoryId | integer | The category ID for the current page if the page is a Category page or Search page. |
Example:
```
context.items.pageContext.categoryCode;
```
### items.navigation
Accesses the current navigation context.
| Property | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
| tree | NavigationNode array | |
| The navigation tree used to build the main navigation bar for the site. Consists of a list of navigation nodes, each of which may contain children nodes which also are a list of nodes, and so on. The navigation nodes contain the following properties: | | |
* `name` (string)—the name of the node.
* `url` (string)—the URL to which the node links.
* `index` (int)—the unique identifier for the node.
* `isHidden` (Boolean)—TRUE if the node does not display in the site's navigation bar.
* `parent` (NavigationNode)—the parent of the current node.
* `items` (list of NavigationNode)—the children of the current node.
|
\| rootCategories | NavigationNode array | This is the same as the `tree`, except it only includes the root-level or top level of the tree, and also excludes CMS pages and external links. |
\| currentNode | NavigationNode | The current node in the tree. |
\| breadcrumbs | NavigationNode array | Shows the "breadcrumbs" that navigate to the current page. This is the same as the `tree` but it excludes the `parent` and `items` properties. |
Example:
```
context.items.navigation.breadcrumbs;
```
## Context Methods Available to All Storefront Actions
### exec.loginUser
Asynchronously retrieves a user, creates an authentication ticket, and sets the authentication cookies.
| Property | Type | Description |
| -------- | ------ | --------------------------------------------- |
| config | object | An object that contains the following fields: |
* `userId` (string)—The 32-character alphanumeric ID of the user to authenticate.
* `userName` (string)—The username of the user to authenticate (this field is not required if you provide a `userId`).
* `rememberUser` (Boolean)—Specifies whether the authentication cookie should be persistent.
|
\| callback | function | A callback function that contains the following fields:
* `err` An error object if the user is not found.
* `data` The authentication ticket for the user.
|
Example:
```
var config = {
rememberUser:true,
userId: '48577d74a86044bfb2872a4c184ce33c'
};
context.exec.loginUser(config, function (err, result){
//handle the possible error and call the callback
//if successful the result should be the customer auth ticket.
if (err){
//bubble up error to the platform
callback (err);
return;
}
//return control flow to the platform
callback();
});
```
Response: NA
### exec.logOut
Synchronously logs out the current user by resetting the user context to an anonymous user and updating the associated cookies.
| N/A | N/A | N/A |
| -------- | ---- | ----------- |
| Property | Type | Description |
| --- | --- | --- |
Example:
```
context.exec.logOut();
```
Response: NA
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Reference Field
Source: https://docs.kibocommerce.com/pages/cms-reference-field
Learn how to use reference field in Kibo CMS.
The reference field enables users to link one content model to another. For instance, consider two content models, **Product** and **Category**.
A product may belong to multiple categories. In such a scenario, we create a reference field in the **Product** content model that refers to the **Category** model.
In this tutorial, we will learn how to use reference field.
As an example, we will use the **Product** content model that we created in the [Create Content Model](/pages/cms-create-content-model) tutorial.
We will create another content model **Category**, and give the reference of **Category** in **Product**.
We will do this in four steps:
* Step 1: Create a **Category** content model.
* Step 2: Add content entries to the **Category** content model.
* Step 3: Update the **Product** content model and add a category reference field to it.
* Step 4: Create a content entry in the **Product** content model with reference to the **Category** content model.
## Step 1: Create 'Category' content model
We will create a category content model with the following attributes and fields.
If you are not familiar with how to create a content model, please follow the [Create Content Model](/pages/cms-create-content-model) tutorial.
1. Create a content model with the following attributes:
| Field | Value |
| :------------------ | :----------------------------------------------------------------------------- |
| Name | **Category** |
| Singular API Name | **Category** |
| Plural API Name | **Categories** |
| Content model group | If you have created **E-commerce** group, select it, else select **Ungrouped** |
| Icon | **(boxes)** |
| Description | **Demo Category content model** |
2. Add the following field to the **Category** content model:
| Field | Field Type |
| :---- | :--------- |
| Name | Text |
## Step 2: Create 'Category' content entries
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
1. Hover over the **Category** content model.
2. Click **View entries**.
2. Click **+ New Category**.
> The **New Category** entry screen opens.
3. In the **Name** textbox, type **Clothes**.
4. Click **Save & Publish**.
> The **Publish Product** confirmation screen appears.
5. Click **Yes, publish!**
> The message "Clothes was published successfully!" displays.
**Optional**: Similarly, you can create another **Category** content entry with name **Accessories**.
## Step 3: Update 'Product' Content Model
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
2. Hover over the **Product** content model.
3. Click **Edit**.
> Screen to configure the **Product** content model's fields opens.
4. Drag and drop the **Reference** field in the **Edit** tab.
> **Field Settings - Reference** screen opens.
5. In the **Label** textbox, type **Category**.
6. In the **Content Models** dropdown, click **Category**.
7. Click the **Use as a list of references** button.
**Note**: Since a product can belong to multiple categories, enabling **Use as a list of references** will allow you to associate multiple categories to a product.
8. Click **Save Field**.
> Screen to configure the **Product** content model's fields opens.
9. Click **Save**.
> The message "Your content model was saved successfully!" displays.
## Step 4: Create 'Product' content entry with a reference to 'Category'
1. From the **Side Menu**, Click **Content Modeling** > **Models**.
> The **Content Models** screen opens.
1. Hover over the **Product** content model.
2. Click **View entries**.
2. Click **+ New Product**.
> The **New Product** entry screen opens.
3. In the **Name** textbox, type **Men's Tiro '21 Pants**.
4. In the **Description** textbox, type **Men's tapered track pants for versatile wear**.
5. In the **Price** textbox, type **28**.
6. In the **Category** field:
1. Click **Select an existing record.**
> The **Select an existing record** screen opens.
2. In the search bar, type **Clothes**.
3. Click the **Clothes** list item.
4. Click **Save**.
7. Click **Save & Publish**.
> The **Publish Product** confirmation screen appears.
8. Click **Yes, publish!**
> The message "Men's Trio '21 Pants was published successfully!" displays.
# Tagging Files
Source: https://docs.kibocommerce.com/pages/cms-tagging-files
Learn how to tag a file and filter it through the tag in Kibo CMS File Manager.
Kibo CMS allows users to tag files, facilitating convenient access. Users can efficiently search and filter files based on assigned tags. In this tutorial, we will learn how to tag a file, and filter it via its assigned tag in the **Kibo CMS File Manager**. We will do this in a few steps:
* Step 1: Upload images
* Step 2: Tag a file
* Step 3: Tag multiple files
* Step 4: Filter files by tags
## Step 1: Upload images
1. From the **Side Menu**, click **File Manager**.
> The **File Manager Home** screen opens.
2. Click **UPLOAD**.
> The file explorer screen opens.
3. From the file explorer, select and upload multiple random images.
## Step 2: Tag a file
1. From the **Side Menu**, click **File Manager**.
> The **File Manager Home** screen opens.
2. Hover over one of the images you uploaded and click the EDIT button.
> The **File details** screen opens.
3. In the **Tags** textbox, type "**snowboard**". Press Enter. Type "**sunset**". Press Enter. Type "**friendship**". Press Enter.
4. Click **SAVE FILE**.
## Step 3: Tag multiple files
1. From the **Top Menu**, click **Switch to Table** icon.
> The **File Manager Home** screen will switch to a table view to make it easier to select/ deselect a larger number of images.
2. Select all images in this folder by clicking on the top checkbox. Note you can also select only individual images.
> The images are highlighted
3. Click the EDIT icon at the top, part of bulk actions menu.
> The Edit items screen will open up.
4. In the **Field** for Operation 1, select "**Tags**". In **Operation**, select "**Append to existing values**". In **Tags**, type "**snow**". Press Enter. Type "**snowboard**". Press Enter. Type "**sport**". Press Enter.
5. Click **SUBMIT**.
## Step 4: Filter files by tags
1. From the **Top Menu**, click **Switch to Grid** icon.
> The **File Manager Home** screen will switch to a grid view to find the desired image(s) quicker.
2. On the **File Manager Home** screen, in the navigation panel on the left, under **Filter by tag**, click the **friendship** tag and then after you see the results select **snow**.
> All the files with the tag **friendship** AND **snow** appear on the screen.
**Note**: You can deactivate an active tag filter by clicking on it again.
3. In the **Conditional filter** drop down switch from "**match all**" to "**match any**".
> All the files having either **friendship** or **snow** tag appear on the screen.
**Note**: When applying multiple tag filters, the **Conditional filter** drop-down becomes active. The default selection is **Match any**, meaning all files with at least one of the active tags will appear on the screen. If the **Match all** option is selected, only files with all the active tags will be displayed on the screen.
## Additional information
1. You can also apply a tag filter by searching the tag name in the search bar.
2. You can apply filters by utilizing the search bar, clicking on tags, and using the conditional filtering drop-down in combination.
# File Upload
Source: https://docs.kibocommerce.com/pages/cms-upload-file
Learn how to upload a file in Kibo CMS File Manager.
Kibo CMS allows you to effortlessly upload files into the **Kibo CMS File Manager** that you can use across your application. In this tutorial, we will learn how to upload a file or multiple files into the **Kibo CMS File Manager**. As an example, we will upload the image shown below. Please save it on your computer to upload later.
The maximum file size per upload is **25 MB**. Files larger than this limit will not be accepted.
Kibo CMS File Manager does not support cache invalidation. If you need to update an asset, upload it as a new file with a different name rather than overwriting the existing one. Overwriting an existing asset will not clear it from CDN caches, so the old version may continue to be served.
There are two ways to upload a file in **Kibo CMS File Manager**; let's look at each approach one by one.
## Approach 1: Through file explorer
1. From the **Side Menu**, click **File Manager**.
> The **File Manager Home** screen opens.
2. Click **UPLOAD**.
> The file explorer screen opens.
3. From the file explorer, upload the image.
> The file is uploaded. A pop-up confirmation message "File upload complete" at the bottom of the page.
4. Click on the **EDIT** button to adjust the **Name** and the other metadata of the record, e.g. you can add Tags to optimize organization and searching for assets.
> The data about the file is updated.
## Approach 2: Drag and drop
1. From the **Side Menu**, click **File Manager**.
> The **File Manager Home** screen opens.
2. Drag and drop the image from your computer's file explorer to the **Home** screen.
> A pop-up confirmation message "File upload complete" at the bottom of the page.
## Image Manipulation
Kibo CMS File Manager supports basic image resizing via URL parameter. You can append a `width` query parameter to any image URL to request a resized version:
```
https://your-cdn-url/images/example.jpg?width=800
```
Image manipulation is currently limited to the `width` parameter. Height, crop, format conversion, and other transforms are not supported.
## Upload multiple files
1. From the **Side Menu**, click **File Manager**.
> The **File Manager Home** screen opens.
2. Click **UPLOAD**.
> The file explorer screen opens.
3. From the file explorer, select and upload the files.
> The assets may take some time to be uploaded. The progress bar will inform the user of the percentage completion. Even if the user navigates away from the page the upload completes in the background and the pop-up confirmation message "File upload complete" shows up at the bottom of the page.
# Kibo CMS Website Builder Glossary
Source: https://docs.kibocommerce.com/pages/cms-website-builder-glossary
Learn about the Kibo CMS Website Builder terminologies.
## Grid Element
The Grid element is the fundamental building block of a Page. When you create a page, the first thing to add is a grid block. It serves as the parent container for all the Page elements.
## Page Element
Kibo CMS Website Builder application comes with a few ready-made page elements like Image, Rich Text, Fragment, etc. These are the building blocks of a Page.
## Page Revision
Page Revisions are a snapshot in time of the page. A new Revision is created every time we have a Publish event, meaning if you are editing Draft of Revision 1, it will stay Revision 1 until you Publish the Page. Once the entry was published and you try editing it again, the system will automatically create Revision 2 for you so that Revision 1 will remain intact and published and Revision 2 will be the record you edit.
## Page Status
In Kibo CMS Website Builder by default, we have three statuses: Draft, Published, and Unpublished. The statuses are self-explanatory, but keep in mind that in the Pages view, the Status that you see is the status of the latest revision.
# Integrations
Source: https://docs.kibocommerce.com/pages/cms-website-builder-integrations
Learn how the Kibo CMS Website Builder connects to Kibo Commerce.
The **Integrations** section in the Kibo CMS Website Builder connects your Website Builder to the Kibo Commerce platform, enabling page creation workflows that are linked directly to your live product catalog and category tree.
## Accessing Integrations
1. Open **Kibo CMS Admin**.
2. In the sidebar, navigate to **Website Builder → Integrations**.
## Kibo Commerce
The Kibo Commerce integration connects the Website Builder to your Kibo product catalog and category data. This integration is pre-configured as part of your tenant setup and requires no additional configuration.
The integration enables two commerce-specific page types in the Website Builder:
* **Kibo Product Page** — Associates a page with a specific product, referenced by product code. The page preview renders at `/product/{productCode}`.
* **Kibo Category Page** — Associates a page with a product category, referenced by category code. The page preview renders at `/category/{categoryCode}`.
These page types allow content editors to build product detail page templates and category browsing pages that are linked to live catalog data, and to preview how those pages render against specific products or categories before publishing.
Contact Kibo Support if you encounter issues with the Kibo Commerce integration.
# Redirects
Source: https://docs.kibocommerce.com/pages/cms-website-builder-redirects
Learn how to manage URL redirects in Kibo CMS Website Builder.
The Kibo CMS Website Builder includes a built-in Redirects manager that lets you define URL redirect rules directly from the Admin interface, without needing to redeploy your frontend application.
## Overview
Redirects are managed under **Website Builder → Redirects** in the Kibo CMS Admin. Each rule maps a source path to a destination URL and can be configured as a permanent (301) or temporary (302) redirect.
When a visitor requests a URL that matches a source path, the Website Builder serves the configured redirect. Your Next.js frontend fetches these rules at runtime via the `/api/redirects` endpoint included in the starter kit.
## Managing Redirects
### Create a Redirect
1. Navigate to **Website Builder → Redirects** in the Admin sidebar.
2. Click **New Redirect**.
3. Set the **From** field to the path you want to redirect (for example, `/old-page`).
4. Set the **To** field to the destination URL or path (for example, `/new-page`).
5. Select the redirect type: **301 Permanent** or **302 Temporary**.
6. Click **Save**.
### Edit a Redirect
1. Navigate to **Website Builder → Redirects**.
2. Locate the redirect you want to change and click to open it.
3. Update the fields and click **Save**.
### Delete a Redirect
1. Navigate to **Website Builder → Redirects**.
2. Select the redirect and choose **Delete** from the action menu.
## How Redirects Are Served
The Next.js starter kit includes a `/api/redirects` route and a `middleware.ts` file that fetches redirect rules from Kibo CMS at request time. This means new redirects take effect immediately after saving — no rebuild required.
If you are not using the official starter kit, you will need to implement redirect fetching yourself. Redirect rules are available via the Kibo CMS GraphQL API.
# Setting Up the Website Builder
Source: https://docs.kibocommerce.com/pages/cms-website-builder-setting-up
Understand how the Website Builder connects to your frontend app, then get the Next.js starter kit running and create your first page.
In this guide, we'll explore how the Website Builder works from a developer's perspective, then get the Next.js starter kit running locally and create a first page — confirming the full stack is wired up correctly.
**What you'll learn:**
* How the editor and your Next.js app connect
* How to clone and install the Website Builder Next.js starter kit
* How to configure API keys and environment variables
* How to create a page in the Admin editor and see it rendered
**Prerequisites:**
* Access to a Kibo CMS Admin instance
* Node.js 20.9+ and npm/yarn installed
* Familiarity with Next.js App Router — the starter kit uses App Router, not Pages Router
## How It All Fits Together
Before writing any code, it's worth understanding how the Website Builder actually works — because it's a bit different from what you might expect.
When a content editor opens the Website Builder in Kibo CMS Admin, they see a canvas where they can drag components onto a page, configure their inputs in a sidebar, and hit Publish. That's the editorial experience.
On the developer side, the picture is different — and it's what makes the Website Builder stand out from most page builders.
**The editor doesn't have its own components or styles.** Instead, it's always connected to a separate frontend app that you own — in this case a Next.js project. When the editor opens, it loads your Next.js app inside an iframe. The component palette, the live preview, all of it is your real app running right there.
This means all your component code and all your styles live in your Next.js project. Kibo CMS only stores the page structure — which components are on the page and what input values the editor set for each one. It has no idea what a "Hero" or "Banner" looks like, and it never needs to.
We cover how to create and register your own editor components in the [Custom Components](/pages/cms-custom-components) guide.
The practical upside: no style clashes, no fighting the platform, full ownership of your code. And because editors are looking at your actual app, the WYSIWYG is genuine — not a simulation.
```mermaid theme={null}
flowchart TB
subgraph admin["Kibo CMS Admin"]
subgraph editor["Website Builder Editor"]
sidebar["sidebar
(inputs)"]
iframe["your Next.js app (iframe)
real components · real styles"]
end
end
subgraph nextjs["Your Next.js App (running separately)"]
sdk["@webiny/website-builder-nextjs SDK"]
end
editor <-->|"postMessage (SDK)"| nextjs
```
The `@webiny/website-builder-nextjs` SDK is what connects the two sides — it handles the communication between the editor and your app when editing, and fetches published page documents from Kibo CMS when rendering pages for visitors.
## Step 1: Open the Admin App
Navigate to your Kibo CMS Admin URL. You'll need it running and accessible before creating pages later in this guide.
## Step 2: Clone the Starter Kit
The official Next.js starter kit wires up the SDK, routing, and rendering so you have a working base to build from.
```bash title="Terminal" theme={null}
git clone https://github.com/webiny/website-builder-nextjs.git my-website
cd my-website
npm install
```
Before running `npm install`, make sure the `@webiny/website-builder-nextjs` and `@webiny/sdk` versions in `package.json` match your Kibo CMS version. You can find your Kibo CMS version in the Admin app under **Support → About**.
For example, if your Kibo CMS version is `6.2.1`, your `package.json` should have:
```json title="package.json" theme={null}
{
"dependencies": {
"@webiny/website-builder-nextjs": "~6.2.1",
"@webiny/sdk": "~6.2.1"
}
}
```
## Step 3: Gather Your Credentials
To connect the starter kit to your Kibo CMS project, you'll need an API key, API host URL, and tenant ID. The easiest way to get these is through the **Configure Next.js** shortcut in Kibo CMS Admin — click **Support** in the bottom-left corner and select **Configure Next.js**.
A dialog appears with the three environment variables already filled in and ready to copy:
Click the copy icon and paste the block directly into your `.env` file in the next step.
If your Admin is running on a non-localhost domain, the dialog will also include a
`NEXT_PUBLIC_WEBSITE_BUILDER_ADMIN_HOST` variable — make sure to copy that too.
### API Key Is Auto-Created
Unlike the Headless CMS where you manually create an API key and configure its permissions, the Website Builder API key is created automatically for the current tenant — you'll find it under **Settings → Access Management → API Keys** as "Website Builder". It's a read-only key, intentionally scoped that way since it's meant to be used in external frontend apps like your Next.js project.
## Step 4: Configure Environment Variables
Create a `.env` file in the root of your Next.js project:
```dotenv title=".env" theme={null}
NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY=your_api_key_here
NEXT_PUBLIC_WEBSITE_BUILDER_API_HOST=https://your-cloudfront-url.cloudfront.net
NEXT_PUBLIC_WEBSITE_BUILDER_API_TENANT=root
```
All three variables are prefixed with `NEXT_PUBLIC_` because they are used on the client side
during live editing. The Content SDK also reads them server-side at build/request time.
## Step 5: Start the Dev Server
```bash title="Terminal" theme={null}
npm run dev
```
Open [http://localhost:3000](http://localhost:3000). At this point you'll see a "Page not found" message — that's expected because there are no pages in your Website Builder yet.
## Step 6: Create Your First Page
1. Open your Kibo CMS Admin app.
2. In the sidebar, go to **Website Builder → Pages**.
3. Click **New Page**.
4. Set the **title** to "Hello World" and the **path** to `/` (the homepage), then click **Create**.
5. You'll land in the page editor. In the component palette on the left, find the **Custom** group and drag the **Hero #1** component onto the canvas. It renders with placeholder content straight away — no configuration needed for now.
6. Click **Publish**.
## Step 7: See It Rendered
Go back to [http://localhost:3000](http://localhost:3000) and refresh. You should now see the hero section rendered by your Next.js app.
You've successfully rendered your first Website Builder page. Content authored in Kibo CMS Admin, delivered through your own Next.js app — that's the full loop working end to end.
## Project Structure
Here's what's in the starter kit and what each part does:
```txt title="Project structure" theme={null}
src/
app/
[[...slug]]/
page.tsx # Catch-all route — renders every Website Builder page
api/
preview/ # Enables Next.js draft mode for Website Builder preview
redirects/ # Serves redirect rules defined in Website Builder Admin
layout.tsx
components/
DocumentRenderer.tsx # Wires editorComponents into the SDK renderer
Header.tsx
NotFound.tsx
PageLayout.tsx
contentSdk/
initializeContentSdk.ts # SDK init
groups.ts # Component group registration
ContentSdkInitializer.ts # Client component wrapper for SDK init
getTenant.ts # Reads tenant ID from request headers
index.ts
editorComponents/
index.tsx # Register your components here
Hero1.tsx # Built-in Hero component
theme/
theme.css # CSS variables + typography classes
theme.ts # createTheme() call
tailwind.css
utils/
normalizeSlug.ts
constants.ts
middleware.ts # Handles preview mode, tenant routing, redirects
```
The two folders you'll spend most time in are `editorComponents/` (building and registering components) and `theme/` (styling). Everything else is infrastructure the starter kit handles for you.
## How the Rendering Works
The starter kit's catch-all route (`src/app/[[...slug]]/page.tsx`) handles all page rendering:
```typescript title="src/app/[[...slug]]/page.tsx (simplified)" theme={null}
export default async function Page({ params }) {
const { slug = [] } = await params;
// Initialize the SDK with credentials from env vars
initializeContentSdk();
// Fetch the published page document from Kibo CMS
const page = await contentSdk.getPage("/" + slug.join("/"));
// DocumentRenderer maps component names → your React components
return ;
}
```
`initializeContentSdk` (in `src/contentSdk/initializeContentSdk.ts`) calls `contentSdk.init()` with your env var credentials and registers the component groups. `DocumentRenderer` takes the page document — a JSON tree of component names and their input values — and renders it by looking up each name in your registered `editorComponents` array.
## Troubleshooting
### Still seeing "Not found!" after publishing
* Make sure you set the page **path** to `/` exactly.
* Check the browser console for API errors — a CORS or auth error means your env vars may be wrong.
* Restart the dev server after editing `.env`.
### Editor shows a blank canvas
* Make sure your Next.js dev server is running on `http://localhost:3000`.
## Summary
* The Website Builder editor loads your Next.js app in an iframe — components and styles live entirely in your project.
* Clone the starter kit and configure the three required env vars.
* Create a page in the Admin editor using the built-in Hero #1 component and see it rendered in the Next.js app.
* The catch-all route + `initializeContentSdk` + `DocumentRenderer` is how every page gets rendered.
# Website Builder Settings
Source: https://docs.kibocommerce.com/pages/cms-website-builder-settings
Learn how to configure global settings for the Kibo CMS Website Builder.
The **Settings** section of the Kibo CMS Website Builder lets you configure global options that apply across all pages in your site, such as the default page layout, social sharing defaults, and website metadata.
## Accessing Settings
1. Open **Kibo CMS Admin**.
2. In the sidebar, navigate to **Website Builder → Settings**.
## General Settings
The General tab covers site-wide defaults:
* **Website name** — used in browser titles and social sharing previews when no page-level override is set.
* **Default page layout** — the layout applied to new pages unless overridden at the page level.
* **Pages list thumbnail** — controls the preview image shown in the Pages list view.
## Social Media Settings
Configure default Open Graph and social sharing metadata:
* **Social media image** — the default sharing image for pages that do not have their own social image.
* **Social media title** — the default title used in social previews.
## Advanced Settings
* **Prerendering** — configure prerendering options for pages served by your frontend.
* **Default tags** — tags applied automatically to all pages, useful for grouping or filtering in the Pages list.
Settings here are global defaults. Individual pages can override most settings from the page editor's **Settings** panel.
# Collections
Source: https://docs.kibocommerce.com/pages/collections
Collections are a group of complementary or related "member products" that can be marketed as a single product, even across categories. For example, a beach-themed apparel collection could include products from the catalog's Footwear, Accessories, and Shirts categories.
As all products in a collection are displayed on the same details page in the storefront, allowing customers to easily purchase individual products from the collection from one page. This provides the opportunity for the retailer to cross-sell more products, as well as enhancing the customer experience and convenience. However, the products within a collection must still be purchased individually; the collection cannot be sold on its own as a single entity.
## Example
With collections, a merchandiser can display multiple products on a single details page and give each product equal real estate on this page. For example, a merchandiser could create a collection for a "living room" set that includes a couch, coffee table, end tables, and an entertainment center. These products will be shown together on a single details page on the storefront for the shopper to browse at once. The shopper can choose to add any of those products to their cart directly from that collection page, including selecting quantities and any available product options.
## Configuring Collections
There are four steps to configuring collections in your product catalogs:
1. Add the Collection Product Type to the Schema
2. Create a Collection
3. Add to Catalogs and Categories
4. Select Primary Collections of Products
### Add the Collection Product Type to the Schema
Before creating a collection, the appropriate product type needs to be added to the schema.
1. In **Settings** > **Schema** > **Product Types**, create a new type following the instructions in the [Product Types](/pages/configure-product-types) guide.
2. Select **Collection** as the Supported Usage Type.
3. A collection will inherit any base properties that are set up. Add any base properties that you want to apply for this collection type. You can also add properties that may be specific to the Collection Type. Extras, options, and variants are not supported.
4. Click **Save**.
Although similar collections can use the same product type, it is generally a good idea to make separate product types for each collection so that they can have different properties as needed.
### Create a Collection
As collections are created as a product type, they are viewed at **Main** > **Products**. Filter the Products view by "Product Type = Collection" to see a list of all collections.
Note that collections are created at the Master Catalog level but can then be assigned to child catalogs as needed.
1. Click **Create New Product** in the top righthand corner to begin configuring a new collection.
2. In the General settings for a collection, provide the details of the collection.
* **Product Title:** The required name for the collection, to be displayed on the storefront.
* **Product Code:** The required code identifier for the collection.
* **Product Type:** The Collection product type that was added to the schema.
* **Product Usage**: his should always be "Collection" to indicate that this is not an individual product. When the Product Type and Product Usage are selected to indicate that this is a collection, the page will update to contain collection-specific configuration options.
* **Short Description:** A brief summary of the collection, usually one line. This will be displayed on the storefront.
* **Long Description:** A longer description explaining more details about the collection.
* **Product Images:** A list of images to provide a preview of products within this collection. The first entry in the list is the hero image that will be used as the primary collection image.
3. The Member Products section displays a list of all products that have been added to this collection. If no products have been added yet, then the list will be empty. Note that these products do not all have to be from the same category – any Standard or Configurable product in the catalog can be part of a collection.
4. Click **Add** in the top right of the Member Products section to open the below menu. A table of all standard and configurable products in the catalog will be displayed by default.
1. Use the search bar to locate products by name or product code.
2. Check the box of any product(s) that you wish to add to the collection. You may select up to a maximum of 35 products.
3. Only Standard or Configurable product types are supported in collections. Any other products are not displayed as options in this table. This means that subcollections are not supported. You cannot add a collection as a member to another collection.
4. Click **Save** to close the menu.
5. All selected products will now be visible in the member products list. Drag and drop the products to change their ordering in the list; this will be the order that they are displayed in on the collection details page of the storefront.
5. If at least one product member exists and is in stock, then the collection will be displayed on the storefront. If a collection is created without any member products, then the collection will not be displayed on the storefront. However, if a collection is created with product members and then those members are removed, it will still continue to display on the storefront.
6. In the next section of the collection settings, any available properties can be set at the collection level. The base properties inherited in the product type that was configured in the schema are not mandatory. If an inherited property does not apply to the collection, then do not select a value.
* Note that any fields related to exact unit price, shipping, and inventory are not supported for collections, because a collection itself cannot be sold as a product—only the individual product members can be purchased.
7. Optional SEO details can be set for the collection and will affect the collection details page on the storefront. In the SEO section at the bottom of the collection settings page:
1. Enter a meta title.
2. Enter a slug for this page.
3. Enter a meta description and keywords for this page.
8. Continue to the next section to add the collection to any catalogs and categories.
### Add to Catalogs and Categories
While the collection is always made at the master catalog level, you can also add it to any child catalogs.
1. Click the pencil icon in the Catalog header above the product settings and add the collection to additional catalogs by checking the box next to one or more catalog names.
2. Child catalogs that the collection is a part of will be added to the header once selected. Click a catalog name to view the catalog-specific configurations for the collection.
3. You can set any overrides to the General and SEO settings at the catalog level. Check the box for **Override global** to set different values that will only be used for the collection within this catalog. If the override box is not checked, then the fields will be greyed out.
When a collection is added to a child catalog, you can then apply it to any categories within that catalog. This means that the collection will be displayed on that category page in the storefront alongside any other products in the category.
1. Click **Add** next to **Assigned Categories** or use the dropdown to assign the collection to any categories, just as you would for other products. Once added, the collection will always be displayed in the category by default (as long as it has at least one member product).
2. The **Primary Category** specifies which static category to use in the navigation breadcrumb on the storefront, regardless of how shoppers navigate to the collection. If not set, the default is to use the category with the smallest ID in the catalog.
3. Click **Save** in the top righthand corner of the page to finalize the collection creation. Note that a collection can still be saved without any member products being added – however, an empty collection will not be displayed on the storefront.
#### Static, Dynamic, and Real-Time Categories
To add a collection to a category, add it like you would any regular product. This allows you to have categories that are only regular products, categories that are mixed products and collections, and categories that are only collections.
For static categories, a category can be set at the product member or collection level. If set at the collection level, then the collection will be included in the category. If not set, then the collection will only be included in the category based on whether any of its member products are assigned to that category.
For static and dynamic categories, you don't have to explicitly add collections because the collection will be displayed as long as any product member belongs to the category. However, collections must be explicitly added to any real-time categories. Kibo recommends that if you want to use collections for real-time categories, then use a condition for the category that the collection itself falls within rather than being dependent on a specific member product.
### Select Primary Collections of Products
A member product can be added to multiple collections, but only one can be its primary collection. The "primary collection" is the collection that the product is generally associated with on the product details page in the storefront.
However, a primary collection is not required. The default setting for a primary collection is none – the primary collection must be explicitly chosen on the product settings. For any other collections that have not been selected as the primary, the product will still be listed with other member products when viewing the collection but the collection will not be displayed on the product's details page.
1. Select a product in **Main** > **Sell** > **Products**.
2. In the **General** settings, select a primary collection from the dropdown menu. The available collections are those that the product is already added to.
## Viewing Collections
Collections are displayed on the storefront in their own details page and on their member products' details page where they are the primary collection. They will also be returned in search results like other products. This section shows some examples of how they are displayed, though the exact display will depend on your front-end design and implementation.
Be aware that collections should not be added to lists or Quick Orders from the product picker for B2B shoppers.
### Collection Details Page
While each member product in a collection still has its own individual details page on the storefront like any other product, the collection also has a details page that will display information for the entire collection: the name, description, hero image, and list of member products.
The order that the member products are displayed in is based on the sort order determined for the collection. The shopper can browse this list and quickly add individual products to their cart by selecting any product variant options and the quantity before clicking **Add to Cart**. Clicking any product in the list will take the shopper to the product details page.
Clicking **Shop the Collection** as shown in the example below will focus the page on the list of member products. However, this page can be customized on your front-end.
### Collections on the Product Details Page
When viewing an individual product details page on the storefront, the name of the collection that the product belongs to will be displayed and linked to the collection details page. If the Member Product belongs to more than one collection, only the primary collection that was selected in the product settings will be displayed.
### Collections in Search Results
For existing clients, the Search Schema will need to be manually updated with the below fields, which will be provided out of the box for new clients.
A collectionMemberNames field is supported in the schema for Site Search, allowing collections to be returned in the standard storefront search results in addition to their individual member products. For example, if a user does a search for "hammer" then the search results will include both the hammer product and the Tools collection that the hammer is a part of.
The lenient and lenient pf attribute types are included by default, but if you want to add other types then you can as long as it is still using the collectionMemberNames field. For more information about editing the search schema, see the [Search Schema documentation](/pages/search-schema-overview).
Assign weights to each collectionMemberNames field. Give the collections a low weighting if you want to bury them in search results.
By default, a collection will be displayed in a category if a member product is in that category.
## Faceting Collections
Collections can be faceted and will be displayed on the storefront if any member product matches the facet criteria, which includes direct fields like price (which are not set at the collection level but are analyzed at the member product level). For example, if a Facet is "price range: (\$5 – \$500)" then the collection will display if even one of the member products is \$5. Even if multiple members in the collection fall within the facet criteria, the collection will only be displayed once.
If the value of any property is left blank at the collection level, then the member property values will be referenced instead. However, if this value is set at the collection level then it will be used as the override and determine whether the collection appears in faceting regardless of the property values of the member products.
Examples:
* Facet: Rating range: (3—5). If even one of the products in the collection has a rating of 4, the collection will be displayed.
* Filter by Popularity = 5. Both a product member and collection have a popularity of 5. In this case, the product member and the collection will be displayed.
* Filter by Season = Fall. Only the collection has this property set. Only the collection is displayed.
For more information about configuring facets, see [Facets](/pages/facets).
# Configurable Gift Cards
Source: https://docs.kibocommerce.com/pages/configurable-gift-cards
Configurable gift cards require you to create special product attributes and a product type before the gift card product.
See how to manage store credits and store gift cards
## Create the Product Attributes
You must first create product attributes that provide the selectable monetary amounts for the gift card.
1. Go to **System** > **Schema** > **Product** **Attributes**.
2. Click **Create New Attribute**.
3. Enter an **Attribute Label**.\
This label appears on your storefront and is visible to your shoppers.
4. Enter an **Administration Name**.\
This field defaults to the Attribute Label value, but you can specify another name to help you better identify the attribute.
5. If not already populated, enter an **Attribute Code**.\
This field defaults to the Attribute Label value.
6. Set the **Input Type** to **List**.
7. Under **Attribute Type**, select **Option**.
8. Set the **Date Type** to either **Text** or **Number**.\
Text allows you to add in the dollar sign to the monetary values in the list. Number only supports numerical values.
9. Under **Values**, add the individual monetary amounts that your gift cards come in.
Press **Enter** after typing in each value to quickly add your values to the list.
10. Click **Save** to save the product attribute.
## Create the Product Type
After creating the product attributes, you then create the product type so that Kibo eCommerce knows the product is a gift card.
If you previously created a gift card product type, you're not required to create an additional gift card product type for the configurable gift card. However, if you use an existing gift card product type, you'll need to add your product attributes to the product type as Options.
1. Go to **System** > **Schema** > **Product Types**.
2. Click **Create New Product Type**.
3. Enter a **Name**.
4. Under **Supported Usage Types**, ensure that **Configurable Product With Options** is selected.
If you plan on creating standard gift cards, select **Standard Product**. You can use the same product type for the two different gift card types.
5. Under **Options**, click **Add**.
6. In the **Attribute** list, select the product attribute you previously created for the monetary gift card amounts.
7. In the **Values** list, select the monetary value amounts that you wish to offer the gift card in. Each selection appears in the **Selections** list.
The sequence the monetary values appear in the Selections list is the same sequence they'll appear in to shoppers.
8. Click **Done**.
9. Under **Advanced**, select **This Product Type is a Digital Gift Card**.
10. Click **Save** to save the product type.
## Create the Gift Card Product
After creating the product attributes and product type, you then create the gift card product and apply the product type you previously created.
1. Go to **Main** > **Catalog** > **Products**.
2. Click **Create New Product**.
3. Click the **Plus** button on the global tab to add the gift card to a specific catalog.
4. Enter a **Code** for the gift card.
5. Select a **Status** for the gift card.\
The Status drop-down menu does not appear if you did not previously select a specific catalog.
6. Under **Product Type**, select the gift card product type you previously created.
7. Under **Product Usage**, select **Configurable Product With Options**.
8. Enter a **Name** for the gift card.\
This is the name that appears on your storefront and is visible to shoppers.
9. (Optional) Enter a **Short Description**, a **Full Description**, and add a **Product Image**.
10. Set the **Price** and **Gift Card/Credit Value** to \$0.
The base gift card should have a price of \$0, and the individual gift card variances will have a price according to their respective monetary values.
11. (**Recommended**) Under **Product Discounts**, Kibo eCommerce recommends to select **Restrict discounts on this product** to prevent discounts being applied to the gift card price.
12. Under **First Available Date**, ensure the correct date is selected when the gift card product first became available.
13. Under **Options**, click **Select Values**.
14. In the **Edit Variants** dialog box, click **Update Options**.\
The product attributes you previously created appear.
15. Select the monetary values you wish to offer the gift card in.
16. Click **Save**.
17. In the **Edit Variants** dialog box, complete the following steps for each applicable gift card variant:
1. Enable each individual gift card variant.
2. (Optional) Enter a product code for each variant. This should be a minimum of 3 characters, up to a maximum of 30. If you don't enter a product code, Kibo eCommerce automatically creates one for you.
3. Under **Extra Price**, enter the amount you wish to charge for each individual gift card variant.\
For example, you have a \$50 gift card variant, so you enter \$50 in Extra Price.
4. Under **Gift Card/Credit Value**, enter the credit amount the gift card is for.
18. Click **Save** in the **Edit Variants** dialog box to save your product variants.
19. (Optional) Add any applicable properties, categories and SEO information to the gift card.
20. Click **Save** to save the gift card product.
21. If your product publishing settings are set to Staged, complete your product publishing workflow to publish the gift card.
# Configure Discounts
Source: https://docs.kibocommerce.com/pages/configure-discounts
This guide explains how to create a new discount and the different types of discount settings, as well as provides examples of common discounts and how to configure them. For more information about how this page displays discounts in a folder hierarchy and allows you to manage existing discounts, see [Discount Folders](/pages/discount-folders).
Learn how to create and manage coupon sets for discounts
Get an introduction to marketing and discount capabilities
See how to create free shipping order discounts
Learn how discount stacking works and how to configure it
See how to configure the general section of an order discount
Learn how to set target criteria for order discounts
See how to configure discount conditions for order discounts
Learn how to set limitations on order discounts
Learn how to set target criteria for line item discounts
See how to configure conditions for line item discounts
Learn how to set limitations on line item discounts
Learn how to configure message conditions for discounts
By default, [order attributes ](https://docs.kibocommerce.com/pages/schema-extensible-attribute)are only captured during checkout and the system does not reprice orders or reevaluate discounts after updating the attributes. This means that if a discount is applied in the cart but order attributes are updated during checkout, then the discount will remain applied even if the order doesn't match its conditions any more. Kibo recommends configuring your storefront to capture order attributes before the payment step so that attributes are included in discount evaluation.
## Create a Discount
To create a new discount:
1. Go to **Main** > **Sell** > **Discounts.**
2. Select the desired catalog you want to make the discount for in the top of the page.
3. Click **Create New Discount**.
Within the editor that opens, you can configure various settings for the discount by following the steps outlined in the next sections of this guide. To edit an existing discount, simply click the discount in the table displayed on the Discounts page and you will be able to update these configurations.
## General Settings
The General settings specify the framework of the discount, such as the discount name, the type and amount of the discount, and what part of the purchase the discount applies to. Note that some options, such as the subscription and stackable discount configurations, may not be displayed depending on your implementation.
To configure a disocunt:
1. Toggle whether you want the discount to be immediately enabled or not. If you are editing an existing discount, you can use this toggle to manually enable/disable a rule that was deactivated or activated by a [campaign](/pages/campaigns#activate-or-deactivate-a-campaign "Campaigns").
2. Toggle **Available for** **Public API** if you want this discount to be accessible by your storefront and other custom code. If not public, then the discount will only be accessible to the storefront via secure endpoints by users with Discount Read behaviors. See [the API documentation](/api-overviews/getting-started) and [guide](/pages/discounts-api-overview "Discounts API Overview") for more details.
3. Enter a **Name** for the discount.
4. Enter a **Code** for the discount.
5. Specify a **Start** and **End** date for the discount. If the discount is enabled and the start date is left blank, it will be immediately activated. If you leave the end date blank, the discount will never expire.
6. Choose whether the discount **Applies To:**
* **Line Item:** The discount applies to the price of a line item(s) in the order. Line item-level discounts are useful when you want to apply the discount to specific products in the order, or when you want to provide granular shipping discounts for specific products.
* **Order:** The discount applies to the subtotal of all items in the order. Order-level discounts are useful when you want to apply the discount to all products in the order.
7. Choose whether the discount **Affects**:
* **Product:** The discount applies to the cost associated with products in the order.
* **Shipping:** The discount applies to the cost associated with shipping the order.
8. Choose a discount **Type** and enter the **Amount Off**:
| Discount Type | Example |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Percentage | Subtract 20% from a particular cost. |
| Amount | Subtract \$10 from a particular cost. |
| Free | |
| | Provide free shipping or a free product. |
| **Note**: This type does not display when the discount applies to the whole order. | |
| | Fixed Price |
| Provide shipping or a product at a certain cost. | |
| **Note**: This type does not display when the discount applies to the whole order. | |
| | Auto-Add Free Product |
| Automatically adds a product to a shopper's cart and sets the product's price to free. | |
| **Note**: To view this option, you must set the **Applies To** field to **Line Item** and the **Affects** field to Product. | |
| | |
9. If you want the discount to only be applied on specific sites, then select those sites from the **Exclusive Sites** drop-down list. These options are limited to the sites associated with the same catalog you are creating the discount in. If this field is left blank, then the discount will be able to apply to all sites of the catalog.
10. If subscriptions are enabled on your tenant (not shown above), select whether the discount applies to **One-time sales only** or **Subscriptions only**. One-time sales are standard discounts that can be applied to regular orders, while subscription discounts can only be applied to subscriptions and their continuity orders.
* Selecting **Subscriptions only** will cause additional subscription configurations to appear, where you can select the required frequency (for item-level discounts) or continuity order (for order-level discounts) at which the discount can be applied. For more details about these subscription-specific options, see the [Subscriptions documentation](/concept-guides/subscriptions).
11. If you want it to be [stackable with other discounts](/pages/stackable-discounts), toggle **Stackable** on and select the discount layer at which this discount is applied to. Layers help the system determine which discounts can be stacked together.
12. Enter an optional **Description** of the discount. You can display this description to shoppers if you customize your theme to include this functionality.
13. Enter **Discount Labels** if you want to use additional tags to differentiate and organize your discounts.
After you configure these initial settings, the following options display: [Discount Conditions](#discount-conditions), [Target Criteria](#target-criteria), [Attribute Conditions](#attribute-conditions), [Message Conditions](#message-conditions), [Discount Limitations](#discount-limitations), and [Custom Properties](#custom-properties). Continue with those sections as needed to finish configuring the discount.
## Discount Conditions
The discount conditions determine what must happen before the discount applies. For example, you may want the pre-discounted order total to exceed \$50 dollars before you apply a discount, or you may want the shopper to purchase at least three clothing items before you allow them to use a coupon. If you do not want to apply a condition, leave it blank. All discount conditions are optional.
In the case of competing discounts, such as when a shopper has a subtotal of exactly \$100 in their cart and applies for a discount that gives 25% off when they spend \$100 or more as well as a discount that gives 50% when they spend \$100 or less, the discounts compete for the best deal. In this case, the order would be 50% off.
1. Specify the pre-discounted subtotal that must be in the shopper's cart in order for the discount to apply (**Minimum Order Amount**) and/or the pre-discounted subtotal that the shopper's cart must not exceed in order for the discount to apply (**Maximum Order Amount**). When both of these criteria are used, then it will create a range in which the discount is valid.
2. (Optional) Select products that you want to exclude from the pre-discounted minimum and/or maximum order subtotal.
3. (Optional) Select product categories that you want to exclude from the pre-discounted minimum and/or maximum order subtotal.
4. Specify if you want the shopper to use a **Required Payment Method** for the discount to apply. You can only select from payment types that belong to the site(s) within your current catalog. If a catalog has a single site attached to it, payment types only for that site will be displayed. If a catalog has multiple sites and a payment is common across two or more of them, the option will only be displayed once in the dropdown but it can be applied across both sites.
5. (Optional) Specify if you want the shopper to meet a **Minimum Lifetime Value Amount** for the discount to apply. For example, you may want to apply a discount when a shopper spends a cumulative amount of \$500 or more since the opening of the customer's account.
6. Click **Add** to specify which customer segments the shopper must belong to for the discount to apply. For example, you may want to create a discount for employees or students. To create new customer segments, use the Customer Segments page located at **Main** > **Customers** > **Customer Segments**. Refer to the [Customers](/pages/customers-overview) for more information about creating customer segments.
The next section of Discount Conditions, titled **Purchase Requirements**, changes depending on your selections. These options are detailed below—all of the following settings are optional unless otherwise noted.
#### Order-Level Discounts
If you are creating an order-level discount, you will have options for minimum total quantity and distinct products, required products and categories, and minimum category purchase amounts.
1. Set a **Total Order** **Quantity**. This will allow the discount to be applied only if the order's total item quantity meets that value.
2. Set the minimum **Distinct Number of Products**. For instance, if you want the discount to only apply if the order includes three or more different products then set this value to three.
3. Click **Add** to specify which products or product categories a shopper must purchase for the discount to apply. For example, you may want to apply a discount when a shopper purchases ten specific leather-bound notebooks. Or you may want to apply a discount when a shopper purchases any ten office products. If you apply a minimum quantity for a product(s) and for a category(s), then both conditions must be met in order for the discount to apply.
4. Specify a **Minimum Category Purchase Amount** if you want the shopper to purchase a certain amount of a product category for the discount to apply. If you entered a value for this field and for the Minimum Order Amount field in Step #1, both conditions must be met in order for the discount to apply.
5. If you want the discount to only be applied to line items with specific fulfillment types, then enter those types into **Exclusive Fulfillment Methods**. Valid values are "Ship," "Pickup," "Digital," "Curbside," and "Delivery". If this field is left blank, then the discount will be able to apply to items of all fulfillment types.
#### Item-Level Discounts
If you selected to create a line item-level discount in the General Settings, then you are required to select one of two options from the **Purchase Requirements** dropdown.
* **Specific Products and Categories:** The discount will apply to the shopper's purchases if they purchase specific products or categories.
* **Target Only:** The discount will apply to a shopper's purchases if the shopper purchases the specific product(s) that the discount targets.
If you selected Specific Products & Categories:
1. Click **Add** to specify which products or product categories a shopper must purchase for the discount to apply. For example, you may want to apply a discount when a shopper purchases ten specific leather-bound notebooks. Or you may want to apply a discount when a shopper purchases any ten office products. If you apply a minimum quantity for a product(s) and for a category(s), then both conditions must be met in order for the discount to apply.
2. Specify a **Minimum Category Purchase Amount** if you want the shopper to purchase a certain amount of a product category for the discount to apply. If you entered a value for this field and also for the Minimum Order Amount field earlier in Discount Conditions, both criteria must be met in order for the discount to apply.
3. If you want the discount to only be applied to line items with specific fulfillment types, then enter those types into **Exclusive Fulfillment Methods**. Valid values are "Ship," "Pickup," "Digital," "Curbside," and "Delivery". If this field is left blank, then the discount will be able to apply to items of all fulfillment types.
If you selected Target Only:
1. In the **Minimum Required Purchase Quantity Per Redemption** field, indicate the quantity of the target product that the shopper must purchase before they can qualify for the discount.
2. If you want the discount to only be applied to line items with specific fulfillment types, then enter those types into **Exclusive Fulfillment Methods**. Valid values are "Ship," "Pickup," "Digital," "Curbside," and "Delivery". If this field is left blank, then the discount will be able to apply to items of all fulfillment types.
After you have selected your discount conditions, move on to the **Target Criteria** section.
## Target Criteria
The target criteria specifies the details of what the discount applies to once the discount conditions are met. For example, you may want to provide a free bracelet (target criteria) if a shopper purchases more than \$100 of your products (discount conditions). Or you may want to provide 15% off the entire order (target criteria) if the shopper purchases products during a sale period (discount conditions).
For line item discounts, if multiple discount conditions apply but there is a restriction on the number of redemptions, then you can specify whether the discount applies to the highest-priced qualifying product(s) first providing the shopper with the most value. For example, you have a buy one get one free discount on water bottles that shoppers can redeem once per order. A shopper buys two different water bottles and one model costs \$8 while the other costs \$6. In this case, if you specify for the discount to apply to the highest-priced qualifying product first then the shopper receives the discount on the more expensive \$8 model.
#### Order-Level Discounts
Order-level discounts have the following Target Criteria configurations:
1. Decide if you want to exclude products that already have either **Product Discounts** and/or **Shipping Discounts**.
2. Decide if you want to exclude any products in either specific categories, or specific individual products. For example, you may have a discount for 10% off an order, but you may not want to discount products in a shoe category.
3. Include any price lists to which you want the discount to apply. For example, you may have a price list with a price entry for a water bottle. The discount might apply to the water bottle, and you want to discount the price specified in the price list. By default, Kibo eCommerce excludes all discounts from applying to price lists. You must explicitly add any price lists to which you want the discount to apply in the **Applicable Price Lists** field.
4. Decide if you want the discount to apply to on sale products.
5. If the discount affects Shipping, select the shipping method and the shipping zone. You can only select from shipping methods that belong to the site(s) within your current catalog. If a catalog has a single site attached to it, shipping methods only for that site will be displayed. If a catalog has multiple sites, shipping methods will be tagged with their site name to help you differentiate between the options. If you want to select multiple shipping methods, you will be restricted to selecting methods that belong to the same site.
6. Specify if you want the discount to apply to products shipping to specific regions.
#### Item-Level Discounts
Item-level discounts have the following Target Criteria configurations:
1. Determine the scope of the discount target. You can choose **Specific Products**, **Specific Categories**, or **All** products to be eligible to receive the discount if the conditions are met. If you choose **Specific Categories**, you can select static categories and precomputed dynamic categories. Refer to [Category Types](/pages/category-overview) for more information about the differences between the two types of categories. Precomputed dynamic categories are the only type of dynamic categories you can select as a discount target. Realtime dynamic categories are not supported discount targets. Refer to [Dynamic Categories](/pages/dynamic-categories) for more information about dynamic categories. If you choose either an individual product or category in the Discount Conditions section, you can target the same product or category for the discount using the **Same as Required Purchase** option. This is essentially the same as a "Buy (n) of X, Get (x) for Y" scenario. Refer to the [Common Discount Examples](#common-discount-examples) for more information.
2. (**If applicable**, **not shown**) Select the **Specific Products** or **Specific Categories** that you want to target for the discount.
3. Select the quantity of products on which the shopper receives the discount. Leave this field blank for an Unlimited amount. For example, you may want to want to apply the discount only to the first product in the order. Or, you may want to apply the discount to the same amount of products that are required for purchase in the conditions section.
4. (**Not shown**) If you select either **Specific Categories** or **All** products in the Scope, exclude products or categories to which you do not want to apply the discount. For example, you may have a discount for 25% off clothing items, but you may not want to include blazers in the sale.
5. Include any price lists to which you want the discount to apply. For example, you may have a price list with a price entry for a water bottle. The discount might apply to the water bottle, and you want to discount the price specified in the price list. By default, Kibo eCommerce excludes all discounts from applying to price lists. You must explicitly add any price lists to which you want the discount to apply in the **Applicable Price Lists** field.
6. Decide if you want the discount to apply to on sale products or the on sale price. For example, you may already have a discount for 25% off a product, but you may not want to discount already on sale products or discount the sale price.
7. If multiple products qualify for the discount, decide if you want the discount to apply to the highest-priced product(s) first.
* For example, you have a buy one get one free discount on water bottles that shoppers can redeem once per order. A shopper buys two different water bottles and one model costs \$8 while the other costs \$6. In this case, if you specify for the discount to apply to the highest-priced qualifying product first then the shopper receives the discount on the more expensive \$8 model. If you select Shipping in the Affects field under the General section, this option changes to specify whether you want the discount to apply to qualifying products with the highest shipping cost first.
8. (**Shipping discounts**, **not shown**) Select the shipping method and the shipping zone to use for a shipping discount.
#### Line Item Discounts with Volume Pricing
You can use volume pricing in price lists to specify product prices that are based on specific quantities of products. For example, when shoppers order 10 to 20 hammers you want the price per hammer to be \$20, and when shoppers order 21 to 30 hammers you want the price per hammer to be \$15. You can use volume pricing in price list entries to accomplish this. Refer to Volume Pricing in the [Price Lists](/pages/price-lists) documentation for more information.
When using both discounts and volume pricing, it's important to keep the following conditions and restrictions in mind:
* When you create a line item discount that targets specific products, and if those products have multiple volume bands, the discount applies to the price of the applicable quantity that a shopper selects.
* When you create a line item discount that targets a dynamic category expression that evaluates product pricing, and if you create multiple volume prices for a product, the discount only applies to the price of the lowest quantity volume band and not the other volume bands.
Refer to the following table for more information:
| Discount Applies To | Discount Target | Outcome |
| ------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Line item | Specific product or category | If the targeted product has multiple volume bands, the discount applies to the price of the applicable quantity that a shopper selects. |
| Line item | Dynamic category with an expression that evaluates product price | If you create multiple volume bands for a product, the discount only applies to the price of the lowest quantity volume band and not the other volume bands. |
Volume pricing is not affected by buy one get one free (BOGO) type discounts. If you create a BOGO discount and include a price list with volume pricing in the discount, shoppers must still order the specified amount of products in the volume band; however, they are not required to pay for all of the products because they receive half of them for free. For example, you create a BOGO discount for hammers, and include a price list that has a volume band of 10 for \$5 each. In order for shoppers to get the \$5 pricing they must still order 10 hammers; however, they'll receive 5 of them for free because of the BOGO discount.
After you have selected your discount conditions, move on to the **Message Conditions** section.
## Attribute Conditions
Attribute conditions allow you to configure logic based on [custom attributes that have been enabled for discounts](/pages/discount-extensibility "Discount Extensibility"). This gives you more flexibility in how discounts can be applied, such as offering discounts to Harvard alumni based on whether an "alumni" attribute is set to "Harvard." Customer, B2B, order, and location attributes are supported for use in discounts.
1. In the Attribute Conditions sections, click **Add**.
2. Select an **Attribute Type** (B2B, Customer, Order, or Location) from the drop-down menu.
3. Select the attribute you want to add from the **Attributes** drop-down menu.
4. Select the **Operator Type**.
5. If you select a comparison operator, another field will appear where you should enter the value that the attribute should be compared to. For example, you may set the operator type as "greater than" and the value as "2."
6. Click **Add**. This attribute and its selected logic will now be displayed in the Attribute Conditions table.
## Message Conditions
Message conditions specify rules which must be met before a threshold message will display. The threshold message acts as a prompt to encourage customers to increase their order value. It appears when the cart total falls within a specific range related to the discount’s minimum order amount. For example, if a discount requires a minimum order of \$25 and the threshold is set to \$10, the message will display when the cart total is between \$10 and \$25 (i.e., threshold value \< cart total \< discount minimum).
This feature requires changes to your core theme. Ask your theme developer to make the required changes to your theme to enable this feature, as detailed in the [GitHub pull request](https://github.com/Mozu/core-theme/commit/42a0ade3f52ce4f7099a9f3d51624136beb7331d).
1. Specify if you want to display a threshold message for this discount.
2. Specify the dollar amount that the shopper's order must exceed before the threshold message displays.
3. Specify if you want the message to display on the cart page, checkout page, and/or whether the shopper needs to enter a coupon code to view this message.
4. Enter the message you want to display when the shopper meets the conditions for the message.
## Discount Limitations
Discount limitations provide rules for the use of discounts, in addition to the discount conditions you already configured. For example, you may want to limit shoppers to using a discount only one time, or limit the discount to \$50 worth of value. You may also want to require that shoppers enter a coupon code to receive the discount. If you do not want to apply a discount limitation, leave it blank.
1. Specify a **Max Discount Value (Per Redemption)**. For example, you have a Buy One Get One Free discount on potted plants. However, you limit the max discount value per redemption to \$30. In this case, a shopper who buys a \$35 potted plant must pay \$5 for the second plant.
2. Specify a **Max Discount Value (Per Order)**. For example, you have a 40% sale on all products. However, you limit the max discount value per order to \$100. In this case, a shopper receives the discount only for the first \$250 worth of goods in their order.
3. Specify a maximum number of **Total Redemptions** that applies across all of a customer's orders. For example, you have a 10% discount on five distinct items in your store. However, you limit the max number of redemptions to three. In this case, shoppers receive the discount on all five items if they purchase all the items with their first order. However, if a shopper purchases the items one at a time in separate orders to space out purchases, they receive the discount only on the first three orders. If a maximum amount of redemptions is set here at the discount level, then the discount will only work when the shopper is logged into their customer account. If you want a discount to be available for guest shoppers, you must leave this option blank and instead set the maximum redemption amount [on the coupon set](/pages/coupon-sets#create-a-generated-coupon-set).
4. Specify a limit of **Max Redemptions (Per Order)**. For example, you have a 10% discount on five distinct items in your store. However, you limit the max number of redemptions per order to three. In this case, a shopper who purchases all five discounted items in one order receives the discount on only the three most expensive items.
5. Choose if you want to require **Coupon Codes**. If you chose to require a coupon code, the shopper must enter the coupon code once they meet the conditions of the discount in order to receive the discount. You can either create a single coupon code or multiple codes using a coupon set. If you choose multiple codes, select the coupon set for which you want to associate the discount with. Refer to [Coupon Sets](/pages/coupon-sets) for more information about coupon sets.
6. (**If applicable**) If you required a coupon code, enter a desired **Coupon Code** or have the system suggest one for you.
7. Specify whether the **Discount can be redeemed one time per shopper**. If a maximum amount of redemptions is set here at the discount level, then the discount will only work when the shopper is logged into their customer account. If you want a discount to be available for guest shoppers, you must leave this option disabled and instead set the maximum redemption amount [on the coupon set](/pages/coupon-sets#create-a-generated-coupon-set).
8. It is very important to consider whether discounts should apply to orders that contain multiple destinations. The **Discount will not apply on multi ship orders** checkbox disables the discount on any orders that contain multiple destinations. Certain discounts should never apply to orders that contain multiple destinations. For example, consider a discount that takes \$10 off shipping on orders of \$100 or more. On a site that has multiple destinations enabled, a shopper can purchase three items collectively worth over \$100, and then choose to ship each item to a unique address. If there was only one destination to ship to, this discount would have taken \$10 off shipping one time, but because there are three shipments, the discount will take \$10 off three times. In this case, you would want to use the checkbox to disable such a discount on orders that contain multiple destinations. For more information, refer to the [topic on multiple addresses](/pages/ship-to-multiple-addresses).
9. Select to exclude product discounts from applying on top of this discount. This field and the following two fields may not display depending on the type of discount you choose to edit. This is because eCommerce applies different types of discounts in the following order: **line item product -> line item shipping -> order product -> order shipping**. As a result, your options for excluding other discounts will change depending on what type of discount you choose to edit. For example, if you edit a line item product discount, you will see more options for discounts to exclude because line item product discounts are applied first when eCommerce calculates a product's price. However, if you edit an order product discount, you will see fewer options for discounts to exclude because eCommerce will have already applied any valid line item product and line item shipping discounts before it checks the settings for an order product discount.
10. Select to exclude line item shipping discounts from applying on top of this discount.
11. Select to exclude order shipping discounts from applying on top of this discount.
12. Click **Save** in the top right of the page to save your fully-configured discount.
## Custom Properties
The Custom Properties section displays all available properties that you've defined and allows you to simply input their value for this discount.
If you do not have any custom properties defined already, you can create up to a maximum of 10 via your Discount Settings. These will be available for all discounts in the master catalog.
1. Go to **System** > **Settings** > **Discount Settings**.
2. Click **Add** in the Custom Properties pane.
3. Enter the **Code** and **Name** of the property. These have maximum lengths of 50 and 200 characters, respectively.
4. New properties will be enabled by default, but you can change their status from the actions menu on the far right of the table row.
5. Click **Save** in the top right of the page.
You can also create custom properties and set them on discounts via [the Catalog Admin APIs](/pages/discounts-api-overview#custom-discount-properties "Discounts API Overview"). Note that once a property has been defined, it cannot be removed.
## Localize Discount Fields
If you have enabled [multiple locales for this catalog](/pages/multi-locale-catalogs "Multi-Locale Catalogs") , you can switch locales using the dropdown menu in the top right. This allows you to localize the discount name, description, and message text for that language. The discount type, application settings, target criteria, discount conditions, limitations, and other settings will not be displayed or editable, as those are only configurable on the default locale for the catalog.
## Configuration Examples
### Common Discount Examples
The following table lists some of the most common discounts and the configuration settings to replicate them.
The following examples do not include price lists. If you are using price lists, ensure that you add all applicable price lists to which you want the discount to apply in the **Applicable Price Lists** under the Discount's Target Criteria.
| Type of Discount | Required Fields |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Free Shipping on Orders over X Amount | Discount Applies To: **Order** |
| Discount Affects: **Shipping** | |
| Discount Type: **Free** | |
| Minimum Order Amount: **\$\_\_** | |
| *X*% off Order | Discount Applies To: **Order** |
| Discount Affects: **Product** | |
| Discount Type: **Percentage (\_%)** | |
| *X*% off a Product | Discount Applies To: **Line Item** |
| Discount Affects: **Product** | |
| Discount Type: **Percentage (\_%)** | |
| Applies to On Sale Products: **✓** | |
| . . .products that the shopper will receive the discount on: **1 of (Desired sale product(s))** | |
| *X*% off a Category | Discount Applies To: **Line Item** |
| Discount Affects: **Product** | |
| Discount Type: **Percentage (\_%)** | |
| Applies to On Sale Products: **✓** | |
| . . .categories that the shopper will receive the discount on: **1 of (Desired category/categories)**. You can select either static categories and/or dynamic categories that have been configured as discount targets. Refer to [Category Types](/pages/category-overview) for more information about the two different types of categories. | |
| Free Product with Purchase over X Amount | Discount Applies To: **Line Item** |
| Discount Affects: **Product** | |
| Discount Type: **Free** | |
| Shopper must purchase a quantity of any item(s) from the following categories: **(1) of (all categories)** | |
| Minimum Product Category Purchase Amount (pre-discount): **(\$\_\_)** | |
| Buy One Get One (BOGO) | Discount Applies To: **Line Item** |
| Discount Affects: **Product** | |
| Discount Type: **Free** | |
| Shopper must purchase a quantity of any one of the following items: **(*) of (*)** | |
| . . .products that the shopper will receive the discount on: **1 of (Desired free product(s))** | |
| *X*% off an Order when Visa Checkout is Used | Discount Applies To: **Order** |
| Discount Affects: **Product** | |
| Discount Type: **Percentage (\_%)** | |
| Required Payment Method: **Visa Checkout** | |
| Buy 5, Get 20% off Each 5 | Discount Applies To: **Line Item** |
| Discount Affects: **Product** | |
| Discount Type: **Percentage** | |
| Percentage Off: **20%** | |
| Shopper must purchase a quantity of any one of the following items: **5 of (\_)** | |
| . . .products that the shopper will receive the discount on: **5 of Required Purchase** | |
| Apply to items satisfying Required Purchase condition: **✓** | |
| Purchase Requirements: **Target Only** | |
Minimum Required Purchase Quantity Per Redemption: # product shopper must buy to qualify for discount
\| | Buy 5, Get 20% off Shipping for Each 5 | Discount Applies To: **Line Item**
Discount Affects: **Shipping**
Discount Type: **Percentage**
Percentage Off: **20%**
Shopper must purchase a quantity of any one of the following items: **5 of (product or category)**
. . .products that the shopper will receive the discount on: **5 of Required Purchase**
Apply to items satisfying Required Purchase condition: **✓**
Purchase Requirements: **Target Only**
Minimum Required Purchase Quantity Per Redemption: # product shopper must buy to qualify for discount
\| | Buy at least 5, Get 20% off Each | Discount Applies To: **Line Item**
Discount Affects: **Product**
Discount Type: **Percentage**
Percentage Off: **20%**
Shopper must purchase a quantity of any one of the following items: **5 of (product or category)**
. . .products that the shopper will receive the discount on: **Unlimited of Required Purchase**
Apply to items satisfying Required Purchase condition: **✓**
Purchase Requirements: **Target Only**
Minimum Required Purchase Quantity Per Redemption: # product shopper must buy to qualify for discount
### Greedy Discount
You have a discount that enables shoppers to buy three shirts (Minimum Required Quantity Per Redemption set to 3) to qualify for 20% off a purchase of up to five shirts, and you set the Max Redemptions to 1 for the discount. If you enable this option and:
* The shopper buys 1-2 shirts the discount does not apply.
* The shopper buys 3-5 shirts all the shirts receive a 20% discount.
* The shopper buys 6 shirts the discount applies only to the first five shirts. To get a discount on the 6th shirt and beyond, the discount would need additional or unlimited redemptions set in the Max Redemptions field.
If you do not set the purchase requirements field to Target Only, the discount does not apply to the first three shirts in the cart but does apply to additional shirts added to the cart up to five shirts.
### Discount Exclusion Examples
You may want to prevent some discounts from applying together. For example, you create a product discount named Discount A with a coupon code for \$50 off Product A. You also run other discounts at the same time, for example a product discount named Discount B that gives the shopper %20 off their order. You do not want Discount A to be combined with Discount B or any other discount.
To achieve this, you toggle the **Order Product**, **Line Item Product**, and **Order Shipping Settings** in the Discount Limitations configurations, indicating that Discount A should not be combined with any other discount.
# Configure Dropship
Source: https://docs.kibocommerce.com/pages/configure-dropship
This guide walks you through the Dropship capability end-to-end
Learn how operators invite and manage dropship vendors in Kibo Admin
Dropship spans two interfaces. The **Operator Portal** is the existing Kibo Admin, where the operator manages vendors, reviews documents, maps items, and activates partners. The **Vendor Portal** is a separate vendor-facing interface where each vendor self-onboards, configures fulfillment locations, and processes orders routed to them. Locations created in the Vendor Portal are mirrored into Kibo Admin, and every Dropship order surfaces in both portals — the vendor-facing PO Number on each order corresponds to the operator's Kibo Admin shipment number, so the same record can be tracked from both sides throughout fulfillment.
## **Platform Setup**
Before any dropship activity can occur, two things must be in place on the tenant. These are typically configured once during initial setup and do not need to be repeated for each new vendor.
1. Have Kibo Support enable the **DropShipEnabled** tenant attribute on your tenant. Once enabled, a new **Vendor** module appears in the Kibo Admin left navigation. Submit a request to [Kibo Support](https://help.kibocommerce.com/) if you want to use this feature.
2. Create a dedicated **location group** for all dropship locations and assign the **dropship fulfillment workflow** to that group. This is what causes shipments destined for vendor locations to enter the Order Acknowledgement → ASN sequence rather than the standard fulfillment workflow.
3. If you want vendors to ship on your carrier accounts, enable operator-managed shipping in Vendor Settings → Shipping Configuration, and ensure the **Location Group** tagged to vendor locations has the carrier accounts, predefined packages, and unit type configured. See Vendor Settings.
**Note:** The dedicated location group with the dropship fulfillment workflow must be in place before you can mark any vendor as Active. Without it, vendor fulfillment will not route through the correct two-step workflow.
# Configure Inventory
Source: https://docs.kibocommerce.com/pages/configure-inventory
You must enable inventory at the location level before you can begin to associate products with inventory.
Get an introduction to inventory management in Kibo
Note that changes to these settings may not immediately take effect when processing orders. It may take up to 15 minutes for updates to be reflected in the system while the cache refreshes.
## Enable Inventory
You must enable inventory support for one or more of your locations and then enable products for stock tracking before you can create inventory records and set quantities.
To enable inventory support for a location:
1. Go to **Main** > **Supply** > **Locations**.
2. Click a location to open its configuration details.
3. Under the **Location** section, enable **Location supports inventory**.
4. (**Optional**) Decide whether you want to **Allow fulfillment without stock on hand**.
This allows you to fulfill orders without sufficient on-hand quantities. This is useful if you want to mark items as fulfilled before entering newly arriving stock quantities in Kibo eCommerce. Refer to [Fulfill Items Without Sufficient Stock](/pages/fulfill-items-without-sufficient-stock) for more information.
5. Click **Save**.
To enable inventory for a product in the catalog:
1. Go to **Main** > **Sell** > **Products**.
2. Click a product to open its configuration details.
3. Go to **Product Editor** > **Inventory** and enable **Track stock level**.
4. Click **Save**.
Note that if you click **Manage Inventory** in the product configurations shown above, you will be taken to the Inventory UI filtered to that product. If it's a configurable product with options, then the base product code will be used.
## Create Inventory Records
**Note:** The Inventory UI has been updated with a new look and feel and new functional changes, and has been renamed to **Supply/Demand UI**. Contact [Kibo Support](https://help.kibocommerce.com/) to opt in and begin using it. All sandbox tenants will receive the new UI on July 21. Select the tab below based on which UI your tenant is currently using.
You can create inventory records and set quantities from the Inventory UI.
1. Go to **Main** > **Supply** > **Inventory**.
2. Click **Create New Inventory**. This will add an empty row to the table.
3. Enter a product code and select a location, then enter the On Hand and any other inventory values you want to include such as LTD, Floor, Safety Stock or Excess Inventory Threshold. The below example shows a basic inventory record without additional [granular inventory fields](/pages/granular-inventory-fields "Granular Inventory Fields") or [tags](/pages/inventory-segmentation-overview "Inventory Segmentation Overview").
If you want to set Safety Stock levels automatically upon inventory refreshes, based on criteria such as product types and location groups, you can use [Safety Stock Rules](/pages/safety-stock-rules "Safety Stock Rules").
4. Click **Save**.
1. Go to **Main > Supply > Inventory**.
2. Click **+ Create Inventory**. A right-side drawer opens.
3. Enter a **UPC / Product Code** (required) and select a **Location**(required).
4. Enter **On Hand**(required) and any other applicable values: LTD, Floor, Safety Stock, Excess Inventory Threshold.
> **Available quantity:** By default, Available is computed from On Hand. If your tenant has the `isTenantEnabledToSetAvailableQuantity` flag enabled, an Available quantity field appears and can be edited directly.
5. *(Tags-enabled tenants only)* A tag selector appears. Select a tag to create the record at that tag level. Without a selection, the record is created at the UPC-location level.
6. *(Granular-enabled tenants only)* [Granular fields](/pages/granular-inventory-fields) appear: SKU, Lot Code, Date, Condition, Serial No. These are optional unless your configuration requires them. At max you can add 10 granular records.
**Note:** Serial No: On Hand cannot exceed 1 when a Serial No is entered. Condition: Appears as a dropdown only when values exist in Settings > Condition Availability
7. Click **Save**.
## Adjust Inventory Quantities
**Note:** The Inventory UI has been updated with a new look and feel and new functional changes, and has been renamed to **Supply/Demand UI**. Contact [Kibo Support](https://help.kibocommerce.com/) to opt in and begin using it. All sandbox tenants will receive the new UI on July 21. Select the tab below based on which UI your tenant is currently using.
You can adjust the On Hand, LTD, Floor, Safety Stock and Excess Inventory Threshold quantity of existing inventory records at any time via the Inventory UI. You can also update inventory quantities via the [Refresh](/api-reference/modifyinventory/refresh) and [Adjust](/api-reference/modifyinventory/adjust) APIs or [inventory import process](/pages/inventory-import-file) instead.
1. Go to **Main** > **Orders** > **Inventory.**
2. Either select the **Location Name** from the drop-down menu or enter a **Product Code** to view inventory levels.
3. Expand the actions menu on the far right of an inventory row and click **Edit**. This will make the fields editable for you to enter a new quantity.
* Note that if the inventory record includes [granular fields](/pages/granular-inventory-fields "Granular Inventory Fields") or [tagged inventory](/pages/inventory-segmentation-overview "Inventory Segmentation Overview"), the total cannot be edited at the top level. You must update the quantity for a specific granular field or tag instead.
4. Click **Save**.
Click **Delete** in the actions menu if you want to completely remove a record instead. If the inventory record includes granular fields or segmented tags, they will be removed as well.
**View a record**
Click **View** on any row (or anywhere on the row) to open the read-only drawer. Fields are organized into tabs:
* **Summary tab** — shows all available Inventory metrics like On Hand, Available, Allocated, Pending, Safety Stock, Floor, LTD, Excess Inventory Threshold, Excess.
* **Tags tab** — per-tag quantities (shown when Tags are enabled)
* **Granular tab** — individual granular records (shown when Granular Inventory is enabled)
* **Future tab** — future inventory for this product-location upto the future Date range selected in search section, with a link to open the Future Inventory page with filters pre-populated
**Edit a record**
You can adjust the On Hand, LTD, Floor, Safety Stock and Excess Inventory Threshold quantity of existing inventory records at any time via the Inventory UI. You can also update inventory quantities via the [Refresh](/api-reference/modifyinventory/refresh) and [Adjust](/api-reference/modifyinventory/adjust) APIs or [inventory import process](/pages/inventory-import-file) instead. Click **Edit** on any inventory record row. Editable fields depend on tenant configuration:
| Tenant setup | What's editable |
| :------------------- | :------------------------------------------------------------------------------------------------ |
| No tags, no granular | On Hand, LTD, Floor, Safety Stock, Excess Inventory Threshold, inventory attributes |
| Tags enabled | Quantity fields per tag (inside Tags tab); LTD, Floor, Safety Stock at UPC-location level |
| Granular enabled | On Hand per granular record (inside Granular tab); LTD, Floor, Safety Stock at UPC-location level |
If future inventory is searched - Future Tab allows to edit individual future inventory record.
Click **Save** to apply changes.
**Delete a record**
Click **Delete** on a row. Confirm when prompted. This removes the entire product-location record.
*Delete at tag level:* Open the Edit drawer → Tags tab → click the delete icon on the target tag row. Removes only that tag, not the full product-location record.
*Delete at granular level:* Open the Edit drawer → Granular tab → click the delete icon on the target granular row.
By default, you can only update On Hand quantities and the system will calculate the appropriate Available amount. If you want to change this behavior so that you can directly edit the Available inventory value, contact [Kibo Support](https://help.kibocommerce.com/) to update your tenant configurations.
# Configure Inventory Tags
Source: https://docs.kibocommerce.com/pages/configure-inventory-tags
To use inventory segmentation, you need to enable them on your tenant and then configure your tags.
**Note:** The Inventory UI has been updated with a new look and feel and new functional changes, and has been renamed to **Supply/Demand UI**. Contact [Kibo Support](https://help.kibocommerce.com/) to opt in and begin using it. All sandbox tenants will receive the new UI on July 21. Select the tab below based on which UI your tenant is currently using.
## Enable Inventory Tags
Tags must be enabled and configured before inventory can be used in segments.
1. Click **Inventory Settings** in the Inventory UI to access the inventory configurations.
2. Under the Inventory Tags section, click **Enable Inventory Tags** to toggle this functionality on.
This will create an empty table where tags will be displayed once created.
Tags must be enabled and configured before inventory can be used in segments.
1. Click **Inventory Settings** in the Supply Demand Menu to access the inventory configurations.
2. Under the Inventory Tags section, click **Enable Inventory Tags** to toggle this functionality on.
This will create an empty table where tags will be displayed once created.
## Create Inventory Tags
You can create new tags by clicking **Create Inventory Tag**. A pop-up will appear with configuration settings. There is a default maximum limit of 3 tags per tenant and 6 tag values per tenant (across all tags).
1. Enter a **Tag Name** (such as Channel). This name is sometimes referred to as a "tag category" in APIs or other resources.
2. Enter a default **Tag Value** (such as Amazon). At least one value is required to be set, as if no tag is specified for an inventory item then it will use this first value instead.
3. If desired, set the **Inventory Allocation** percentage. This will determine how much of the total inventory is made available for this segment. In this example, 50% of the discrete total inventory will always be allocated for the Amazon sales channel. If you want to use discrete values for your inventory segmentation instead of a percentage, you must leave the Inventory Allocation % field blank. If you do set percentage values but want to switch to discrete values later, you must delete all tags and re-add them without percentages to view discrete inventory.
4. Click **Add Tag Value** to create another option for this tag. All values that you add should be unique within their tag name.
5. If an allocation percentage is specified for each value, then all of the percentages must add up to 100%.
* In the below example, the first value is allocated at 50% so additional tags could be created with allocations of 20% and 30%. However, it is not required to set these percentages – if any are left blank, then validation will not be done for that tag value when inventory levels are refreshed. It will effectively accept any amount of inventory, as long as other values' percentage requirements are satisfied first.
6. Click **Create** to save the tag.
You can create new tags by clicking **Create Inventory Tag**. A Drawer will appear with configuration settings. There is a default maximum limit of 3 tags per tenant and 6 tag values per tenant (across all tags).
1. Enter a **Tag Name** (such as Channel). This name is sometimes referred to as a "tag category" in APIs or other resources.
2. Enter a default **Tag Value** (such as Amazon). At least one value is required to be set, as if no tag is specified for an inventory item then it will use this first value instead
3. If desired, set the **Inventory Allocation** percentage. This will determine how much of the total inventory is made available for this segment. In this example, 50% of the discrete total inventory will always be allocated for the Amazon sales channel. If you want to use discrete values for your inventory segmentation instead of a percentage, you must leave the Inventory Allocation % field blank. If you do set percentage values but want to switch to discrete values later, you must delete all tags and re-add them without percentages to view discrete inventory.
4. Click **Add Tag Value** to create another option for this tag. All values that you add should be unique within their tag name.
5. If an allocation percentage is specified for each value, then all of the percentages must add up to 100%.
* In the below example, the first value is allocated at 50% so additional tags could be created with allocations of 20% and 30%. However, it is not required to set these percentages – if any are left blank, then validation will not be done for that tag value when inventory levels are refreshed. It will effectively accept any amount of inventory, as long as other values' percentage requirements are satisfied first.
6. Click **Save** to Create the tag.
## View and Update Tags
Once set, the new tag is added to the Inventory Tags table. Click a tag in the table to expand its details and view the possible values and allocation percentages.
You can use the dropdown menu shown below to **Edit** or **Delete** a tag instead. Editing will open the same pop-up as used for tag creation, allowing you to update all values, change the default value, and delete any non-default values.
Inventory should be periodically redistributed between your channels based on the allocation percentages. You can do this on-demand by calling the [Inventory Redistribution API](/pages/inventory-api-overview#inventory-redistribution "Inventory API Overview") with the UPCs and/or location codes you want to redistribute across. Asynchronous redistribution will then occur at the next Refresh or Adjust update to restore the appropriate amount of inventory to the designated channels.
Once set, the new tag is added to the Inventory Tags table. Click the edit icon in the table to view and edit its details and view the possible values and allocation percentages.
Editing will open the same Drawer as used for tag creation, allowing you to update all values, change the default value, and delete icon will allow to delete Tag.
Inventory should be periodically redistributed between your channels based on the allocation percentages. You can do this on-demand by calling the [Inventory Redistribution API](/pages/inventory-api-overview#inventory-redistribution "Inventory API Overview") with the UPCs and/or location codes you want to redistribute across. Asynchronous redistribution will then occur at the next Refresh or Adjust update to restore the appropriate amount of inventory to the designated channels.
# Configure Product Types
Source: https://docs.kibocommerce.com/pages/configure-product-types
To create a new product type:
See how to create and manage product types
1. Go to **System** > **Schema** > **Product Types**.
2. Click **Create New Product Type**.
3. Enter a **Name**.
4. In the **Support Usage Types** list, select the options that apply to your product type:
* Standard Product
* Configurable Product With Options
* Product Bundle
* Bundle Component
* Collection
5. Under each attribute type, click **Add** to associate attributes with this product type.
Depending on the attribute type that you add to the product type and the attribute's input values, you might be required to select specific configurations of the attribute. Refer to [Product Attributes](/pages/product-attributes-overview) for more information about adding attributes to a product type.
6. In the **Advanced** section, select whether this product type is a physical item, service item, digital item, digital credit item, or digital gift card. This will determine the product type's "goods type" which is an irreversible setting and will impact the workflow of shipments with items of that product type.
* **Physical:** This is the default goods type used by most products. They can be associated with inventory which will be referenced when creating, assigning, and fulfilling shipments with these items.
* **Service:** Used only for [service items such as assembly](/pages/fulfillment-service-items "Fulfillment Service Items").
* **Digital**: Used for [digital items](/pages/fulfillment-method-types#digital-item-fulfillment "Fulfillment Method Types") other than gift cards or store credit, such as warranties or service fees. This does not include digital art, books, music, printable documents, or software. These items will be immediately fulfilled and captured upon order placement.
* **Digital Credit:** Creates a [store credit](/pages/store-credit-and-gift-cards "Store Credit and Gift Cards") record assigned to the customer who placed the order. These items will be immediately fulfilled and captured upon order placement.
* **Digital Gift Card:** Used when a customer purchases a [digital gift card](/pages/digital-gift-card-overview "Digital Gift Card Overview"). These items will be immediately fulfilled and captured upon order placement.\\
7. Click **Save**.
You can update a product or multiple products' product types at once using the [Quick Edits](/pages/quick-edits "Quick Edits") tool.
# Configure Products
Source: https://docs.kibocommerce.com/pages/configure-products
After creating [product attributes](/pages/product-attributes-overview) and [product types](/pages/product-types-overview), you can then create products to sell on your Kibo eCommerce storefront.
See how to create a new standard product
Learn how to create products with configurable options
The way that these products display can be further configured with [slicing](/pages/product-slicing) to show variants of a product separately in search results and category pages.
You can also use a Postman Runner to update products with the [Kibo Catalog APIs.](/api-overviews/openapi_catalog_admin_overview)
## Create Products
Once you create product attributes and product types you can then create your products to sell on your storefront. When you create products you can also choose to create product variations if your product includes configurable options.
To create a new product:
1. Go to **Main** > **Sell** > **Products**.
2. Click **Create New Product** in the top right.
3. Select the catalog you wish to add the product to by clicking the pencil icon in the **Catalogs** bar and selecting which catalogs to add to the list.
Ensure that you have the correct master catalog selected, because once you add a product to a catalog you cannot move that product to another catalog that belongs to a different master catalog. However, you can always move products between catalogs that belong to the same master catalog.
4. Once added, you can click any of the catalogs in the list to configure the product specifically within that catalog. Some settings are only available at the master catalog level, while others are only available at the child catalog level.
5. At the master catalog level, enter the following **General** settings:
* Product Title
* Product Code (at least 3 and up to 30 characters)
* Product Type
* Product Usage (this will determine what other configuration sections are displayed on the page, such as Inventory, Properties, Shipping, Bundle Items, and SEO)
* Short Description (260 character limit)
* Long Description
* Product Image
* Pricing Information
* And any other configuration sections that appeared when you selected a Product Usage (see Step #8 and beyond for more detailed descriptions of these possible settings)
6. At each child catalog level, select the following **General** settings:
* Status (Active, Disabled, or Scheduled, which allows you to schedule the product to be active during a specific time-frame on your storefront)
* If Scheduled was selected as the Status, then select the Active Start Date and Active End Date. See the [Schedule Products](/pages/schedule-products) guide for more information about this behavior.
* [First Available Date](/pages/schedule-products#first-available-date) (allows you to specify the date the product either becomes or became first available in the specific catalog)
7. Continue down the page to the other configuration sections that appeared below General when you selected a Product Usage.
8. If the **Inventory** section is available, you can track stock level and determine the behavior when the product goes out of stock. When you product goes out of stock, you can opt to show an out of stock message, allow backordering, or hide product in store. If you decide to track inventory for a product, refer to [Inventory Management](/concept-guides/inventory) for information.
You must configure one or more locations for the Inventory section to appear. Refer to [Location Settings](/pages/location-types) for more information about configuring locations.
9. Depending on what you selected for Product Usage, you may have **Options**, **Properties**, and/or **Extras** to enter. Refer to [Product Attributes](/pages/product-attributes-overview) for more information about assigning attribute values to a product, and refer to [Dynamic Imaging](/pages/dynamic-imaging) for more information about assigning images to specific variants.
If your product includes options, in the **Options** section select a **Pricing Mode** and click **Select Values** to edit the product’s variants. In the **Edit Variants** window, click **Update Options** to create a [product variation](/pages/product-variations) and click the **Enabled** checkbox next to each variant you want to enable. Refer to [Product Variant Pricing](/pages/product-variations#product-variant-pricing-and-weight) for more information about product variant pricing.
10. If the **Shipping** section is displayed, select whether the product is available for direct ship, in-store pick up, or both. You can also specify whether the item must ship in a package by itself (such as for fragile items), the weight, and appropriate package dimensions in this section.
11. The **Categories** section is only displayed if you clicked on a child catalog to configure the product on that site (as products cannot be assigned to categories at the master catalog level). Here, select the static categories of which the product is a member. Alternatively, you can create dynamic categories to automatically add products to depending on specific configuration options. Refer to [Dynamic Categories](/pages/dynamic-categories) for more information.
You must first create static categories before you can assign products to a static category. Refer to [Static Categories](/pages/static-categories) for more information.
12. If you assign a product to more than one static category, then you can use the **Primary Category** field to specify which static category to use in the navigation breadcrumb, regardless of how shoppers navigate to the product. If not set, or if the product belongs only to dynamic categories, the default is to use the category with the smallest ID.
13. If the **SEO** section is available, use the available fields to enter SEO information:
| Field Name | SEO Effect |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Meta Title | Maps to the HTML meta title tag. While most search engines place little value on this tag, most Kibo eCommerce themes inject the value of the meta title tag into the HTML title tag. |
| The HTML title tag is used by search engines and browsers to display the title of the page, and is critical to SEO. Search engines place very high importance on the correlation between a page's title tag and its content. | |
| Slug | The default URL structure for products is `yourSite.com/{slug}/p/{productCode}` and for categories is `yourSite.com/{slug}/c/{categoryId}`. The slug (or SEO-friendly URL) gives you the ability to add a meaningful component to the URL structure in order to boost search results. |
| Meta Description | Maps to the HTML meta description tag, which is used by search engines to summarize the content of the page. |
| Meta Keywords | Maps to the HTML meta keywords tag, which is used to tell search engines what the page is about. From an SEO-perspective, search engines place little value on this tag, but the Kibo eCommerce search implementation uses these keywords to help construct search results for pages on your storefront. |
14. If you have enabled [multiple locales for this catalog](/pages/multi-locale-catalogs "Multi-Locale Catalogs"), you can switch locales using the dropdown menu in the top right. This allows you to localize the product title, images, descriptions, customizable string properties, and SEO fields for that language. The pricing, inventory, shipping, extras, and other settings will not be displayed or editable, as those are only configurable on the default locale for the catalog.
15. Depending on your [Product Publishing settings](/pages/publishing-settings), you can either have the product publish immediately or be saved as a product draft:
* If your Product Publishing settings are set to Live, click **Save** to make the product live on your storefront.
* If your Product Publishing settings are set to Staged, click **Save** to save your changes as a [draft](/pages/drafts), and then decide to either publish the draft immediately or move it to a Publish Set.
## Add Products to Catalogs
You add existing products to catalogs using the product details:
1. Go to **Main** > **Sell** > **Products**.
2. Select your product.
3. In the Catalogs list, click **Edit** to add your product to a specific catalog.
4. If you want to change the product's details for a specific catalog such as price or descriptions, select that catalog’s tab and check **Override global**.
5. Click **Save** in the top right.
# Configure Shipment Creation
Source: https://docs.kibocommerce.com/pages/configure-shipment-creation
By default, shipments are created immediately upon order submission which means you must make edits to order items and pricing at the shipment level. You can change this behavior to delay shipment creation and inventory allocation to a preset time after submission.
Delaying shipment creation gives your customer service representatives more flexibility to edit orders after submission. This allows you to offer a remorse period, in which orders can be cancelled within a certain time frame with minimal downstream effects. This reduces the rate of item returns and cancellations after shipments are already fulfilled or in the process of being fulfilled.
When you have configured shipment creation to a later date, [future inventory](/pages/future-inventory "Future Inventory") and [reservations](/pages/reserve-inventory-in-cart "Reserve Inventory in Cart") will still be supported by those shipments. However, there are some special behaviors defined in this guide.
## Enable Shipment Release
Your site settings determine when to create the shipment and allocate inventory after order submission. If not configured, shipments will be created immediately.
Before you can configure shipment creation, you need to submit a [Kibo Support](https://help.kibocommerce.com/) request to enable the feature on your tenant. Then:
1. Go to **System** > **Settings** > **General** > **Site** > **Fulfillment Settings**.
2. Toggle **Enable configurable shipment release** on.
3. Toggle **Refresh Pricing on Order Edit** on if you have an Order Management with Catalog implementation and want to modify [repricing behavior](/pages/edit-order-items#order-item-edits "Edit Order Items") when edits are being done to orders in Pending Shipment status.
4. Enter a value for **Release orders** **\_ minutes after order submit**. This can be any number between 1-7200.
5. If desired, enable **Reserve inventory when order status is PendingShipment**. If enabled, inventory will be reserved when the order is submitted. If disabled, then inventory will be reserved upon shipment creation.
6. Click **Save** in the top right.
## Pending Shipments Status
When this feature is enabled, orders will be put into the [Pending Shipments status](/pages/order-statuses "Order Statuses") upon submission. The Order Confirmation email will be triggered at this time, if enabled. During this status, you will also be able to make edits at the order level such as changing item quantity, pricing, and adding new items. Once shipments are created, the order will move out of Pending Shipments and any further edits must be made at the shipment level instead.
If an order is in Pending Review status and is accepted, then the system will first look at the shipment creation date of the order. If the date has passed, then the system will release the order and create the shipments. If the date has not yet passed, then the order will not be released from fraud until that date is reached.
## Inventory Reservations
There are some special behaviors to be aware of when using [inventory reservations](/pages/reserve-inventory-in-cart "Reserve Inventory in Cart"). If you opted to reserve inventory on the Pending Shipment status:
* Inventory will automatically be reserved when the order is submitted. If any items were already reserved in the cart, then that reservation will carry over to the order and any additional items will be added to the existing reservation.
* If you do not reserve any inventory in the cart, then a new reservation will be created for the order and those items will be reserved while waiting for the shipment(s) to be created.
* If any edits are made to the order items, such as changing quantity, then the system will check whether the **Reserve Inventory when order status is pending shipment** setting is enabled and whether the changed item is part of the existing reservation. If either of these are true, the reservation will be updated.
If you opted to not reserve inventory on the Pending Shipment status, but you do reserve inventory in the cart:
* The cart reservation will still carry over to the order and be reserved upon shipment creation (which is the default behavior without the Pending Shipment setting enabled) but any additional unreserved items will not be added to the existing reservation.
* If new item(s) are added to the order, the system will check whether to add them to the reservation or not based on the **Reserve Inventory when order status is pending shipment** setting. If this setting is enabled, then the new item(s) will be added to the existing reservation.
## API Override
You can override the shipment creation site setting for a particular order via the [Create Order API](/api-reference/order/create-order) and [Update Order API](/api-reference/order/update-order). This is useful in cases such as if your shipments are set to be delayed for one day but you know you won't be able to fulfill them for another two days. In that case, you can delay the shipment creation by an extra day either upon order creation or after the order has been created.
This top-level field is called `shipmentCreationOffset` in the API request, as found in the below example. The value determines the amount of minutes that shipment creation is delayed by, and can be -1 or any number between 1 and 7200. If -1, then the shipment delay will be bypassed and shipments will be immediately created without sending the order into the Pending Shipment status.
```
"shipmentCreationOffset": 1440,
"version": "1",
"isPartialOrder": false,
"availableActions": [
"ValidateOrder",
"SetOrderAsProcessing",
"CancelOrder"
],
"customerAccountId": 1000,
"isTaxExempt": false,
"email": "Admin@kibocommerce.com",
"ipAddress": "172.16.254.150",
"type": "Offline",
"paymentStatus": "Unpaid",
"returnStatus": "None",
"isEligibleForReturns": false,
"totalCollected": 0,
"attributes": [],
"shippingDiscounts": [],
"handlingDiscounts": [],
"handlingTotal": 0,
"fulfillmentStatus": "NotFulfilled",
"isFulfillable": false,
"submittedDate": "2023-02-24T11:51:09.690Z",
"releaseShipmentDate": "2023-02-23T21:31:09.690Z",
"acceptedDate": "2023-02-24T12:04:45.253Z",
"notes": [],
"items": [
{
"id": "194d203d2e784268ac05afb300c33ed8",
"fulfillmentLocationCode": "Loc1",
"fulfillmentMethod": "Ship",
"isReservationEnabled": false,
"lineId": 1,
"product": {
"mfgPartNumber": "SP_01",
"sku": "SP_01",
"fulfillmentTypesSupported": [
"DirectShip",
"InStorePickup"
],
"options": [],
"properties": [],
"categories": [],
"price": {
"price": 10
},
"discountsRestricted": false,
"isTaxable": true,
"productType": "standard",
"productUsage": "Standard",
"bundledProducts": [],
"productCode": "SP_01",
"name": "SP_01",
"goodsType": "Physical",
"isPackagedStandAlone": false,
"stock": {
"manageStock": true,
"isOnBackOrder": false,
"stockAvailable": 75,
"aggregateInventory": 0,
"isSubstitutable": false
},
"measurements": {
"height": {
"unit": "in",
"value": 1
},
"width": {
"unit": "in",
"value": 1
},
"length": {
"unit": "in",
"value": 1
},
"weight": {
"unit": "lbs",
"value": 1
}
},
"fulfillmentStatus": "PendingFulfillment"
},
"quantity": 1,
"subtotal": 10,
"extendedTotal": 10,
"taxableTotal": 10,
"discountTotal": 0,
"discountedTotal": 10,
"itemTaxTotal": 0,
"shippingTaxTotal": 0,
"shippingTotal": 0,
"feeTotal": 0,
"total": 10,
"unitPrice": {
"extendedAmount": 10,
"listAmount": 10
},
"productDiscounts": [],
"shippingDiscounts": [],
"auditInfo": {
"updateDate": "2023-02-24T11:50:52.057Z",
"createDate": "2023-02-24T11:50:52.057Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
},
"shippingAmountBeforeDiscountsAndAdjustments": 0,
"weightedOrderAdjustment": 0,
"weightedOrderDiscount": 0,
"adjustedLineItemSubtotal": 10,
"totalWithoutWeightedShippingAndHandling": 10,
"weightedOrderTax": 0,
"weightedOrderShipping": 15,
"weightedOrderShippingDiscount": 0,
"weightedOrderShippingManualAdjustment": 0,
"weightedOrderShippingTax": 0,
"weightedOrderHandlingFee": 0,
"weightedOrderHandlingFeeTax": 0,
"weightedOrderHandlingFeeDiscount": 0,
"weightedOrderDuty": 0,
"totalWithWeightedShippingAndHandling": 25,
"weightedOrderHandlingAdjustment": 0,
"isAssemblyRequired": false
}
],
"validationResults": [],
"billingInfo": {
"billingContact": {
"id": 1000,
"email": "Admin@kibocommerce.com",
"firstName": "anagha",
"lastNameOrSurname": "deshmukh",
"phoneNumbers": {
"home": "5129991111"
},
"address": {
"address1": "State Capital, Suite 1173",
"cityOrTown": "Sacramento",
"stateOrProvince": "CA",
"postalOrZipCode": "95814",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"auditInfo": {
"updateDate": "2023-02-24T11:50:42.192Z",
"createDate": "2023-02-24T11:50:42.192Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
},
"isRecurring": false
},
"payments": [],
"refunds": [],
"credits": [],
"packages": [],
"pickups": [],
"digitalPackages": [],
"isDraft": false,
"hasDraft": false,
"isImport": false,
"isHistoricalImport": false,
"isUnified": true,
"couponCodes": [],
"invalidCoupons": [],
"amountAvailableForRefund": 0,
"amountRemainingForPayment": 25,
"amountRefunded": 0,
"readyToCapture": false,
"isOptInForSms": false,
"continuityOrderOrdinal": 0,
"userId": "2406bfcddf3e4f5d94a2b1626f3f8cfd",
"id": "14f9028614d09a0001bbaedc00004856",
"tenantId": 18518,
"siteId": 23414,
"channelCode": "test",
"currencyCode": "USD",
"customerInteractionType": "Unknown",
"fulfillmentInfo": {
"fulfillmentContact": {
"id": 1000,
"email": "Admin@kibocommerce.com",
"firstName": "anagha",
"lastNameOrSurname": "deshmukh",
"phoneNumbers": {
"home": "5129991111"
},
"address": {
"address1": "State Capital, Suite 1173",
"cityOrTown": "Sacramento",
"stateOrProvince": "CA",
"postalOrZipCode": "95814",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"shippingMethodCode": "b9742c08b30749c487f7afaf0129a8fd",
"shippingMethodName": "Flat Rate",
"auditInfo": {
"updateDate": "2023-02-24T11:51:01.084Z",
"createDate": "2023-02-24T11:50:29.667Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"orderDiscounts": [],
"suggestedDiscounts": [],
"subtotal": 10,
"discountedSubtotal": 10,
"discountTotal": 0,
"discountedTotal": 10,
"shippingTotal": 15,
"shippingSubTotal": 15,
"shippingTaxTotal": 0,
"handlingTaxTotal": 0,
"itemTaxTotal": 0,
"taxTotal": 0,
"feeTotal": 0,
"total": 25,
"lineItemSubtotalWithOrderAdjustments": 10,
"shippingAmountBeforeDiscountsAndAdjustments": 15,
"lastValidationDate": "2023-02-24T11:50:53.798Z",
"changeMessages": [
{
"id": "9092b52fbece4c6d8c68afb300c3256e",
"correlationId": "ac4b3ab78b5c498a8cc01864b5556620",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "Kibo",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.2302.2.0.Release",
"subjectType": "StateChange.WorkflowAction",
"success": true,
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "CreateOrder",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"oldValue": "Null",
"newValue": "Pending"
}
],
"oldValue": "Null",
"newValue": "Pending",
"createDate": "2023-02-24T11:50:30.337Z"
},
{
"id": "55fa337c3ed04bad94a3afb300c32f6d",
"correlationId": "56ee2068ab1c44d38ee5e0d9e8eda00d",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "Kibo",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.2302.2.0.Release",
"subjectType": "Order",
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "Fulfillment Info Updated",
"verb": "Updated",
"message": "Fulfillment Info Updated",
"metadata": [
{
"updatedFulfillment": {
"FulfillmentContact": {
"Id": 1000,
"Email": "Admin@kibocommerce.com",
"FirstName": "anagha",
"LastNameOrSurname": "deshmukh",
"PhoneNumbers": {
"Home": "5129991111"
},
"Address": {
"Address1": "State Capital, Suite 1173",
"Address2": null,
"Address3": null,
"Address4": null,
"CityOrTown": "Sacramento",
"StateOrProvince": "CA",
"PostalOrZipCode": "95814",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": false
}
},
"ShippingMethodCode": null,
"ShippingMethodName": null,
"IsDestinationCommercial": null,
"Data": null,
"AuditInfo": {
"UpdateDate": "2023-02-24T11:50:38.8594175Z",
"CreateDate": "2023-02-24T11:50:29.667Z",
"UpdateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"CreateBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"originalFulfillment": {
"FulfillmentContact": null,
"ShippingMethodCode": null,
"ShippingMethodName": null,
"IsDestinationCommercial": null,
"Data": null,
"AuditInfo": {
"UpdateDate": "2023-02-24T11:50:29.667Z",
"CreateDate": "2023-02-24T11:50:29.667Z",
"UpdateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"CreateBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
}
}
],
"createDate": "2023-02-24T11:50:38.868Z"
},
{
"id": "1852516b6c064521974dafb300c332a2",
"correlationId": "fec3bcd49cab4d588b5c86f5f735806d",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "Kibo",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.2302.2.0.Release",
"subjectType": "Order",
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "Fulfillment Info Updated",
"verb": "Updated",
"message": "Fulfillment Info Updated",
"metadata": [
{
"updatedFulfillment": {
"FulfillmentContact": {
"Id": 1000,
"Email": "Admin@kibocommerce.com",
"FirstName": "anagha",
"LastNameOrSurname": "deshmukh",
"PhoneNumbers": {
"Home": "5129991111"
},
"Address": {
"Address1": "State Capital, Suite 1173",
"Address2": null,
"Address3": null,
"Address4": null,
"CityOrTown": "Sacramento",
"StateOrProvince": "CA",
"PostalOrZipCode": "95814",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": false
}
},
"ShippingMethodCode": null,
"ShippingMethodName": null,
"IsDestinationCommercial": null,
"Data": null,
"AuditInfo": {
"UpdateDate": "2023-02-24T11:50:41.589849Z",
"CreateDate": "2023-02-24T11:50:29.667Z",
"UpdateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"CreateBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"originalFulfillment": {
"FulfillmentContact": {
"Id": 1000,
"Email": "Admin@kibocommerce.com",
"FirstName": "anagha",
"LastNameOrSurname": "deshmukh",
"PhoneNumbers": {
"Home": "5129991111"
},
"Address": {
"Address1": "State Capital, Suite 1173",
"Address2": null,
"Address3": null,
"Address4": null,
"CityOrTown": "Sacramento",
"StateOrProvince": "CA",
"PostalOrZipCode": "95814",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": false
}
},
"ShippingMethodCode": null,
"ShippingMethodName": null,
"IsDestinationCommercial": null,
"Data": null,
"AuditInfo": {
"UpdateDate": "2023-02-24T11:50:38.859Z",
"CreateDate": "2023-02-24T11:50:29.667Z",
"UpdateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"CreateBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
}
}
],
"createDate": "2023-02-24T11:50:41.603Z"
},
{
"id": "beca8f9710f14b3ba237afb300c33fcf",
"correlationId": "f87d4450f1c242f9949ceacc1933270c",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "Kibo",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.2302.2.0.Release",
"subjectType": "OrderItem",
"identifier": "194d203d2e784268ac05afb300c33ed8",
"subject": "Item Added",
"verb": "Added",
"message": "Product SP_01 (Code: SP_01) was added.",
"metadata": [
{
"productCode": "SP_01",
"productName": "SP_01",
"quantity": 1
}
],
"createDate": "2023-02-24T11:50:52.848Z"
},
{
"id": "98f41af1c579410fb71dafb300c34976",
"correlationId": "778581b6a3be482e87077ededa60b542",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "Kibo",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.2302.2.0.Release",
"subjectType": "Order",
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "Fulfillment Info Updated",
"verb": "Updated",
"message": "Fulfillment Info Updated",
"metadata": [
{
"updatedFulfillment": {
"FulfillmentContact": {
"Id": 1000,
"Email": "Admin@kibocommerce.com",
"FirstName": "anagha",
"LastNameOrSurname": "deshmukh",
"PhoneNumbers": {
"Home": "5129991111"
},
"Address": {
"Address1": "State Capital, Suite 1173",
"Address2": null,
"Address3": null,
"Address4": null,
"CityOrTown": "Sacramento",
"StateOrProvince": "CA",
"PostalOrZipCode": "95814",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": false
}
},
"ShippingMethodCode": "b9742c08b30749c487f7afaf0129a8fd",
"ShippingMethodName": "Flat Rate",
"IsDestinationCommercial": null,
"Data": null,
"AuditInfo": {
"UpdateDate": "2023-02-24T11:51:01.0845537Z",
"CreateDate": "2023-02-24T11:50:29.667Z",
"UpdateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"CreateBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"originalFulfillment": {
"FulfillmentContact": {
"Id": 1000,
"Email": "Admin@kibocommerce.com",
"FirstName": "anagha",
"LastNameOrSurname": "deshmukh",
"PhoneNumbers": {
"Home": "5129991111"
},
"Address": {
"Address1": "State Capital, Suite 1173",
"Address2": null,
"Address3": null,
"Address4": null,
"CityOrTown": "Sacramento",
"StateOrProvince": "CA",
"PostalOrZipCode": "95814",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": false
}
},
"ShippingMethodCode": null,
"ShippingMethodName": null,
"IsDestinationCommercial": null,
"Data": null,
"AuditInfo": {
"UpdateDate": "2023-02-24T11:50:41.589Z",
"CreateDate": "2023-02-24T11:50:29.667Z",
"UpdateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"CreateBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
}
}
],
"createDate": "2023-02-24T11:51:01.085Z"
},
{
"id": "813fa05e2b3149c5a234afb300c353ad",
"correlationId": "273fda8718ff4027b77654207a76e034",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "Kibo",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.2302.2.0.Release",
"subjectType": "StateChange.WorkflowAction",
"success": true,
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "SubmitOrder",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"oldValue": "Pending",
"newValue": "Submitted"
}
],
"oldValue": "Pending",
"newValue": "Submitted",
"createDate": "2023-02-24T11:51:09.800Z"
},
{
"id": "c5e7a806bacb411da871afb300c358f1",
"correlationId": "",
"subjectType": "StateChange.WorkflowAction",
"success": true,
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "ValidateOrder",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"oldValue": "Submitted",
"newValue": "Validated"
}
],
"oldValue": "Submitted",
"newValue": "Validated",
"createDate": "2023-02-24T11:51:14.293Z"
},
{
"id": "123a79a60d3e413eb514afb300c35907",
"correlationId": "",
"subjectType": "StateChange.WorkflowAction",
"success": true,
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "PendingShipmentOrder",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"oldValue": "Validated",
"newValue": "PendingShipment"
},
{
"releaseShipmentDate": "2023-02-24T21:31:09.69Z"
}
],
"oldValue": "Validated",
"newValue": "PendingShipment",
"createDate": "2023-02-24T11:51:14.366Z"
},
{
"id": "6861efc4731f45d9a9bfafb300c70f49",
"correlationId": "",
"subjectType": "shipment.create",
"subject": "Shipments created",
"verb": "Created",
"message": "Created shipments 18.",
"createDate": "2023-02-24T12:04:45.252Z"
},
{
"id": "fa0ef0cfe8554d6398adafb300c70f52",
"correlationId": "",
"subjectType": "StateChange.WorkflowAction",
"success": true,
"identifier": "14f9028614d09a0001bbaedc00004856",
"subject": "AcceptOrder",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"oldValue": "PendingShipment",
"newValue": "Accepted"
}
],
"oldValue": "PendingShipment",
"newValue": "Accepted",
"createDate": "2023-02-24T12:04:45.282Z"
}
],
"extendedProperties": [],
"discountThresholdMessages": [],
"auditInfo": {
"updateDate": "2023-02-24T12:04:45.301Z",
"createDate": "2023-02-24T11:50:30.382Z",
"updateBy": "UNKNOWN",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
}
```
# Configure Subscriptions
Source: https://docs.kibocommerce.com/pages/configure-subscriptions
Subscriptions is supported in your catalog by a set of product attributes. These attributes must be applied to a product type before the subscription configuration options are available for any individual product. Once products are enabled for subscriptions, you can set their subscription pricing.
Learn how to configure subscription attributes and create offline subscription orders
See how to configure subscription-related settings
See how to configure subscription settings at the site level
## Set Up Attributes
In order for any individual product to be enabled for subscriptions and/or trial periods, the relevant attributes must be enabled on its product type first. These are all out-of-the-box [property attributes](/pages/product-attributes-overview) viewable at **System** > **Schema** > **Product Attributes**.
* **Subscription Mode:** Allows a product to be enabled for either subscription-only purchase or both subscription and one-time purchase. If enabled, the Subscription Frequency is required to be set up as well.
* **Subscription Frequency:** Determines the frequency options for the subscription. There are many possible values included by default, from weekly to annual, and any number of these values can be enabled on an individual subscription product.
* **Trial Days:** A number attribute that allows you to configure how many days a particular product is offered for a trial period, between 1 and 365.
* **Trial Product Code:** A text attribute that allows you to specify a product code being offered for trial. This can be any product in the catalog.
* **Trial Product Variation Code:** A text attribute that allows you to specify a variation product code being offered for trial. This can be any product in the catalog, but if a variant product code is selected then a Trial Product Code is also required.
### Subscription Frequency
You can configure the Subscription Frequency attribute to support custom frequencies in addition to those included out-of-the-box. As with configuring any other list [property attribute](/pages/property-attributes "Property Attributes") at **System** > **Schema** > **Product Attributes**, add a value by typing it in label:value format and saving your changes. The frequency for days must be a positive integer between 1-365, while frequencies in weeks must be a positive integer between 1-52. If you enter a value outside of this range, an error will not be displayed on the Product Attributes page but an error will be experienced when adding an item with that frequency to an order or cart.
Once added to the attribute and then enabled on subscription products as shown later in this guide, the custom frequencies will be selectable alongside out-of-the-box frequencies when adding items to the cart, configuring a subscription discount, or updating an existing subscription.
### Configurable Bundle Attributes
Additional attributes are also required for subscriptions to support configurable bundles, which are sets of products that are ordered together as a single item.
While there is a "Bundle" [product usage type](/pages/product-types-overview), configurable bundles for subscriptions are instead made by creating a "Standard" parent product with the bundled items as [extras](/pages/extra-attributes). Text or Boolean extras will remain associated to the parent product in a shipment, but product extras can be split into additional line items. To do this, the following property attributes should be added to the product type. Then one or both can be enabled on the standard product to configure the preferred extra behavior.
* **Split Extras in Shipments:** Splits the price of the bundle between all product extras at the shipment level. These extras carry over to a shipment as individual line items, but are still displayed as one bundled item in the subscription and order details. This can only be enabled if the product's subscription mode is selected and the product has a nonzero price.
* **Split Extras in Subscriptions:** "Flattens" the bundle into separate line items when creating the subscription. Each product extra will be displayed and treated as individual line items on the subscription and order details. This means that discounts, tax, and shipping refreshes will consider them separately. It is recommended for a flattened extra to be a single product instead of a product with multiple variations (such as a shirt with red and blue variations).
You must assign extras to the parent product in order to create configurable bundles. Each product extra must be enabled for subscriptions in its product settings and have an individual price of \$0 (because the total bundle price is set on the parent product and then distributed).
### Custom Data Attributes
Attributes are also used to track custom data in subscriptions. Capturing custom data allows you to generate reporting data or track more insight about subscribers, such as their location, age, gender, birth date, or spending profile. For example, if you sell pet food to consumers then you may want to record their pet's name. If you are a B2B seller, then you may want to indicate the sales representative of the subscriber.
To create custom data attributes that can be used for subscription, set up a new attribute ([Extensible Attribute](https://docs.kibocommerce.com/pages/schema-extensible-attribute) or [Extensible Item Attribute](https://docs.kibocommerce.com/pages/schema-extensible-item-attribute)) and set its **Apply Attribute To** setting that includes Entity "Subscription". If you select Subscription Only, then this custom data will only be visible at the subscription level and will not appear on continuity orders. If you want this data to be included in continuity order attributes, then you should select Order and Subscription.
Once created, you can update these custom data attributes on individual subscriptions in the [Subscription Details UI](/pages/manage-product-subscriptions "Manage Subscriptions") or [Subscription API](/api-overviews/openapi_subscription_overview). However, the custom data is not editable when the subscription is in the Cancelled status, when ordering partial items now, or when updating the next order only.
## Enable Product Types for Subscriptions
Using those product attributes, you have to enable product types for subscriptions before configuring subscription options for the individual products. At **System** > **Schema** > **Product Types**, you can [apply these property attributes](/pages/property-attributes) to any existing or new product type and select their possible values for that particular product type.
For example, the below ProductWithSubscriptionAttribute product type includes all five attributes. This means that any product belonging to the ProductWithSubscriptionAttribute type is able to be configured for subscription-only, subscription and one-time purchase, a trial period, and any of the default frequencies.
The difference between "1 Month" and "30 Days" frequencies is that the 1 Month option preserves the date so that orders are placed on the same day every month (such as July 15, August 15, September 15, and so forth). Meanwhile, a 30 Day frequency counts exactly 30 days between orders.
Similar differences apply between other similar options, such as "4 Weeks" and "1 Month." A week counts as exactly 7 days.
## Configure Products for Subscriptions
Once the product type supports subscriptions, you can enable subscriptions at the product level and select the subscription, frequency, and trial options that are offered for each product. This also applies to bundled products, which are treated as one product and can be subscribed to as one.
1. Go to **Main** > **Sell** > **Products**.
2. Select the product you want to offer subscriptions for.
3. Go to the **Properties** configuration tab.
4. Set the **Subscription Mode** to enable the product as either a subscription-only product (if this is selected, then one-time purchases will not be allowed for this item) or allow both subscription and one-time purchases.
5. If a subscription mode is enabled, then you are required to set available frequencies. Use the **Subscription Frequency** drop-down to select one or more frequencies for the product. The customer will be able to choose between these options when signing up for the subscription.
6. If you want to enable trials for the product, enter the trial period length in **Trial Days** and the alternate **Trial Product Code** to be used for the trial version of the product. You cannot set a product code without configuring Trial Days.
7. If applicable, you can also enter the **Trial Product Variation Code** if you are offering a variation of the base product for trial. If you select a variation code, then you are required to have also selected a Trial Product Code and Trial Days.
8. Click **Save**.
This example shows a product that is enabled for both one-time purchases and subscriptions at a frequency of 1 Month, 3 Months, or 6 Months, and also offers a week-long trial period. If you do not want to offer a trial period on that particular product, you can simply leave those attributes blank.
## Configure Subscription Pricing
Subscription pricing is determined by [price lists](/pages/price-lists "Price Lists"), and you can configure the preferred behavior of determining continuity order totals to account for any changes that may have happened since the initial subscription creation.
### Subscription Price Lists
Price lists for configuring subscription pricing should always be made under an empty parent price list. This allows you to tie subscription discounts to the parent price list, so that all price lists will inherit that discount and you won't have to link the discount to every individual price list.
1. Go to **Main** > **Catalog** > **Price Lists** to create new price lists and/or add products to a list according to [the user guide](/pages/price-lists#create-price-lists "Price Lists API Overview"). In the example below, Facewash is a subscription product.
2. While viewing the price entry for a subscription product, note that there are separate configuration fields for one-time purchase and subscription **Price** and **Sale Price** values. These settings will override the default catalog pricing and allow you to offer the product at a reduced rate if purchased as part of a subscription rather than a one-time purchase.
3. Check the box next to any fields you want to use as an override and enter the appropriate price value.
* If you check a **Price**, then that field cannot be left blank.
* If you select the checkbox for a **Sale Price** and don't enter a value, then the catalog sale price will not be used either. This product will effectively have no sale price.
* If a checkbox is not selected, then the item will use the catalog price or sale price.
You do not have to enter a value in the **Price** field if you want the one-time purchase price to default to the price set in the product catalog. In the above example, the catalog price is \$10.00 and the price list's one-time purchase price is \$9.00. If you left the **Price** blank, then one-time purchases would default to the base catalog price of \$10.00.
For more details about using price lists, see the [Price Lists guide](/pages/price-lists).
### Continuity Order Pricing
Pricing is stored on the subscription at creation, meaning that by default the total will remain the same for continuity orders (unless a recalculation is triggered by editing the subscription, such as adjusting the quantity) and will not be refreshed if the price list changes. To offer more flexible and customer-friendly pricing for continuity orders, your settings can be configured to:
* Update pricing at the moment a continuity order is created by applying the latest item prices.
* Honor the lowest available total price by comparing the updated continuity order total with the original subscription total.
This pricing behavior is configured with two site settings under the Subscriptions tab at **System** > **Settings** > **General**. Both of these settings are applied whenever a continuity order is created, which includes orders generated by actions such as [Order Now](/pages/order-subscription-now#order-all-items "Order Subscription Now"), [setting the Next Order Date](/pages/manage-product-subscriptions#edit-subscription-details "Manage Subscriptions"), and [Update Next Order Only](/pages/update-next-order-only "Update Next Order Only").
* **Apply Latest Item Price on Continuity Order**: When enabled, the system refreshes the item price for each item on the continuity order (which fetches the latest price list information), along with any applicable discounts and taxes. This setting is also applied when creating a continuity order from [Order Partial Items Now](/pages/order-subscription-now#order-partial-items "Order Subscription Now") action.
* **Apply Best Price on Continuity Order**: When enabled, the system compares the continuity order's total with the original subscription total and applies whichever is lowest to the order.
For example, a continuity order is expected to be \$50 per the original subscription price. Between the original subscription's creation and the continuity order's creation date, an item's pricing changes. When creating the continuity order, **Apply Latest Item Price on Continuity Order** refreshes the pricing for each item. This results in a calculated continuity order total that could be \$75 (if prices went up) or \$40 (if prices went down). **Apply Best Price on Continuity Order** then compares the original subscription total (\$50) with this newly calculated continuity order total and the lower of the two is applied to the order. If the calculated total was \$75, then the original \$50 would be applied. If the calculated total was \$40, then \$40 would be applied.
## Other Site Settings
Other optional configurations for subscriptions are also available in your site settings, as seen above.
* **Order Now Resets Next Order Date:** When enabled, the next order date will be reset based on the current date and frequency whenever the Order Now action is performed on a subscription. If disabled, the next order date that already exists will remain unchanged. This is enabled by default.
* **Create Continuity Order \_ Days Before Next Order Date**: Continuity orders will be created this many days before the next order date. If left blank, continuity orders will be created on the next order date.
* **Update Next Order Date Up to \_ Days From Existing Next Order Date**: The next order cannot be set any further out than this limit when the date is manually updated. For example, if the date is August 24 and the next order date is September 2, and this configuration is set to 7 days, the next order cannot be changed to any date later than September 9. You will not be able to extend the next order date again until the next continuity order is placed, though it can be moved closer.
* **Pause Subscription for \_ Continuity Orders**: A paused subscription will be automatically reactivated after this many continuity orders have passed and cannot be paused again until the next continuity order is placed. It can still be [manually reactivated](/pages/manage-product-subscriptions#view-subscriptions-in-customer-details) at any point before this limit is reached. If left blank, the subscription will remain paused indefinitely until manually reactivated.
* **Skip Subscription \_ Times**: The ability to skip a continuity order will be disabled once this amount of skips has been made in a row. When this happens, a continuity order must be placed before the subscription can be skipped again.
* **Allow Order All or Partial Items Now Once Every \_ Days**: After [ordering either all or partial items now](/pages/order-subscription-now "Order Subscription Now"), both of these actions will be restricted for this amount of days. For example, if a full order is created on September 20 and this setting is configured as 10 days, then both the entire order and partial order actions will not be available until September 30.
* **Send Subscription Reminder \_ Days Before Next Order**: The [subscription order reminder email](/pages/subscription-notifications) will be sent to customers this many days before their next order. This email template must also be enabled in the Email section of the site settings.
* **Send Email \_ Days Before Paused Subscription is Re-Activated**: The [subscription pause limit reached email](/pages/subscription-notifications) will be sent to customers this many days before their paused subscription is automatically re-activated.
* **Send Email Reminder Every \_ Days for Paused Subscriptions**: The [recurring subscription paused reminder email](/pages/subscription-notifications) will be sent to customers at this interval until the subscription is reactivated.
# Configure Substitutions
Source: https://docs.kibocommerce.com/pages/configure-substitutions
You must first contact [Kibo Support](https://kibotechsupport.zendesk.com/) to have this feature enabled in your tenant settings. Then you will be able to proceed with this guide to enable repricing and email notifications, add the substitute attribute to product types, and select the substitutes on products. If you also want to offer shoppers the ability to opt in or out of substitutions, refer to the [Shopper Preferences](/pages/shopper-preferences "Shopper Preferences") guide.
Learn how to create and manage product substitution rules
## Enable Repricing
Repricing on substitutions is optional. When a reprice occurs, the substitute's item price will be applied but discounts will not be re-evaluated. Any discounts on the original item will be copied to the substitute item as-is. Shipping and handling will be copied from the original item to the substitute item, tax will be refreshed, and the shipment total will be recalculated.
Payment may or may not be affected, depending on the difference between the substitute item and original item's pricing:
* If the substitute item's price is lower than the original item, then the difference will be credited to the customer. If [Auto Capture](/pages/payment-ranking-and-auto-capture#auto-capture "Payment Ranking and Auto Capture") is enabled, then the system will do this automatically as long as a payment has already been captured. If Auto Capture is not enabled, you will have to credit the amount manually.
* If the substitute item's price is higher than the original item, the payment status will be set to Errored and all shipments on the order will be blocked from fulfillment until an additional payment for the difference is authorized. An email notification can be sent to the shopper informing them of this and directing them to Customer Care for more details.
* If the substitute item's price is the same as the original item, there will be no impact to payment.
* If a bundled item is substituted, pricing was distributed across all items in the bundle before the substitution is made. When repricing is enabled, the substitute item's catalog price will replace the original item's distributed price without affecting other items in the original bundle. If repricing was not enabled, then the original item's distributed price would still be applied to the substitute item.
* If a single item is substituted by a bundle, the bundle's catalog price will simply replace the original item's price. This may require additional payment collection if the bundle costs more than the original product. If repricing was not enabled, then the original item's price would be distributed across all substituted bundle components in a weighted ratio based on the price (which would not require additional payment collection).
Repricing is disabled by default. To enable repricing on all substitutions:
1. Go to **System** > **Settings** > **General** > **Site.**
2. Locate the **Fulfillment Settings** section.
3. Toggle **Reprice on Substitution**.
4. Click **Save**.
## Enable Email Notifications
In order to send optional email notifications to shoppers, enable them under [your email settings](/pages/general-settings#email "General Settings"):
1. Go to **System** > **Settings** > **General** > **Email**.
2. Scroll down to Shipment Emails and toggle on **Substitution - payment required** to send an email notification when the substitute item's price is higher than the original item after repricing. This prompts the customer to provide additional payment before the order can be fulfilled.
3. Scroll down to Order Emails and toggle on **Item Substituted** to send an email notification when an automatic substitution takes place.
4. Click **Save**.
## Add Attribute to Product Types
Enable substitutions in your catalog using the substitute property in the [product type configurations](/pages/product-types-overview).
1. Go to **System** > **Schema** > **Product Types**.
2. Select a product type. All usage types are supported.
3. In the **Properties** tab of the product type settings, select the **Substitute Products** attribute.
* If the product is a Configurable Product, then substitutes must be set up at the variant level as each of its product variants has its own product code. In this case, select the **Substitute Variants** attribute instead.
4. Click **Done** to add it to the product type.
5. If you want the system to perform automatic substitutions on this product type, also add the **Allow Auto Substitutions** attribute. If this attribute is not added, then substitutions can only be performed manually by fulfillers.
6. If you want to set up any products (or product bundles) of this type that are only used for substitutions and should not be displayed on the storefront for purchase, also add the **Hide Product** attribute and select Substitute Only as the only value option.
7. Click **Save**.
8. If you are using the Hide Product attribute, go to the [property configurations](/pages/property-attributes#assign-property-values-to-products "Property Attributes") of the product(s) you want to hide and set the attribute to "Substitute Only." This product will then only be available when performing a substitution. If no value is set, it will continue to be displayed on the storefront.
## Select Substitutes on Products
After adding the attribute to product types, select any product of that type in your master catalog and set up its substitute(s). Substitutions may be made for any standard products, variant products, product extras, bundles, bundle components, items in collections, and digital items, with the exception of service items.
1. Go to **Main** > **Catalog** > **Products**.
2. Click the product that you want to configure substitutes for.
3. In the **Properties** tab of the product settings, enter eligible substitutes in the **Substitute Products** field. If the product usage is Configurable Product with Options, use the **Substitute Variants** field to select eligible variants as substitutes instead.
* These may be individual products or product bundles.
* The order in which you add these substitutes will be the order of priority used by automatic substitutions, from highest to lowest.
4. **Substitute with Multiple Items Using a Product Bundle**
* Each entry in the **Substitute Products** field can only hold one product. To have a single substitute entry apply more than one quantity of an item, or a combination of different items, create a [Product Bundle](/pages/product-bundles-and-product-extras) first, then add that bundle as the substitute:
* Go to **Main** > **Catalog** > **Products** and create a new product bundle (for example, a **Cleanser Bundle** or a **Half-Gallon Milk 2-Pack**).
* Add each item you want to include as a bundle component and set the required quantity for each. For example, add 1 quantity each of 60 Day Cleanser and 30 Day Cleanser, or add 2 quantities of ½ Gallon Milk.
* Click **Save** on the bundle product.
* If the bundle should only be used for substitutions and not sold directly on the storefront, go to the [property configurations](/pages/property-attributes) for the bundle and set the **Hide Product** attribute to **Substitute Only**.
* Return to the original product (for example, 90 Day Cleanser or 1 Gallon Milk), open its **Properties** tab, and add the bundle as one of the entries in the **Substitute Products** field, alongside or instead of individual product substitutes.
* Click **Save**.
* Once configured, the bundle appears as a single selectable option in the Substitute Item pop-up. Selecting it applies all of its bundle components together as the replacement.
5. If you want to perform automatic substitutions, toggle on **Allow Automatic Substitutions**.
6. Click **Save** when you have finished adding all desired substitutes to your product.
There is a limit of 10 substitutes per product. If you don't want to use substitutes for a particular product, then you do not have to select any in its product configurations (even if it belongs to a product type enabled for substitutions).
# Configured Product (After)
Source: https://docs.kibocommerce.com/pages/configured-product-after
**Related API:** This extension modifies the [Configure Variation Product](/api-reference/storefrontproducts/configure-variation-product) operation.
This action manipulates the HTTP request or response after the ConfiguredProduct operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.catalog.storefront.products.configuredProduct.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/catalog/storefront/products/ConfiguredProduct](/api-reference/storefrontproducts/get-product) operation.
**HTTP Request**
GET `api/commerce/catalog/storefront/products/{productCode}/configure?includeOptionDetails={includeOptionDetails}&skipInventoryCheck={skipInventoryCheck}&quantity={quantity}&responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Configured Product (Before)
Source: https://docs.kibocommerce.com/pages/configured-product-before
**Related API:** This extension modifies the [Configure Variation Product](/api-reference/storefrontproducts/configure-variation-product) operation.
This action manipulates the HTTP request or response before the ConfiguredProduct operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.catalog.storefront.products.configuredProduct.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/catalog/storefront/products/ConfiguredProduct](/api-reference/storefrontproducts/get-product) operation.
**HTTP Request**
GET `api/commerce/catalog/storefront/products/{productCode}/configure?includeOptionDetails={includeOptionDetails}&skipInventoryCheck={skipInventoryCheck}&quantity={quantity}&responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Fulfiller and Returns Customization
Source: https://docs.kibocommerce.com/pages/content-fulfiller-and-returns-customization
It is often best for fulfiller users to have a synergized experience across their tenant's entire suite of platforms and applications, which is created by visuals such as branded logos and matching color schemes. This can be achieved in the Fulfiller Interface of the Kibo Composable Commerce Platform (KCCP) by configuring a theme that includes custom assets to re-skin the appearance of the interface, including the modals and other elements for processing returns.
This guide provides a step-by-step walkthrough to customize the fulfiller application for a more personalized user experience.
## Customizable Elements
The below elements of the interface can be customized to enhance the fulfiller user experience. However, it is good idea to discuss customization changes and field displays with the Kibo project team first in case supporting code changes are required for your implementation.
* **Logo:** The logo that gets displayed on fulfiller hamburger menu. This allows maintaining the same branding experience across the platform.
* **Color Scheme:** The background colors of grid headers, popups, section headers, and other elements. However, font size and font family cannot be changed.
* **Localization:** Labels are displayed based on language-specific resource files. To change the text of buttons, grid headers, section headers, or other elements, edit the resource keys in the localization files.
* **Field Display:** Language files can also be leveraged to hide or show certain fields. A common use for this is the flag that determines whether to display the External Order Number field in order data. This field is hidden by default in the tenant settings via `displayExternalOrderId`, which is set to 0 by default. Changing this option to "1" would toggle the order number on.
* Another example is the Return Status column that is usually displayed in shipment details. If your implementation does not process returns in the Fulfiller UI, you can toggle this column off with the `displayReturnsSection` setting. In most cases such as these, a value of 1 will display the field while a value of 0 will hide it.
* **Search Results Sort:** You can configure the Fulfiller UI's default sorting order of search results so that users will view either the most relevant, most recent, or other preferred shipments first. In the tenant settings of a language file, set `searchShipmentSortBy` to orderFirst, orderLast, newest, oldest, highestCost, or lowestCost.
## Development Environment
You will need a command line interface, [Node.js](https://nodejs.org/en), [Grunt.js](https://gruntjs.com/), and [Git](https://git-scm.com/). This software is required in order to build and manage the theme files that are used for customization.
Additionally, [Visual Studio Code](https://code.visualstudio.com/) should be installed. This is a lightweight but powerful source code editor which runs on the desktop and is available for Windows, macOS and Linux. It comes with built-in support for JavaScript, Typescript, and Node.js, and has a rich ecosystem of extensions for other languages (such as C++, C#, Java, Python, PHP, Go) and runtimes (such as .NET and Unity).
Note that access to a provisioned sandbox is required through a Dev Center account.
## Creating a Theme
To begin creating a theme:
1. In the Dev Center Console, click **Develop** > **Themes**.
2. Click **Create Theme**.
3. In the dialog box that appears, specify the Name and ID.
4. Click **Save**. You should now see your theme in the Themes grid.
5. Double-click your new theme to edit it.
6. Note the Application Key. You will need this value later in the tutorial.
## Configuring Assets
In the new theme, follow the below steps to create the configuration file:
1. Create a file called "mozu.config.json" in the root of the theme folder. Configure it as shown in the below code block.
* To find your developer account ID, click Launchpad under your user name in Dev Center, and then hover over the link to the account you want to access. You should see your developer account ID appended to the URL, typically as a four-digit number.
2. Replace the `workingApplicationKey` value with the Application Key value that you noted when creating the theme.
```text theme={null}
{
"baseUrl": "https://t00000.sandbox.mozu.com",
"developerAccountId": yourDevAccountId,
"developerAccount": {
"emailAddress": "yourDevEmailAddress"
},
"workingApplicationKey": "yourPackageApplicationKey"
}
```
## Customizing Assets
Now you are ready to begin customizing. The structure and assets of the new theme can be based on existing repositories that Kibo provides as templates, so you can clone those and make changes that will be uploaded to your new theme in Dev Center.
1. If you are customizing the general UI, clone the [fulfiller theme repository](https://github.com/KiboSoftware/kibo.theme.fulfiller) to a local folder. If you are customizing the returns part of the UI, clone the [returns theme repository](https://github.com/KiboSoftware/kibo.theme.returns) instead.
2. Open the cloned local folder in Visual Studio Code.
3. Open the Terminal window of Visual Studio Code. Usually this window should be open by default and displayed in the bottom half of Visual Studio Code. If not displayed, click **Terminal** > **New Terminal** in the menu to launch a new window.
Both the fulfiller and returns themes share a similar hierarchy, in which theme assets such as logos and CSS variables are accessible under the root **fulfiller** or **returns** folder depending on which repository you are using. The **languages** subfolder contains the language files that support custom language localization and field display.
You can make the following changes to customize the theme:
1. Ensure that the [config.json file](#configuring-assets) from the repository exists in your new theme.
2. Replace the logo.png file with the appropriate image, though the file name and the extension must remain the same.
3. Open the variables.css file and make changes to the CSS styling for the user interface and its color scheme. For example, replacing `--dashboard-active-tab-background-color: #c73916;` with `--dashboard-active-tab-background-color: #56ba77;` would change the dashboard active tab's background from red to green.
4. The language localization files bind static text in the UI to string variables. To change any of the text, make edits to the values of these variables in the appropriate language file (such as fr.json for French). For example, changing the `"lateShipments": "Late Shipments"` field in the section for dashboard grid tabs with `"lateShipments": "Delayed Shipments"` would cause the UI to display "Delayed Shipments" where that label appears on the dashboard.
The structure of the variables.css file must remain the same, so make sure to keep `:root {` as the first line in the file. If you remove this line, then the customized variables will not be loaded.
Edited assets must be pasted into the theme at **resources** > **admin** > **fulfiller** or **resources** > **admin** > **returns**. Then, it is ready to be applied to a sandbox.
## Custom Language Localization
Recall that the **fulfiller** > **languages** and **returns** > **languages** subfolders contain language files that allow localization of the Fulfiller UI. If the language you want to use is not included by default, you can upload additional files for other languages that you want to support.
You must upload a language file to both the fulfiller and returns subfolders to fully translate both elements of the Fulfiller UI. These files should use the same template as the existing en.json and fr.json files, but with the string values translated into your chosen language. The name of the files must be the locale code, such as de.json (German), otherwise it will not be usable and the UI will default to English.
Once these language files exist for the user’s browser language, then the Fulfiller UI and return menus will automatically be displayed in that language.
## Shipping Label Orientation
You can override the default shipping label orientation for specific carriers by defining the orientation, CSS style, width, and/or height in the theme. Supported orientation values are Landscape, Portrait, RotateRightPortrait, RotateLeftPortrait, Default, and Custom.
Locate the `shippingLabelOrientationsForCarrier` tenant setting and configure the settings for each carrier in the array, such as in the below example. The "Custom" carrier refers to those integrated with [shipping extensibility.](/pages/shipping-extensibility "Shipping Extensibility")
```text theme={null}
"shippingLabelOrientationsForCarrier": [
{
"carrier": "UPS",
"orientation": "Default"
},
{
"carrier": "FedEx",
"orientation": "Default"
},
{
"carrier": "Purolator",
"orientation": "Default",
"style": "page-break-after: always;text-align: center;",
"width": "80%",
"height": "50%"
},
{
"carrier": "Custom",
"orientation": "Default"
}
]
```
## Publishing Changes
The new theme must be built, published, applied to the tenant, and tested to ensure it displays properly. Make sure that your final theme in Dev Center includes both your customized clone and the configuration file that you created before.
1. In the terminal window, type `grunt build –force` and check for a successful build message.
2. Once the build is successful, publish the customized theme to the Dev Center by typing the command `grunt mozusync:upload` and then authorizing with your password. This will upload all the customizations to the Dev Center.
3. To apply it to a tenant, it must be installed on a sandbox. You only need to do this once. After installation, your theme remains installed on the sandbox until you remove it.
* In the theme toolbar at the top right, click **Install**.
* In the Select a Tenant dialog box, select the sandbox you previously created.
* Click **OK**.
4. Then you can apply it to a site from the Admin UI.
* In the Admin UI, Go to **Main** > **Storefront** > **Themes**.
* Select the appropriate site in the header.
* Click the three dots to the right of the theme to expand the action menu and click **Apply**.
5. You can view either the live or staged versions of this theme with the **View** button in the top right.
Kibo recommends applying any theme customizations to all of your sites. This is because the Fulfiller UI cannot distinguish between sites except when viewing shipment details, so the default site's theme is always used on the dashboard or any other page where there isn't a specific shipment to reference.
# Content Overview
Source: https://docs.kibocommerce.com/pages/content-overview
The Content section of the Admin UI allows you to apply themes to customize your Fulfiller UI and email/packing slip templates, view existing templates, and manage files such as product images.
Email and packing slip templates can be viewed at **Storefront** > **Editor**, but editing them must be done in a theme file which you can then upload at **Storefront** > **Themes**. For more information about these features and the customization process, refer to the [email](/pages/general-settings#email "General Settings") and [packing slip](/pages/packing-slips "Packing Slips") documentation.
The guides in this category provide details about how to apply themes, manage files, and customize the Fulfiller UI.
If you are using the Kibo Composable Commerce Platform with a site, you may have access to additional functionality in the Editor as well as a page for configuring redirects. Contact [Kibo Support](https://help.kibocommerce.com/) for more documentation about these features.
# Contentful Integration
Source: https://docs.kibocommerce.com/pages/contentful-integration
Kibo provides an application to integrate between Contentful, a leading Content Management System (CMS), and the Kibo Catalog service. This application connects your catalog to reference your products inside of Contentful and streamline your content management to ensure a consistent shopping experience across all of your sites, marketplaces, and points of sale.
For more information on Contentful, see their [website](https://www.contentful.com/) and [developer portal](https://www.contentful.com/developers/).
## Requirements
You must have a Contentful account, as the application is installed and managed within Contentful rather than Kibo's Dev Center.
To authorize the application, you will also need to know your Kibo Client ID and secret.
## Install the App
Navigate to **Apps** > **Manage Apps** in the Contentful interface. This page will include a list of all available applications in which you can find Kibo Commerce. Click this application to view more information and install it. Clicking **Install** will open a configuration screen.
## Configure the App
To configure the application in Contentful:
1. Contentful will prompt you to provide your Auth Host, Kibo Client ID, Shared Secret, and API Host. These values should be the same as you would use for any other Kibo application; the Client ID and Shared Secret can be [found in your Developer Console](/pages/getting-started#view-application-credentials "Getting Started").
2. You must assign your products to Contentful fields in order to enable products. Check the **Kibo Standard Product** and **Product** options in this section. Note that all products will be displayed as the "Kibo" product type in Contentful.
3. Click **Install** in the top right to confirm your settings and complete the installation process. You can return to **Apps** > **Manage Apps** again at any time to view your Kibo application and edit these configurations.
## The Content Page
The **Content Model** page allows you to manage your content types. As mentioned above, "Kibo Products" will be the only type supported for products imported via the application.
If you click the Kibo Product, then the UI will open the below page where you can access additional settings. However, Kibo recommends that you do not make any changes here as they will not work as expected with Kibo products.
## Add Kibo Products
On the **Content** page, you can add selected products from your Kibo catalog to Contentful.
1. If you have other content types in your account, then you must select "Kibo Product" from the dropdown list in the search bar. If you do not have any other content, then Kibo Product will be automatically populated.
2. Click **Add Kibo Product** in the top right.
3. From this page, click **Select products** in the left pane.
4. This will open a navigation module allowing you to view your catalog. Select one or more products that you want to add and click **Save # products** in the top right.
5. Your selections will now display on the page and this update will be saved in draft status. To remove any selections, click the **X** in the corner of the product listing. You can also drag and drop them to change their order.
6. When satisfied, click **Publish** on the right to publish your content entry. Alternatively, you can archive it instead or schedule it for publishing at a later date.
## Next Steps
For more information about managing products and content entries, see [Contentful's guides and tutorials](https://www.contentful.com/guides/).
# Contentstack Integration
Source: https://docs.kibocommerce.com/pages/contentstack-integration
The Kibo Commerce extension with Contentstack lets you search and fetch products from your Kibo catalog and display them on your entry page via a custom field. This step-by-step guide explains how to create the custom field extension for your [content types](https://www.contentstack.com/docs/developers/create-content-types/about-content-types/). For more information on Contentstack, see their [website](https://app.contentstack.com/) and [developer portal](https://www.contentstack.com/docs/developers/).
## Prerequisites
You must have the following accounts:
* Kibo Commerce Account
* Contentstack Account
## Install the App
For installation instructions, email the Contentstack support team and request access to the Kibo Commerce Contentstack integration source code.
## Configure the Integration
The following sections of this guide will walk through the different steps that must be performed to create a Kibo Commerce custom field extension:
1. Retrieve your Kibo Commerce App API credentials.
2. Add the Kibo Commerce custom field extension to your account.
3. Use the custom field.
4. Add products in the custom field.
### Retrieve API Credentials
To obtain your Kibo API credentials:
1. Log in to your Kibo Commerce [Dev Center](http://developer.mozu.com/login).
2. Click **Develop** > **Applications**.
3. Select an existing application or create an application for your sandbox or production environment.
4. Click **Create Application** on the top right corner.
5. Enter a **Name** and **Application ID**.
6. Click **Save**.
7. Copy the **Application ID** and **Shared Secret** to use later in your application.
### Add the Custom Field Extension
The root folder of the source code that you get from the support team contains a redirect HTML file.
1. Upload this file as an asset in Contentstack by following steps mentioned in the [Create/Upload](https://www.contentstack.com/docs/content-managers/working-with-assets/create-upload-assets/) asset article.
2. After uploading the file, you'll get a URL in the [asset details](https://www.contentstack.com/docs/content-managers/working-with-assets/create-upload-assets/#asset-details) section, make note of this URL.
To add the extension to your stack:
1. Log in to your Contentstack account.
2. Click the **Settings** icon on the left navigation panel.
3. Select **Extensions**.
4. Click **+ New Extension** in the top right, then **Create New**.
5. In the **Select Extension Type** window, select **Custom Field**.
6. On the Create New Extension page, enter the following values.
* **Title** (Required): Enter a title such as “Kibo Commerce” for your custom field.
* **Field Data Type** (Required): Select "JSON" as the data type in which the field input will be saved in Contentstack.
* **Multiple** (Optional): Leave this field unchecked.
* **Hosting Method** (Required): Select "Hosted by Contentstack" for this content type.
* **Extension Source Code:** Specify the extension code here. Copy the source code from the index.html file located in the root folder that you get from our Support team and paste it into the Extension source code field.
7. Set up the **Configuration Parameter** such as in the below example:
```
{
"apiHost": "https://t1234.sandbox.mozu.com",
"authHost": "https://t1234.sandbox.mozu.com",
"applicationId": "kibo.example-app-name.1.0.0.Release",
"sharedSecret": "12345_Secret",
"type": "product_multiple",
"pageCount": "10",
"redirectUrl": "https://assets.contentstack.io/v3/assets/123/123/123/redirect.html"
}
```
These parameters are:
* **apiHost**\*\*:\*\* Host of your Kibo API environment.
* **authHost:** Host for Kibo API authentication, either a production ([https://t00000.tp0.mozu.com](https://t00000.tp0.mozu.com)) or sandbox ([https://t00000.sandbox.mozu.com](https://t00000.sandbox.mozu.com)) environment. Replace the numeric placeholders with your Tenant ID and production pod.
* **applicationId:** The Application ID [found in your Developer Console](/pages/getting-started#view-application-credentials "Getting Started").
* **sharedSecret:** The Application Secret [found in your Developer Console](/pages/getting-started#view-application-credentials "Getting Started").
* **type:** The Kibo Data Object being fetched (which should be a product).
* **pageCount:** The number of items that the API will return for each page of your query (default is 10).
* **redirectUrl:** The URL to redirect.
8. Click **Save**.
### Use the Custom Field
Once you have added a custom field, you can use it in your content type.
1. Click the **Content Models** icon on the left navigation panel.
2. Click **+ New Content Type** in the top right.
3. Enter a **Name**, **UID**, and then click **Save and proceed**.
4. Click **Insert a field** link (the **+** sign) and add the **Custom** field to it.![Insert a field link displays with plus sign]()
5. Click **Select Extension/App** from the drop-down menu in Basic properties.
6. Check the KiboCommerce extension field that you created and click **Proceed**.
7. Click **Save and Close.
**
8. Create an entry for this content type and you will see the **Kibo Commerce** custom field.
### Add Products in the Custom Field
To add products to the custom field:
1. Click the **Entities** icon on the left navigation panel.
2. Click **All Entries** and then **+ New Entry** in the top right.
3. Select the custom field and click **Proceed**.
4. Select the corresponding **Add Products** to either add single or multiple products.
5. Click **Add Products** to go to the KiboCommerce Extension window.
6. Use the search bar at the top to search for the product of your choice.
7. Select one or more products and click **Add Product(s)**.
8. Click **Save**.
# Continuity Orders for Products Dashboard
Source: https://docs.kibocommerce.com/pages/continuity-orders-for-products-dashboard
The Continuity Orders for Products dashboard keeps you up to date on how individual products will perform in the future based on [subscription continuity orders](/concept-guides/subscriptions "Product Subscriptions Overview"). This can be viewed under the Subscriptions topic at **Kibo Standard Reports** > **Subscriptions** > **Continuity Orders for Products Dashboard** in the navigation menu.
Understand subscription commerce and recurring orders
See the Subscription API documentation for programmatic access
The supported filters that can be applied to this dashboard are:
| Name | Description | Default |
| --------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ |
| Site Name | Restrict results to one or more of your sites. | All |
| Next Order Date | Limit results to only the calculated next continuity order date (the current order date + subscription frequency). | Next 30 Days |
| Product Code | The unique identifier for the product. | None |
The measures that are calculated by this dashboard are:
| Name | Description |
| ------------------ | ------------------------------------------- |
| Subscription Count | Count of subscriptions for the time window. |
The tiles that make up this dashboard are:
| Name | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Subscription Product Details | The details of each subscription: Subscription Number, Product Code, Product Name, Next Order Date, Email, User ID / Customer Account ID, and Quantity. |
# Coupon Sets
Source: https://docs.kibocommerce.com/pages/coupon-sets
Coupon sets are collections of coupons that you can associate with one or more discounts. For example, you may want to create 1,000 coupons to use for a free shipping promotion on your site. To accomplish this, you create a generated coupon set and specify to create 1,000 coupons and then associate the coupon set with a free shipping discount.
Learn how to create and manage coupon sets for discounts
You can create a coupon set before creating a discount. You can first create a coupon set, and then create a discount and associate the coupon set you created with the discount. Refer to the [Configure Discounts documentation](/pages/configure-discounts) for more information about associating coupon sets with discounts in the Discounts module.
You can use the import/export tools to quickly import and export your coupon sets. Refer to the [Marketing Template](/pages/marketing-best-practices) for more information.
## Coupon Set Types
There are two types of coupon sets:
* **Manual Coupon Sets:** Allow you to specify the entire coupon code for every coupon in the coupon set.
* **Generated Coupon Sets:** Allow you to specify only a coupon code prefix that every coupon code in the coupon set starts with.
For example, you want to create 1,000 coupons for a free shipping promotion on your site and you don't want to manually enter the entire coupon code for all 1,000 coupons. To accomplish this, you create a generated coupon set and you specify to create 1,000 coupons that all start with a custom prefix.
## Create a Manual Coupon Set
To create a manual coupon set:
1. Go to **Main** > **Sell** > **Coupon Sets**.
2. Click **Create New Coupon Set** > **Manual Coupon Set**.
3. Specify a **Name** for the coupon set.
4. (**Optional**) Specify a **Start Date** and an **End Date** for the coupon set.
The **Start Date** and **End Date** fields specify when the coupons in the coupon set are active and in effect. You can specify either a Start Date, an End Date, or both.
5. Specify the **Max Redemptions (Per Code)** and **Max Redemptions Per Customer (Per Code)**.
You can also set maximum redemption amounts [at the discount level](/pages/configure-discounts#discount-limitations). If you have only selected a maximum here at the coupon set level, then the discount code will work regardless of whether the shopper is logged into their customer account or not. If you have set a maximum at the discount level, then the code will only work if the shopper is logged in.
6. Click **Save & Continue**. The modal will expand to include the **Codes** and **Discounts** sections.
7. In the **Codes** section, enter your desired coupon code(s) and click **Add**.
If you already have coupon codes created, you can use the search box and the filter to find and add your coupon codes to the coupon set.
8. (**If applicable**) If you want to associate the coupon set with discount(s) that you've already created:
* In the **Discounts** section, either search for the discount(s) for which you want the coupon set to be associated with or use the drop-down menu to select the discount(s).
* Click **Enter**.
9. Click **Save.**
## Create a Generated Coupon Set
To create a generated coupon set:
1. Go to **Main** > **Sell** > **Coupon Sets**.
2. Click **Create New Coupon Set** > **Generated Coupon Set**.
3. Specify a **Name** for the coupon set.
4. (**Optional**) Specify a **Start Date** and an **End Date** for the coupon set.
The **Start Date** and **End Date** fields specify when the coupons in the coupon set are active and in effect. You can specify either a Start Date, an End Date, or both.
5. Specify the **Max Redemptions per Code** and **Max Redemptions per Customer**.
6. In the **Code Configuration** section, enter the **Number of Codes** you wish to generate.
7. Enter a **Code Prefix**. The **Code Prefix** specifies the prefix of all the coupon codes in the coupon set. Click **Suggest** to have Kibo eCommerce suggest a code prefix for you. You can preview what the coupon codes will look like in the **Preview** window.
8. Click **Save & Continue**. The modal window expands to now include the **Discounts** section.
9. (**If applicable**) If you want to associate the coupon set with discount(s) that you've already created, in the **Discounts** section click **Add** and select the discount(s) for which you want the coupon set to be associated with.
## Remove a Coupon Set
You can delete manual and generated coupons set through either the UI or Catalog API. To remove a coupon set via API, simply make a DELETE call to the [Delete Coupon Set API](/api-reference/couponsets/delete-coupon-set) endpoint with the appropriate coupon set code in the path.
To remove a coupon set via the interface:
1. Go to **Main** > **Sell** > **Coupon Sets**.
2. Expand the dropdown menu on the right of a coupon set in the table and click **Delete**.
3. If the coupon set is currently in its active date range, a pop-up will ask you to confirm. Click **Yes**.
* You do not have to deactivate the coupon before deleting, but Kibo recommends making sure a coupon is no longer in use first. You can access coupon settings by clicking **Edit** instead of **Delete** in the previous step.
# Create a New Tax Integration
Source: https://docs.kibocommerce.com/pages/create-a-new-tax-integration
You can calculate tax using Avalara and add your own tax engines using either API Extensions or tax calculator capability. If a user needs a service other than Avalara then the following approaches help to integrate your own tax calculator.
## Approach 1: Using estimateTaxes API Extension
This approach is used after creating a new API extension application.
The following steps set a tax response using the estimateTaxes API Extension:
1. Create a new **API Extension Application**. Refer to the [API Extension](/pages/api-extension-examples) document.
2. Use the [API Extension function.](/pages/estimate-taxes-before)
3. The [Estimate Taxes (Before)](/pages/estimate-taxes-before) file is shown in the following code block:
```
module.exports = function(context, callback) {
var responseBody = {
"itemTaxContexts" : [],
"shippingTax" : 0.00,
"handlingFeeTax" : 0.00,
"orderTax" : 0.00,
"taxData": { "taxPercent": 0.00 }
};
needle.get('https://example.com/taxService', (res) => {
var taxResponse = JSON.parse(data);
responseBody.orderTax = taxResponse.data.taxAmount
responseBody.taxData = { "taxPercent": taxResponse.data.taxPercentage };
var lineItem = taxOrderInfo.lineItems[0]; // assume there is at least 1 item in the order
responseBody.itemTaxContexts.push({
"id" : lineItem.id,
"productCode" : lineItem.productCode,
"quantity" : lineItem.quantity,
"tax" : taxResponse.data.taxAmount,
"shippingTax" : 0.0,
"feeTotal": taxOrderInfo.handlingFee
});
context.response.body = responseBody;
context.response.end();
callback();
});
};
```
The sum of the item.itemTaxContexts elements must equal to orderTax in all the examples given below. This is a requirement for any tax integration in KCCP to be able to correctly calculate the prorated taxes when items are split across shipments.
## Approach 2: Using Tax Calculator Capability
This approach helps you to add tax calculator capability through the Kibo commerce application.
The following steps add a tax calculator capability:
1. In Dev Center, navigate to **Develop** > **Applications > Packages > Capabilities.**
2. Click **Add Capability**.
3. Search for Tax Calculator in the **Add Capability** modal and click **Ok.**\\
4. Enter the external URL that receives the tax request and responds with the tax response. It will post to the URL directly and does not add any path.
5. Select the country you want to enable it for. Press the “Enabled” toggle to enable the calculator. It might take a minute to start working.\\
## Rest API Responses
This is what your endpoint will receive:
```
{
"OrderDate": "0001-01-01T00:00:00Z",
"TaxContext": {
"TaxContextId": "13",
"CustomerId": "",
"TaxExemptId": null,
"TaxShipping": true,
"OriginAddress": {
"Address1": "1835 Kramer Lane",
"Address2": "#100",
"Address3": null,
"Address4": null,
"CityOrTown": "Austin",
"StateOrProvince": "TX",
"PostalOrZipCode": "78758",
"CountryCode": "US",
"AddressType": null,
"IsValidated": false
},
"DestinationAddress": {
"Address1": "1234 Fake St",
"Address2": "",
"Address3": null,
"Address4": null,
"CityOrTown": "Houston",
"StateOrProvince": "TX",
"PostalOrZipCode": "12345",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": null
}
},
"LineItems": [
{
"Id": "dbc98455f06d47359d47ae230119e28f",
"ProductCode": "blz-1001",
"VariantProductCode": null,
"ProductName": "Wool Blazer",
"ProductProperties": [
{
"AttributeFQN": "tenant~availability",
"Values": [
{
"Value": "24-48hrs",
"StringValue": "Usually Ships in 24 to 48 Hours"
}
],
"AttributeDetail": {
"InputType": null,
"ValueType": null,
"DataType": null,
"Name": "Availability",
"Description": null
},
"IsHidden": null,
"IsMultiValue": false
}
],
"Quantity": 1,
"LineItemPrice": 199.0,
"DiscountTotal": 0.0,
"DiscountedTotal": 199.0,
"ShippingAmount": 0.0,
"HandlingAmount": null,
"FeeTotal": 0.0,
"IsTaxable": true,
"Reason": null,
"Data": null,
"ProductDiscount": null,
"ShippingDiscount": null,
"ProductDiscounts": [],
"ShippingDiscounts": [],
"OriginAddress": null,
"DestinationAddress": null
}
],
"ShippingAmount": 0.0,
"CurrencyCode": "USD",
"HandlingFee": 0.0,
"OriginalDocumentCode": "13",
"OrderId": "12e9f48b2405bf00012c953200007729",
"OrderNumber": 13,
"OriginalOrderDate": "2022-01-20T17:06:35.0750575Z",
"TaxRequestType": "Order",
"Attributes": [],
"ShippingDiscounts": null,
"ShippingDiscount": null,
"OrderDiscounts": null,
"OrderDiscount": null,
"HandlingDiscounts": null,
"HandlingDiscount": null,
"ShippingMethodCode": null,
"ShippingMethodName": null
}
```
### Example: OrderTaxContext Response
This is what your endpoint should respond with:
```
{
"ItemTaxContexts": [
{
"Id": "dbc98455f06d47359d47ae230119e28f",
"ProductCode": "blz-1001",
"Quantity": 1,
"Tax": 1.0,
"ShippingTax": 1.0,
"TaxData": {
}
}
],
"ShippingTax": 1.0,
"HandlingFeeTax": 3.0,
"OrderTax": 1.0
}
```
### Example: Application
This just sends back dummy data for the specific order above, but it does work.
```
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/', methods=['GET', 'POST'])
def hello_world():
print(request.get_data(as_text=True))
return jsonify({
"ItemTaxContexts": [
{
"Id": "dbc98455f06d47359d47ae230119e28f",
"ProductCode": "blz-1001",
"Quantity": 1,
"Tax": 1.0,
"ShippingTax": 1.0,
"TaxData": {
}
}
],
"ShippingTax": 1.0,
"HandlingFeeTax": 3.0,
"OrderTax": 1.0
})
app.run(host='0.0.0.0', port=8000)
```
And then in your terminal:
```
\# In one terminal tab
python3 app.py
# In another terminal tab
ngrok http 8000
```
Use the URL that ngrok gives you as your application URL.
# Create From Cart (After)
Source: https://docs.kibocommerce.com/pages/create-from-cart-after
**Related API:** This extension modifies the [Create Order](/api-reference/order/create-order) operation.
This action occurs after an order is created from the cart. Changes made to the order or order items in this action persist in Kibo.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.orders.createFromCart.after |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = _function_(_context_, _callback_) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Order
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that creates orders from the cart.
## Get
### get.order
Obtains a response that includes information about the current order.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.order();
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setItemAllocation
Sets soft allocation information on an order item.
| Parameter | Type | Description |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the order item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for an order item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setAttribute
Sets an attribute from the order.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute to set on the order. Must apply to an existing attribute. |
| value | object | Value or values to set on the order for the specified attribute. |
Example:
```
context.exec.setAttribute("attributeName", value);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeAttribute
Removes an attribute from the order.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute to set on the order. Must apply to an existing attribute. |
Example:
```
context.exec.removeAttribute("attributeName");
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setData
Sets custom key/value data on the current order.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------ |
| key | string | Key of the data to set on the order. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the current order.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------- |
| key | string | Key of the data to remove from order. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on an order item.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| key | string | Key of the data to set on the order item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the order item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from an order item.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the order item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from an order item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setDutyAmount
Sets the duty amount applied to an order.
| Parameter | Type | Description |
| ---------- | ------ | ------------------------------------ |
| dutyAmount | number | The duty amount to set on the order. |
Example:
```
context.exec.setDutyAmount(8);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setHandlingAmount
Sets the handling amount applied to an order. This method is only available for the `embedded.commerce.orders.price.before` action. In addition, do not use both the `setHandlingAmount` and the `setItemHandlingAmount` methods within the same function, as this forces ambiguous adjustments on the handling amount.
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------- |
| handlingAmount | number | The handling amount to set on the order. |
Example:
```
context.exec.setHandlingAmount(3.99);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemHandlingAmount
Sets the handling amount applied to an order item. This method is only available for the `embedded.commerce.orders.price.before` action. In addition, do not use both the `setHandlingAmount` and the `setItemHandlingAmount` methods within the same function, as this forces ambiguous adjustments on the handling amount.
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------------------- |
| handlingAmount | number | The handling amount to set on the order. |
| itemId | string | Id of the item for which to set the handling amount. |
Example:
```
context.exec.setItemHandlingAmount(2, "123");
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create From Cart (Before)
Source: https://docs.kibocommerce.com/pages/create-from-cart-before
**Related API:** This extension modifies the [Create Order](/api-reference/order/create-order) operation.
This action occurs before an order is created from the cart. Changes made to the order or order items in this action persist in Kibo.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.orders.createFromCart.before |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = _function_(_context_, _callback_) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: Order
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that creates orders from the cart.
## Get
### get.order
Obtains a response that includes information about the current order.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.order();
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setItemAllocation
Sets soft allocation information on an order item.
| Parameter | Type | Description |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the order item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for an order item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setAttribute
Sets an attribute from the order.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute to set on the order. Must apply to an existing attribute. |
| value | object | Value or values to set on the order for the specified attribute. |
Example:
```
context.exec.setAttribute("attributeName", value);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeAttribute
Removes an attribute from the order.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------------------------- |
| fqn | string | Fully-qualified name of the attribute to set on the order. Must apply to an existing attribute. |
Example:
```
context.exec.removeAttribute("attributeName");
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setData
Sets custom key/value data on the current order.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------ |
| key | string | Key of the data to set on the order. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the current order.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------- |
| key | string | Key of the data to remove from order. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on an order item.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| key | string | Key of the data to set on the order item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the order item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from an order item.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the order item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from an order item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setDutyAmount
Sets the duty amount applied to an order.
| Parameter | Type | Description |
| ---------- | ------ | ------------------------------------ |
| dutyAmount | number | The duty amount to set on the order. |
Example:
```
context.exec.setDutyAmount(8);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setHandlingAmount
Sets the handling amount applied to an order. This method is only available for the `embedded.commerce.orders.price.before` action. In addition, do not use both the `setHandlingAmount` and the `setItemHandlingAmount` methods within the same function, as this forces ambiguous adjustments on the handling amount.
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------- |
| handlingAmount | number | The handling amount to set on the order. |
Example:
```
context.exec.setHandlingAmount(3.99);
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemHandlingAmount
Sets the handling amount applied to an order item. This method is only available for the `embedded.commerce.orders.price.before` action. In addition, do not use both the `setHandlingAmount` and the `setItemHandlingAmount` methods within the same function, as this forces ambiguous adjustments on the handling amount.
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------------------- |
| handlingAmount | number | The handling amount to set on the order. |
| itemId | string | Id of the item for which to set the handling amount. |
Example:
```
context.exec.setItemHandlingAmount(2, "123");
```
Response:
```
{
"acceptedDate": "DateTime",
"acceptsMarketing": "bool",
"adjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"amountAvailableForRefund": "decimal",
"amountRefunded": "decimal",
"amountRemainingForPayment": "decimal",
"attributes": [
{
"attributeDefinitionId": "int",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"fullyQualifiedName": "string",
"values": "object"
}
],
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"cancelledDate": "DateTime",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"closedDate": "DateTime",
"couponCodes": "string",
"currencyCode": "string",
"customerAccountId": "int",
"customerInteractionType": "string",
"customerTaxId": "string",
"data": "string",
"digitalPackages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"giftCardCode": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"dutyTotal": "decimal",
"email": "string",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"externalId": "string",
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"fulfillmentStatus": "string",
"handlingAmount": "decimal",
"handlingDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"handlingSubTotal": "decimal",
"handlingTaxTotal": "decimal",
"handlingTotal": "decimal",
"hasDraft": "bool",
"id": "string",
"importDate": "DateTime",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"ipAddress": "string",
"isDraft": "bool",
"isEligibleForReturns": "bool",
"isImport": "bool",
"isTaxExempt": "bool",
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"dutyAmount": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"originalCartItemId": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"locationCode": "string",
"notes": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"text": "string"
}
],
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"orderNumber": "int",
"originalCartId": "string",
"packages": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"hasLabel": "bool",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"packagingType": "string",
"shipmentId": "string",
"shippingMethodCode": "string",
"shippingMethodName": "string",
"status": "string",
"trackingNumber": "string"
}
],
"parentOrderId": "string",
"parentReturnId": "string",
"payments": [
{
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
}
],
"paymentStatus": "string",
"pickups": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"code": "string",
"fulfillmentDate": "DateTime",
"fulfillmentLocationCode": "string",
"id": "string",
"items": [
{
"fulfillmentItemType": "string",
"lineId": "int",
"productCode": "string",
"quantity": "int"
}
],
"status": "string"
}
],
"refunds": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"id": "string",
"orderId": "string",
"payment": {
"amountCollected": "decimal",
"amountCredited": "decimal",
"amountRequested": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"availableActions": "string",
"billingInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"billingContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"card": {
"cardNumberPartOrMask": "string",
"expireMonth": "short",
"expireYear": "short",
"isCardInfoSaved": "bool",
"isUsedRecurring": "bool",
"nameOnCard": "string",
"paymentOrCardType": "string",
"paymentServiceCardId": "string"
},
"isSameBillingShippingAddress": "bool",
"paymentType": "string",
"storeCreditCode": "string"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"id": "string",
"interactions": [
{
"amount": "decimal",
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"checkNumber": "string",
"currencyCode": "string",
"gatewayAuthCode": "string",
"gatewayAVSCodes": "string",
"gatewayCVV2Codes": "string",
"gatewayInteractionId": "int",
"gatewayResponseCode": "string",
"gatewayResponseText": "string",
"gatewayTransactionId": "string",
"id": "string",
"interactionDate": "DateTime",
"interactionType": "string",
"isManual": "bool",
"isRecurring": "bool",
"note": "string",
"orderId": "string",
"paymentEntryStatus": "string",
"paymentId": "string",
"paymentTransactionInteractionIdReference": "int",
"status": "string"
}
],
"isRecurring": "bool",
"orderId": "string",
"paymentServiceTransactionId": "string",
"paymentType": "string",
"status": "string"
},
"reason": "string"
}
],
"returnStatus": "string",
"shipments": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"cost": "decimal",
"currencyCode": "string",
"destinationAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"id": "string",
"originAddress": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"packageIds": "string",
"shippingMethodCode": "string",
"signatureRequired": "bool",
"trackingNumber": "string"
}
],
"shippingAdjustment": {
"amount": "decimal",
"description": "string",
"internalComment": "string"
},
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"methodCode": "string"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"shopperNotes": {
"comments": "string",
"giftMessage": "string"
},
"siteId": "int",
"sourceDevice": "string",
"status": "string",
"submittedDate": "DateTime",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"totalCollected": "decimal",
"type": "string",
"validationResults": [
{
"createdDate": "DateTime",
"messages": [
{
"message": "string",
"messageType": "string",
"orderItemId": "string"
}
],
"status": "string",
"validationId": "string",
"validatorName": "string",
"validatorType": "string"
}
],
"version": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Offline Orders
Source: https://docs.kibocommerce.com/pages/create-offline-orders
Both eCommerce and Order Management users can create offline orders to assist shoppers. This is different from [Cart Takeover](/pages/cart-takeover) because instead of returning the cart to the customer to finish the checkout process themselves, you will enter payment information on behalf of the shopper if possible and then submit the order.
Learn how to create offline orders in the KIBO Order Admin
If you are using Customer Sets, keep in mind that you can only create offline orders for customers that are assigned to the same customer set as the site on which you are creating the order. Refer to [Offline Orders and Customer Sets](/pages/structure-customer-sets) for more information.
## Create the Order
In Admin, complete the following steps to create an order for an offline shopper:
1. Go to **Main** > **Demand** > **Orders**.
2. Click **Create New Order**.
3. If you have more than one site, select the appropriate site from the drop-down menu that appears.
4. This will take you to the following page. The scrolling panel on the left is a list of existing orders, which you can hide by dragging the resize icon. The panel on the right is your new order details.
5. Select an existing shopper from the **Customer Search** drop-down, or click **Create New Customer** to enter new shopper information. The page will update with customer details in the order information.
* You can only select existing shoppers from the drop-down menu that are associated with the same customer set as the site you previously selected.
* If you create a new customer, complete all necessary fields in the Create Customer and Edit Address dialog boxes. When creating a new customer, at least one phone field (Home, Work, or Mobile) is required. Each customer must have a default billing and a default shipping address, but these defaults can be the same address. If you don't specify at least one phone number and both a default billing and default shipping address, errors will be returned during the order creation process.
6. In the **Order Details** section, click **Edit Details**.
7. Complete the following items in the Order Details dialog box that appears:
* Use the product search box under **Name** to specify a product.
* If the product has configurable options, select the customer's desired options in the pop-up that appears and click **Save**.
* If the product is enabled for [substitutions](/pages/substitute-products-overview "Substitute Products"), indicate whether the customer allows substitutions or not using the drop-down menu that appears underneath the product name.
* Select the item's **Fulfillment** method. There is a "Direct Ship" option for Ship to Home (STH) and individual location options for Buy Online Pickup in Store (BOPIS), including BOPIS variations such as Delivery.
* If STH, you should also select the **Shipping Method** from the dropdown below the table of line items.
* Inventory totals are displayed in the fulfillment options. The Direct Ship option will display an aggregate total, while the BOPIS options will display the total at that specific location. If the total includes [future inventory](/pages/future-inventory "Future Inventory"), the value will be underlined and hovering over it will then reveal a breakdown of future and current inventory levels.
* Specify a quantity for the product and click **Add**.
* (**Optional**) Apply a line item adjustment to the product price.
* Repeat steps a-e for additional products in the order.
* Select a shipping method for the order.
* (**Optional**) Add a coupon to the order or enter customer notes.
* (**Optional**) Indicate that the order is a gift by providing an order-level gift message. You can also enable **Include gift message for specific items** and then select the item(s) that you want to provide specific gift messages for.
* (**Optional**) Add a price list to the order. Refer to [Price List and Orders](/pages/price-lists-and-orders) for more information about associating a price list with an order.
* (**Optional**) Make an adjustment to the order total or shipping cost. You can also view a breakdown of the individual shipping, handling, tax, and duty subtotals by expanding the icons next to those fields.
8. Click **Save** to close the Edit Details modal.
9. The **Payments** tab will now be available.
* Here, click **Add Payment** to enter the customer's credit card information. Fill in all of the fields and then click **Save**.
* Alternatively, expand the drop-down menu to add a different payment type.
10. After payment information is saved, click **Submit Order** to place the order and add it to the system.
You should generally submit an offline order after entering order details and payment information. However, it is possible to submit an order as soon as soon as it has the basic order details (products and shopper information).
# Create or Edit a Search Configuration
Source: https://docs.kibocommerce.com/pages/create-or-edit-a-search-configuration
## Create a New Search Configuration
Learn how to create and configure search settings
1. To add a new entry, click **Create New Configuration**.\\
2. Enter a **Name** and **Description** for the configuration under the General tab. You will not be able to click the other tabs until the configuration is saved.\\
3. Click **Save**. To continue setting it up, refer to the Edit a Search Configuration steps below.
## Edit a Search Configuration
Now that the new setting entry is created, you can adjust it further by clicking **Edit** at the end of the row.
Follow the below steps to fully configure a new configuration, or update just a particular field if you only want to edit an existing configuration.
* The settings in the **Site Search** tab manage the Site Search API results:
1. Enable **Show Product Slicing** if you want product variants to be displayed separately in the API results. For example, if enabled then a red shirt and a blue shirt would be listed as separate products. If disabled, then the shirt will be listed as one product with color options for red and blue. See the [Slicing documentation](/pages/product-slicing) for more information about this feature.
2. Set the [**MinMatch**](/pages/minmatch) to determine how much of the search query needs to match a product. Kibo recommends three options: 100%, 75%, and 50%.
3. Set the [**Phrase Slop**](/pages/phrase-slop) to determine how many other words are permitted between a search query. Kibo recommends a value of 1 or 2.
4. Enable [**Auto Correct**](/pages/spell-correction#auto-correct) if you want to automatically switch to an auto-corrected search term if there are no results for MinMatch.
5. Use [**Did You Mean**](/pages/spell-correction#did-you-mean) to offer corrections for misspellings.
6. Add or edit desired [**Field Weights**](/pages/field-weights).
7. Create [**Boost and Bury**](/pages/boost-and-bury) conditions based on product attributes for all Site Search results. This can help boost popular products or bury low margin products.
8. Click **Save** in the top right.
* The settings in the **Category Suggestion** tab manage the Suggest2 API category suggestion results:
1. Add or edit desired [**Field Weights**](/pages/field-weights) for categories.
2. Select what [**Return Fields**](/pages/return-fields) should be included in the API response.
3. Click **Save** in the top right.
* The settings in the **Product Suggestion** tab manage the Suggest2 API product suggestion results:
1. Add or edit desired [**Field Weights**](/pages/field-weights) for products.
2. Select what [**Return Fields**](/pages/return-fields) should be included in the API response.
3. Create [**Boost and Bury**](/pages/boost-and-bury) conditions based on product attributes.
4. Click **Save** in the top right.
Note that Search Configurations are part of your catalog and site hierarchy. Always check that you are editing settings for the correct catalog and site in the page header.
# Create Package (After)
Source: https://docs.kibocommerce.com/pages/create-package-after
**Related API:** This extension modifies the [Add Package To Return](/api-reference/return/add-package-to-return) operation.
This action manipulates the HTTP request or response after the CreatePackage operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createPackage.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/packages/createPackage](/api-reference/return/add-package-to-return) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/packages?responseFields={responseFields}`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Package (Before)
Source: https://docs.kibocommerce.com/pages/create-package-before
**Related API:** This extension modifies the [Add Package To Return](/api-reference/return/add-package-to-return) operation.
This action manipulates the HTTP request or response before the CreatePackage operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createPackage.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/packages/createPackage](/api-reference/return/add-package-to-return) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/packages?responseFields={responseFields}`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Package Shipments (After)
Source: https://docs.kibocommerce.com/pages/create-package-shipments-after
**Related API:** This extension modifies the [Create Package Shipments](/api-reference/return/create-return-shipment) operation.
This action manipulates the HTTP request or response after the CreatePackageShipments operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createPackageShipments.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/shipments/createPackageShipments](/api-overviews/openapi_commerce_overview) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/shipments`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Package Shipments (Before)
Source: https://docs.kibocommerce.com/pages/create-package-shipments-before
**Related API:** This extension modifies the [Create Package Shipments](/api-reference/return/create-return-shipment) operation.
This action manipulates the HTTP request or response before the CreatePackageShipments operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createPackageShipments.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/shipments/createPackageShipments](/api-overviews/openapi_commerce_overview) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/shipments`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Return (After)
Source: https://docs.kibocommerce.com/pages/create-return-after
**Related API:** This extension modifies the [Create Returns](/api-reference/return/create-returns) operation.
This action manipulates the HTTP request or response after the CreateReturn operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createReturn.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns](/api-reference/return/create-returns) operation.
**HTTP Request**
POST `api/commerce/returns/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Return (Before)
Source: https://docs.kibocommerce.com/pages/create-return-before
**Related API:** This extension modifies the [Create Returns](/api-reference/return/create-returns) operation.
This action manipulates the HTTP request or response before the CreateReturn operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createReturn.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns](/api-reference/return/create-returns) operation.
**HTTP Request**
POST `api/commerce/returns/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Return Item (After)
Source: https://docs.kibocommerce.com/pages/create-return-item-after
**Related API:** This extension modifies the [Create Return Item](/api-reference/return/create-return-item) operation.
This action manipulates the HTTP request or response after the CreateReturnItem operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createReturnItem.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/createReturnItem](/api-reference/return/create-return-item) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/items?responseFields={responseFields}`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.request.body to read/write the HTTP request body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Return Item (Before)
Source: https://docs.kibocommerce.com/pages/create-return-item-before
**Related API:** This extension modifies the [Create Return Item](/api-reference/return/create-return-item) operation.
This action manipulates the HTTP request or response before the CreateReturnItem operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.createReturnItem.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/createReturnItem](/api-reference/return/create-return-item) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/items?responseFields={responseFields}`
**Request Body**\
Use context.request.body to read/write the HTTP request body using this action.
**Response Body**\
Use context.request.body to read/write the HTTP request body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Shipment (After)
Source: https://docs.kibocommerce.com/pages/create-shipment-after
**Related API:** This extension modifies the [Create Shipment](/api-reference/shipment/create-shipment) operation.
This action manipulates the HTTP request or response after the Create Shipment operation occurs in Kibo. Changes made to the shipment or shipment items in this action persist in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.fulfillment.createShipment.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Create Shipment](/api-reference/shipment/create-shipment) operation.
**HTTP Request**
POST `api/commerce/shipments`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Shipment (Before)
Source: https://docs.kibocommerce.com/pages/create-shipment-before
**Related API:** This extension modifies the [Create Shipment](/api-reference/shipment/create-shipment) operation.
This action manipulates the HTTP request or response before the Create Shipment operation occurs in Kibo. Changes made to the shipment or shipment items in this action persist in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.fulfillment.createShipment.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Create Shipment](/api-reference/shipment/create-shipment) operation.
**HTTP Request**
POST `api/commerce/shipments`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Shipments (After)
Source: https://docs.kibocommerce.com/pages/create-shipments-after
**Related API:** This extension modifies the [Create Shipments](/api-reference/shipment/create-shipments) operation.
This action manipulates the HTTP request or response after the Create Shipments operation occurs in Kibo. Changes made to the shipment or shipment items in this action persist in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.fulfillment.createShipments.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Create Shipments](/api-reference/shipment/create-shipments) operation.
**HTTP Request**
POST `api/commerce/shipments/bulk`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Shipments (Before)
Source: https://docs.kibocommerce.com/pages/create-shipments-before
**Related API:** This extension modifies the [Create Shipments](/api-reference/shipment/create-shipments) operation.
This action manipulates the HTTP request or response before the Create Shipments operation occurs in Kibo. Changes made to the shipment or shipment items in this action persist in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.fulfillment.createShipments.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Create Shipments](/api-reference/shipment/create-shipments) operation.
**HTTP Request**
POST `api/commerce/shipments/bulk`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create Subscription as Offline Order
Source: https://docs.kibocommerce.com/pages/create-subscription-as-offline-order
Customer service representatives can [place offline orders](/pages/create-offline-orders) for subscriptions as well. This supports mixed carts, in which the order includes both subscription and one-time purchase items in it. After selecting a subscribable product, subscription options will be displayed.
Learn how to configure subscription attributes and create offline subscription orders
1. If the product offers both subscriptions and one-time purchase, click the **Subscribe** checkbox to make it a subscription. If the product is subscription-only, this checkbox will be selected by default and cannot be turned off.
2. Select the desired **Frequency** from the dropdown. If the Subscribe checkbox was not checked, the frequency field will be greyed out and not editable.
3. Select the **Fulfillment** type (**Direct Ship** or **Pickup** at a selected location) for the product from the dropdown. You may have a combination of Direct Ship and Pickup items in one order.
4. Enter the **Quantity**.
5. Click **Add** to confirm the item.
6. If the product supports trial period, then a pop-up will appear after clicking **Add** to offer a trial. If the customer opts in for the trial, then the trial product will be shipped and the subscription product will only be shipped out after the trial period is complete.
7. You can then add more items, pick a shipping method for any Direct Ship items, input payment information, and place the order as with regular offline orders.
When the order is submitted, subscriptions will be created for the items based on frequency and shipping address. For example, an order could contain the following items:
* **Item A**: Pickup once per month.
* **Item B**: Pickup every other month.
* **Item C**: Direct Ship once per month to 123 First Street.
* **Item D**: Direct Ship once per month to 212 Rocky Avenue.
In this case, Items A and C will be placed into one subscription because they have the same frequency. Items B and D will be placed into their own separate subscriptions, because Item B has a different frequency and Item D has a different shipping address.
# Create User Auth Ticket (After)
Source: https://docs.kibocommerce.com/pages/create-user-auth-ticket-after
**Related API:** This extension modifies the [Create User Auth Ticket](/api-reference/storefrontauthticket/create-user-auth-ticket) operation.
This action manipulates the HTTP request or response after the CreateUserAuthTicket operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.authTickets.createUserAuthTicket.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/authTickets/CreateUserAuthTicket](/api-reference/storefrontauthticket/create-user-auth-ticket) operation.
**HTTP Request**
POST `api/commerce/customer/authtickets/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Create User Auth Ticket (Before)
Source: https://docs.kibocommerce.com/pages/create-user-auth-ticket-before
**Related API:** This extension modifies the [Create User Auth Ticket](/api-reference/storefrontauthticket/create-user-auth-ticket) operation.
This action manipulates the HTTP request or response before the CreateUserAuthTicket operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.authTickets.createUserAuthTicket.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/authTickets/CreateUserAuthTicket](/api-reference/storefrontauthticket/create-user-auth-ticket) operation.
**HTTP Request**
POST `api/commerce/customer/authtickets/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Creating a New Tax Integration
Source: https://docs.kibocommerce.com/pages/creating-a-new-tax-integration
You can calculate tax using Avalara and add your own tax engines using either API Extensions or tax calculator capability. If a user needs a service other than Avalara then the following approaches help to integrate your own tax calculator.
## Approach 1: Using estimateTaxes API Extension
This approach is used after creating a new API extension application.
The following steps set a tax response using the estimateTaxes API Extension:
1. Create a new **API Extension Application**. Refer to the [API Extension](/pages/api-extension-examples) document.
2. Use the [API Extension function.](/pages/estimate-taxes-before)
3. The [Estimate Taxes (Before)](/pages/estimate-taxes-before) file is shown in the following code block:
```
module.exports = function(context, callback) {
var responseBody = {
"itemTaxContexts" : [],
"shippingTax" : 0.00,
"handlingFeeTax" : 0.00,
"orderTax" : 0.00,
"taxData": { "taxPercent": 0.00 }
};
needle.get('https://example.com/taxService', (res) => {
var taxResponse = JSON.parse(data);
responseBody.orderTax = taxResponse.data.taxAmount
responseBody.taxData = { "taxPercent": taxResponse.data.taxPercentage };
var lineItem = taxOrderInfo.lineItems[0]; // assume there is at least 1 item in the order
responseBody.itemTaxContexts.push({
"id" : lineItem.id,
"productCode" : lineItem.productCode,
"quantity" : lineItem.quantity,
"tax" : taxResponse.data.taxAmount,
"shippingTax" : 0.0,
"feeTotal": taxOrderInfo.handlingFee
});
context.response.body = responseBody;
context.response.end();
callback();
});
};
```
The sum of the item.itemTaxContexts elements must equal to orderTax in all the examples given below. This is a requirement for any tax integration in KCCP to be able to correctly calculate the prorated taxes when items are split across shipments.
## Approach 2: Using Tax Calculator Capability
This approach helps you to add tax calculator capability through the Kibo commerce application.
The following steps add a tax calculator capability:
1. In Dev Center, navigate to **Develop** > **Applications > Packages > Capabilities.**
2. Click **Add Capability**.
3. Search for Tax Calculator in the **Add Capability** modal and click **Ok.**\\
4. Enter the external URL that receives the tax request and responds with the tax response. It will post to the URL directly and does not add any path.
5. Select the country you want to enable it for. Press the “Enabled” toggle to enable the calculator. It might take a minute to start working.\\
## Rest API Responses
This is what your endpoint will receive:
```
{
"OrderDate": "0001-01-01T00:00:00Z",
"TaxContext": {
"TaxContextId": "13",
"CustomerId": "",
"TaxExemptId": null,
"TaxShipping": true,
"OriginAddress": {
"Address1": "1835 Kramer Lane",
"Address2": "#100",
"Address3": null,
"Address4": null,
"CityOrTown": "Austin",
"StateOrProvince": "TX",
"PostalOrZipCode": "78758",
"CountryCode": "US",
"AddressType": null,
"IsValidated": false
},
"DestinationAddress": {
"Address1": "1234 Fake St",
"Address2": "",
"Address3": null,
"Address4": null,
"CityOrTown": "Houston",
"StateOrProvince": "TX",
"PostalOrZipCode": "12345",
"CountryCode": "US",
"AddressType": "Residential",
"IsValidated": null
}
},
"LineItems": [
{
"Id": "dbc98455f06d47359d47ae230119e28f",
"ProductCode": "blz-1001",
"VariantProductCode": null,
"ProductName": "Wool Blazer",
"ProductProperties": [
{
"AttributeFQN": "tenant~availability",
"Values": [
{
"Value": "24-48hrs",
"StringValue": "Usually Ships in 24 to 48 Hours"
}
],
"AttributeDetail": {
"InputType": null,
"ValueType": null,
"DataType": null,
"Name": "Availability",
"Description": null
},
"IsHidden": null,
"IsMultiValue": false
}
],
"Quantity": 1,
"LineItemPrice": 199.0,
"DiscountTotal": 0.0,
"DiscountedTotal": 199.0,
"ShippingAmount": 0.0,
"HandlingAmount": null,
"FeeTotal": 0.0,
"IsTaxable": true,
"Reason": null,
"Data": null,
"ProductDiscount": null,
"ShippingDiscount": null,
"ProductDiscounts": [],
"ShippingDiscounts": [],
"OriginAddress": null,
"DestinationAddress": null
}
],
"ShippingAmount": 0.0,
"CurrencyCode": "USD",
"HandlingFee": 0.0,
"OriginalDocumentCode": "13",
"OrderId": "12e9f48b2405bf00012c953200007729",
"OrderNumber": 13,
"OriginalOrderDate": "2022-01-20T17:06:35.0750575Z",
"TaxRequestType": "Order",
"Attributes": [],
"ShippingDiscounts": null,
"ShippingDiscount": null,
"OrderDiscounts": null,
"OrderDiscount": null,
"HandlingDiscounts": null,
"HandlingDiscount": null,
"ShippingMethodCode": null,
"ShippingMethodName": null
}
```
### Example: OrderTaxContext Response
This is what your endpoint should respond with:
```
{
"ItemTaxContexts": [
{
"Id": "dbc98455f06d47359d47ae230119e28f",
"ProductCode": "blz-1001",
"Quantity": 1,
"Tax": 1.0,
"ShippingTax": 1.0,
"TaxData": {
}
}
],
"ShippingTax": 1.0,
"HandlingFeeTax": 3.0,
"OrderTax": 1.0
}
```
### Example: Application
This just sends back dummy data for the specific order above, but it does work.
```
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/', methods=['GET', 'POST'])
def hello_world():
print(request.get_data(as_text=True))
return jsonify({
"ItemTaxContexts": [
{
"Id": "dbc98455f06d47359d47ae230119e28f",
"ProductCode": "blz-1001",
"Quantity": 1,
"Tax": 1.0,
"ShippingTax": 1.0,
"TaxData": {
}
}
],
"ShippingTax": 1.0,
"HandlingFeeTax": 3.0,
"OrderTax": 1.0
})
app.run(host='0.0.0.0', port=8000)
```
And then in your terminal:
```
\# In one terminal tab
python3 app.py
# In another terminal tab
ngrok http 8000
```
Use the URL that ngrok gives you as your application URL.
For a reference of all available platform capability types, see [Application Capabilities](/pages/applications-1a6c791-introduction#add-a-capability).
## Reading taxData Keys From an Order
When Kibo calculates tax, it splits the order into one or more taxable groups and records the result in the order's `taxData` object (a free-form JSON object also present on checkouts, quotes, shipments, subscriptions, and returns). The **top-level keys of `taxData` are not fixed field names** — they are generated from the fulfillment characteristics of the items in each group, so the same logical shipment can produce different keys depending on how the order is configured. Integrations that read a hardcoded key such as `Ship_Warehouse` will fail when that key changes shape.
### How taxData Keys Are Composed
Each key is built by joining the following parts with underscores:
```
{FulfillmentMethod}_{FulfillmentLocationCode}[_{ShippingMethodCode}]
```
| Part | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `FulfillmentMethod` | How the group is fulfilled: `Ship`, `Pickup`, `Curbside`, or `Digital`. |
| `FulfillmentLocationCode` | The code of the location fulfilling the group, for example `Warehouse`. |
| `ShippingMethodCode` | The [shipping method code](/pages/shipping-method-codes) for the group, for example `EXPEDITE`. This part is **conditional** — see below. |
### When and Why the Shipping Method Suffix Is Appended
The `_{ShippingMethodCode}` suffix is appended **only when at least one item on the order carries an item-level shipping method** (for example, orders that use split shipping or per-item delivery options). In that case, each group's key includes the shipping method code so that items shipped by different methods from the same location are tracked as separate taxable groups, since their shipping charges and tax differ.
If the order uses only a single order-level shipping method, no suffix is added — even though a shipping method exists on the order.
| Order configuration | Resulting key |
| ------------------------------------------------------------- | ------------------------- |
| Ships from `Warehouse`, order-level shipping method only | `Ship_Warehouse` |
| Ships from `Warehouse`, item-level shipping method `EXPEDITE` | `Ship_Warehouse_EXPEDITE` |
| Picked up at `Warehouse` | `Pickup_Warehouse` |
This is why a key can change from `Ship_Warehouse` to `Ship_Warehouse_EXPEDITE` without any change to your integration: it reflects a change in how shipping methods are assigned to the order (for example, switching from order-level to item-level shipping, or introducing a new shipping method code), not a renamed platform field. The suffix value is always the shipping method code carried by the order's items, so it varies by tenant and shipping configuration.
### Handle Key Variations Defensively
Because the suffix can appear, disappear, or change value depending on the order, **do not match `taxData` keys by exact string equality**. Match by the stable prefix instead (fulfillment method and location), and degrade gracefully when no matching group is present rather than letting the action throw — an unhandled error in a downstream step (such as sending a confirmation email) can leave the order in an errored state even though it was placed successfully.
```
module.exports = function(context, callback) {
try {
var order = context.get.order();
var taxData = order.taxData || {};
// Match on the stable prefix so an appended shipping method code
// (for example "_EXPEDITE") does not break the lookup.
var prefix = 'Ship_Warehouse';
var matchingKey = Object.keys(taxData).find(function(key) {
return key === prefix || key.indexOf(prefix + '_') === 0;
});
if (!matchingKey) {
// No matching taxable group on this order. Log and continue
// rather than throwing and leaving the order errored downstream.
console.warn('No taxData group found for prefix ' + prefix);
return callback();
}
var taxGroup = taxData[matchingKey];
// ... use taxGroup ...
callback();
} catch (err) {
console.error(err);
callback();
}
};
```
If your integration needs to react to a specific shipping method, read the matched key's suffix (everything after the `{FulfillmentMethod}_{FulfillmentLocationCode}_` prefix) rather than assuming a single fixed value. Iterating over all keys also lets you handle orders that split into multiple taxable groups, which is common once item-level shipping is in use.
# Curbside Delivery
Source: https://docs.kibocommerce.com/pages/curbside-delivery
Order fulfillment through Kibo’s Curbside Delivery provides a safer shopping experience for both the customer and store associate, allowing retailers to continue serving their customers while limiting traffic within the store and contact between individuals.
See how to fulfill buy online pickup in store orders
Curbside Delivery is an order management and fulfillment process with a flexible system of communication between the customer and retailer to enhance the pickup experience. These communications consist of email notifications that direct customers to landing pages to inform the retailer that they are on their way, that they have arrived, and details to identify their car or indicate where they prefer their order to be placed. This keeps both parties in sync and streamlines the pickup process to ensure accuracy.
## The Curbside Delivery Process
Curbside Delivery shipments follow a similar process as BOPIS (Buy Online Pickup in Store) shipments: the retailer accepts the order, validates stock, provides any available inventory to the customer, and then the order is complete. If there is no inventory, then the order is rejected and the customer is informed that it has been cancelled due to lack of inventory.
During this process, [a series of email notifications](#notifications) are received by the customer and retailer:
## Enable Curbside Delivery
To use Curbside Delivery, you should activate the email used during the Curbside process and enable the fulfillment method at the location level. You can also implement a customer widget on your storefront if you want to use it.
### Enable Notifications
Curbside Delivery supports notifications for both the store and the shopper to keep them both up-to-date on the delivery process. All of these notifications are enabled by default but can be disabled.
1. Go to **System** > **Settings** > **General** > **Emails**
2. Toggle the Curbside notifications you want to use. For descriptions of these specific emails, see the [Customer Notifications](#customer-notifications) and [Retailer Notifications](#retailer-notifications) sections below or the [General Settings documentation](/pages/general-settings).
### Enable for Locations
Existing fulfillment locations must have Curbside Delivery enabled as a fulfillment type in their location settings in order for that store to support the process.
1. Go to **Main** > **Supply** > **Locations** and click a location entry in the table, or click **Edit** from the dropdown actions menu on the right of the table row.
2. Click the **Fulfillment Types** field and select "Curbside Delivery" from the dropdown that appear.
3. Click **Save**.
### Implement the Widget
Kibo provides a widget that can be added to any storefront via a JavaScript tag to make Curbside Delivery accessible for the shopper. During checkout, the customer is able to select Curbside Delivery as their chosen fulfillment method. The widget also includes editable text fields for the retailer to collect information such as primary and optional alternate pickup contacts.
The widget does not automatically send any data to Kibo – the order information must be sent through a [Create Order API call](/pages/curbside-delivery). This widget is also not required; a custom process can be used instead if desired.
## Fulfill Curbside Orders
To get started fulfilling a shipment for a Curbside Delivery order:
1. Go to **Main** > **Fulfiller**.
2. Locate the shipment you want to fulfill, whether through the search bar or the widgets on the Fulfiller homepage.
3. Click **Continue to Process Order** to begin or resume fulfilling an order.
4. The first step is **Process Order**, where stock validation occurs. The expected quantity is shown in the table alongside blank In Stock fields. Retrieve the items and enter how many out of the expected quantity they were able to collect as In Stock.
* If only some items are in stock, then partial pickup will be indicated as shown below and the unavailable items will be cancelled. If there is no inventory in stock for any item in the order, the user will not be able to continue to Provide to Customer and will instead cancel the entire order.
5. In the **Provide to Customer** step, the user confirms whether the customer (either the primary pickup contact or the alternate contact, if one was specified) successfully picked up the order. The customer may provide a QR code that can be scanned to verify their identity by validating their code against the order and pickup number.
6. Click either **Customer Accepts Entire Order** or **Customer Cancelled Entire Order** to complete fulfillment. If the customer accepts the order, it is marked complete. If they do not accept the order, it is cancelled with an automatic reason code of "PURCHASE NOT PICKED UP."
## Notifications
Emails allow the customer to generate status updates so that the retailer’s store associates know when to bring the order to the curb. These updates are submitted through links in the notifications. The customer will always receive these email notifications by default.
Kibo provides the default template for notifications, but they [can be customized through your theme](/pages/email-template-customization "Email Template Customization"). If you customize these emails, note that the content must fit within a character limit of 160 characters.
### Customer Notifications
The email notification topics that are sent to customers are listed below. If an alternate pickup contact was specified for the order, then these notifications will be sent to the alternate contact in addition to the primary customer.
* **Order Confirmation:** Triggered when an order is placed and provides pickup instructions including the store location and order items.
* **Order Pickup Ready:** Tells the customer that their full or partial order is ready for pickup. Triggered when the fulfiller has processed the order and placed it into the Provide to Customer state. This includes a link for the customer to indicate that they are on their way, but also includes an option to say they already arrived in case they did not say that they were in transit earlier (see example on previous page).
* **In Transit Confirmation**: Triggered when the customer indicates that they are on their way. This includes a link for them to indicate that they have arrived, which leads to a landing page with the retailer's preferred customer identification details and delivery options, such as the car make/model, parking spot number or license plate, and preference for which door or window to place the order in. When the customer arrives at the location and submits this information, the page displays a QR code that the store associate can scan when they bring the order to further validate the customer.
* **Order Complete:** Triggered whenever the order has been marked as fulfilled.
* **Order Cancellation:** Triggered whenever the order is cancelled, whether lack of inventory or not picked up.
### Retailer Notifications
Retailers receive two notifications that are unique to Curbside during the fulfillment process, Customer In Transit and Customer Arrived. Both are triggered by the customer giving an update to indicate their arrival status, allowing the retailer to know when to take the order to the curb.
* **Shipment Assigned / Fulfillment Location Assigned:** Triggered when an order is placed and assigned to their fulfillment location, and is thus ready to be processed.
* **Customer In Transit:** Triggered when the customer indicates they are on their way after their order is ready for pickup. This notification tells the retailer that the customer is en route and should be expected soon.
* **Customer Arrived:** Triggered when the customer indicates that they have arrived and submitted any identification information about their car or delivery preferences. Upon receiving this notification and customer information, a store associate should take the order to the curb and provide it to the customer.
* **Item Cancelled:** A cancellation confirmation that is triggered whenever an item is cancelled, such as if the store associate indicates that there was not enough inventory in stock.
If a customer fails to indicate that they are on their way, they are still able to indicate they are curbside from the landing page. In this case, the Customer In Transit notification for the retailer would be skipped and the retailer would immediately receive the Customer Arrived notification.
## Customer Surveys
A survey link can be added within any of the customer email notifications. This link leads to a landing page with a form that lists four prompts about their Curbside Delivery experience, allowing them to rank their satisfaction on a scale from 1 (Strongly Disagree) to 5 (Strongly Agree). These prompts request the customer's opinion about:
* Their experience with their store associate
* Overall experience with their order
* Whether they intend to use the curbside option again
* Whether they were satisfied with the communication and notification process
* Any additional feedback as a freeform response
Upon submitting these answers, the customer is thanked for providing feedback.
# Custom Data Lists
Source: https://docs.kibocommerce.com/pages/custom-data-lists
Data lists allow for custom information to be stored and utilized in filters, letting you further fine-tune how specific routing cases are handled. For instance, if a scenario cannot fulfill certain product UPCs then a data list could be created that contains those UPCs. A filter could then be created with that data list applied to the "Item UPC" attribute, so that those items would not be assigned to locations in that scenario.
Note that changes to routing settings may not immediately take effect when processing orders. It may take up to 15 minutes for updates to be reflected in the system while the cache refreshes.
Custom data lists are now known as "filter data lists" and are independent global entities, not defined for a specific strategy. They can be used as filters across any strategy or scenario.
### Data Lists Page
The **Filter Data Lists** page displays all existing data lists in a table. Click the **Current Site** selector in the top right to switch to a different site and view its data lists instead.
### Create a New Data List
To create a new data list:
1. Go to the **Filter Data Lists** page.
2. Click **Add Filter Data List**.
3. Enter a **Name** for the data list.
4. Select the **Data Type** (Text, Number, Location, or Date) you want to use for the list values.
5. Enter an optional **Description**.
6. When initially creating a data list, its values should be provided via .CSV file upload. A template for building this file can be downloaded from the **Download Template** button.
7. Click **Save**.
### Edit Data Lists
Once a list has been created, it can be managed or edited from the Filter Data Lists page. Click the **Delete** icon in the Actions column to remove a data list entirely. If you want to delete a data list, you must first remove it from any filters it's currently used in.
To update a data list and its values instead:
1. Click the **Edit** icon in the Actions column of any list to view its configurations.
2. Edit the list's **Name** or **Description** as needed.
3. Use the action icons in the values table to modify or delete any existing fields.
4. Click **Add New Row** to define additional value:description data pairs.
5. To export the current data list as a CSV file, click the **Download as CSV** button located to the right of the **Add New Row** button
6. Click **Save Changes**.
### Export a Data List as CSV
There are two ways to export a data list:
**From within a Data List (Data List Detail Page)**
1. Open a data list by clicking the **Edit** icon in the Actions column on the Filter Data Lists page.
2. Click the **Download as CSV** button, located to the right of the **Add New Row** button.
3. The file downloads automatically and includes the following columns:
* **Value** — the stored value for each entry
* **Description** — the full description for each entry (untruncated)
4. The export reflects all entries for the currently selected site.
**From the Filter Data Lists Page (List-Level Export)**
1. Navigate to the **Filter Data Lists** page.
2. In the **Actions** column of the data list you want to export, click the **Export** icon.
3. The CSV file for that specific data list downloads automatically.
# Custom Data Sets
Source: https://docs.kibocommerce.com/pages/custom-data-sets
You can define custom location-specific data types that can then be used in filters, such as to reject locations with a particular value. Or, this data can be used as a sort option in scenarios to compare the locations. This may be hourly rates, staff levels, or other attributes that apply to every location but may vary in value.
Data types can also be populated in many APIs as a `customData` object with the configured name and a value appropriate to the data type.
**Custom Data Sets have been deprecated in the New Routing UI.** Existing data sets configured in the legacy Routing UI will continue to be available and can be used in the New Routing UI. However, users will no longer be able to create or add new custom data sets from the New Routing UI.
# Custom Reports
Source: https://docs.kibocommerce.com/pages/custom-reports
Custom reports can be either created from an existing report or created from scratch, and viewed by everyone with the appropriate reporting permissions. You have the option to directly download reports, send them to an email address, or send them to an SFTP droppoint.
Learn how to explore and customize reports
## SFTP Best Practices
If you are using a client-side or third-party SFTP droppoint to receive reports, Kibo recommends following the below guidelines to maximize performance.
* Ensuring access to the SFTP droppoint is the responsibility of the client or third party maintainer. Make sure that Kibo's SFTP user has read and write permissions to the directory, which is required to deliver files.
* For example, in the command line this may look like `drw-rw-r--` (which means the owner has read/write, the group has read/write, others are read-only)
* Ensure files do not pile up over time. Utilize /archive folders and periodic cleanup of historic data. Monitor the droppoint and clean up files that are no longer needed.
* If you need to retain the files, archive them to another folder once they’ve been processed.
* Ensure disk space usage is monitored and alerts the maintaining IT team in time to address low disk space situations before causing connection issues for Kibo.
## Create From Existing Report
A Report Editor user can create custom reports by editing an existing report.
1. Click on right top corner of a tile and then **Explore from Here**.
2. The Explore page displays all current report dimensions and measures. It is possible that this will change the page header to an older version of the UI, but you can still navigate the folder directory and access other options in the top right corner.
3. Change fields by pulling dimensions and measures from the left pane into the **Data** section in the right pane.
4. You can further configure the Data section by clicking the gear icon on a table and changing settings such as calculations, hiding that data from the visualization, filling in missing dates, etc.
5. Expand the **Filters** section to configure the applied filters.
6. You can further edit the Visualization section by clicking **Edit** on the right and changing the axis, positioning, layout, etc.
7. Click **Run** in the top right to generate the report.
8. To save the report, click on the gear icon and select whether to save it as a look (saving the individual report to view in the future) or to a dashboard (adding the report as a tile on a larger dashboard with other reports).
9. If you click **Save as Look**, a modal will appear with several options. Enter a title and description for this custom report.
10. Select whether to save the report to your Personal (where only the creator of the report can access it) or Shared (where all Report Viewers across the organization can access the report and Report Editors can also modify the report) folder.
## Create From Scratch
Rather than base the new report off of an existing one, the Reporting Editor can also create and save their own reports from the data found in the explores.
1. In the folder navigation, go to **Shared** > **Kibo Standard Reports** > **Explores**.
2. Select the explore to base the report on.
3. From that screen, expand the gear icon at the top right and click **Explore From Here**.
4. Customization options will be displayed. Select the dimensions and measures to include in the report from the menu on the left. Each selected dimension or measure will show up in the **Data** tab in the right.
5. The **Data** section displays the raw report results and includes features such as selecting sort order for columns, specifying the maximum rows to return, dragging and dropping columns to reorder them, and adding custom calculations. View pivots by hovering over a dimension and clicking **Pivot**.
6. Filters can be added the same way. Expand the **Filters** section and configure the values for filters there.
7. Once all data has been selected and filters have been applied, expand the **Visualization** tab to see a graphical depiction of what the report would look like as a tile. Select different visualization types to analyze which works best for the data. For more control, use the gear icon in the top right to access more granular configurations.
8. Click the top-level gear icon to save the new report. It can be saved as an individual look or added to a dashboard, as well as directly downloaded or sent via email/SFTP/etc. A **Save & Schedule** option will save the report as a look and set up recurring delivery.
## View Custom Reports
The shared folder, where all Report Viewers in the organization can access the report and all Report Editors can modify the report, is located at **Shared** > **Custom Reports**.
# Custom Route Settings
Source: https://docs.kibocommerce.com/pages/custom-route-settings
Custom routing allows you to display SEO-friendly URLs on your site that map behind-the-scenes to conventional Kibo eCommerce resources such as a product page or a search results page. With custom routing, you gain advanced control over the URL structures on your site and can more visibly highlight the products or categories your shoppers are interested in purchasing.
For example, a category page for women's tops from a certain designer might have a URL in Kibo eCommerce that looks like: `yourSite.com/tops/c/45`. However, for SEO reasons you may prefer that the category page use a URL such as `yourSite.com/womens/tops/designerName`. With custom routing, you can use the SEO-friendly URL and let Kibo eCommerce map it to the correct category page.
Kibo eCommerce parses incoming URLs for your site and matches them to internal routes using specific rules that you set in the Custom Routing JSON Editor. To open the editor, log in to Admin and go to **System** > **Customization** > **Custom Routes**.
## Define URL Routes
To define a custom route you have to:
1. [Create templates to identify URL patterns for custom routing](#create-templates-to-identify-url-patterns-for-custom-routing).
2. [Specify the internal routes to send matching URLs to](#specify-the-internal-routes-to-send-urls-to).
3. (**Optional**) [Create mappings between URL parameters and Kibo eCommerce objects](#create-mappings-between-url-parameters-and-kibo-ecommerce-objects).
4. (**Optional**) [Use validators to restrict which URL values result in a match](#use-validators-to-restrict-which-url-values-result-in-a-match).
5. (**Optional**) [Choose which URLs are canonical](#choose-which-urls-are-canonical).
6. (**Optional**) [Choose the URL scheme for the route](#choose-the-url-scheme-for-the-route).
7. [Verify that the order of templates in the JSON code does not cause conflicts](#verify-that-the-order-of-templates-does-not-cause-conflicts).
### Examples
The following code block shows a completed example of a custom route that you would enter into the JSON editor at **System** > **Customization** > **Custom Routes**, and the subsequent sections in this topic explain the details of the code. A productCode is always required in a custom route, but this example shows that the productCode parameter can be mapped to the productName. This allows the productName to be referenced in the URL template when the name and code are the same. For more real-world examples, see the [Custom Routing Examples](#custom-routing-examples) section.
Capitalization is not important for the JSON code described in this topic.
```
{
"mappings": {
"productMap": {
"type": "direct",
"mappings" : {
"productName" : "ProductCode"
}
}
},
"validators": {
"colorVal": {
"type": "productAttribute",
"attributeFqn" : "color"
}
},
"routes" : [
{
"template": "home/{documentName}",
"defaults": {
"documentListName" : "pages@mozu"
},
"internalRoute": "CmsPage",
"mappings": {},
"validators": {},
"canonical": true,
"urlScheme": "https"
},
{
"template": "{productName}/p/{brand}/{attribute}",
"defaults": {},
"internalRoute": "ProductDetails",
"canonical": true,
"urlScheme": "https",
"mappings": {
"productMap" : [
"productName"
]
},
"validators": {
"colorVal": [
"attribute"
]
}
}
]
}
```
If at any point you want to return a route to the Kibo eCommerce default, simply delete the applicable custom routes from the JSON editor.
In addition to the routes discussed in this topic, you can also [create routes to API Extension functions](#create-a-route-to-an-api-extension-function).
## Create Templates to Identify URL Patterns for Custom Routing
Templates allow Kibo eCommerce to identify which URLs belong to a custom route by specifying the pattern of URL constants, variables, and segments that should match to a specific route. For example, you may want to apply a custom route to a URL that looks like `yourSite.com/promotions/summer/july`. This URL has three segments after the domain name. One of the segments includes a constant (`"promotions"`) and the other segments include variables. A template that identifies this type of URL might look like the following example when you enter it into the JSON editor:
```
"routes" : [
{
"template": "promotions/{season}/{month}"
}
]
```
### Template Syntax
When creating templates, use the following syntax rules:
* Define variables in the URL as template parameters by enclosing them in braces `{ }`.
* You can name URL parameters whatever you wish. However, within a given template, every parameter name must be unique.
* Take advantage of the `{categorySlug}`, `{categoryCode}`, and `{categoryId}` parameters, which provide automatic [validation for categories](#category-validator) in a URL.
* Use forward slashes `/` as delimiters for URL segments.
* Any characters that are not within braces or are not forward slashes are treated as constants that must appear in the URL for a match to occur.
* To include more than one parameter within a set of delimiters, separate the parameters with a constant value. For example, `{categorySlug}-{designer}/{page}` separates the `categorySlug` and `designer` parameters with a hyphen.
* Use an asterisk to handle a variable number of URL segments. For example, `{categorySlug}/{*pages}`.
* Make sure your templates do not conflict with the [default Kibo eCommerce routes](#default-kibo-ecommerce-routes).
### Examples of Templates
The following table shows a list of templates and examples of URLs that match the templates.
| Template | Example of matching URL |
| -------------------------------- | -------------------------------------------------------------------------- |
| `{categoryCode}/p/{productCode}` | `bicycles/p/CAN-209` |
| `{a}-{b}/sale/{page}` | `mens-shoes/sale/new` |
| `{categorySlug}/{brand}/{color}` | `apparel/designer/black` |
| `new/{*pages}` | `new/shoes new/shoes/sandals new/office new/home/kitchen/silverware` |
| etc. | |
Kibo eCommerce identifies a match for a URL parameter so long as there are characters in the URL segment where the URL parameter is located. For example, in the first row of the preceding table, `"CAN-209"` matches to the `productCode` parameter, but any number of other characters would also match, such as `"bogusCode123"`. You may be wondering how you can create a match only when certain conditions apply, such as when a URL parameter matches an existing attribute value on your site. In a later section, you learn how to use validators to apply constraints to the values that can match to a particular parameter.
### Default Kibo eCommerce Routes
The following table lists the default routes in Kibo eCommerce. You cannot overwrite these routes and if you create a template that conflicts with one of these routes, your template will not work, so you should make sure to avoid a naming conflict.
| Relative URL | Internal Route |
| ------------------------------------------------------------------------------- | ----------------------- |
| `user/signup` | User Signup page |
| `cart` | Cart page |
| `user/login` | User Login page |
| `logout` | User Logout page |
| `user/forgotpassword` | Forgot Password page |
| `c/{categoryCode}` | |
| or | |
| `{categorySlug}/c/{categoryCode}` (if slug is present) | Category page |
| `p/{productCode}` | |
| or | |
| `{productSlug}/p/{productCode}` (if slug is present) | Product page |
| `p/{productCode}?vpc={productVariationCode}` | |
| or | |
| `{productSlug}/p/{productCode}?vpc={productVariationCode}` (if slug is present) | Product Variant page |
| `home` | |
| or | |
| `/` | Home page |
| `about-us` | About Us page |
| `contact` | Contact page |
| `location` | Store Locator page |
| `myaccount` | My Account page |
| `checkout/{orderId}` | Checkout page |
| `checkout/{orderId}/confirmation` | Order Confirmation page |
## Specify the Internal Routes to Send URLs To
For each template, you need to specify the internal route that a matching URL should use. You specify this route using the `"internalRoute"` object.
In addition, some routes require specific parameters, such as a product code, to complete the route successfully. You specify these parameters using either the `"defaults"` object or by extracting them from the URL.
The following example demonstrates how you can create an internal route from `yourSite.com/pendants` to a search results page for the query, `"pendant lights"`.
```
"routes": [
{
"template" : "pendants",
"internalRoute": "Search",
"defaults": {
"query": "pendant lights"
}
}
]
```
The preceding example uses the `"internalRoute"` object to identify the type of internal route and the `"defaults"` object to provide the value for the `"query"` parameter, which is a global parameter that you can apply to all routes.
As mentioned, you can also extract the parameter values from the URL. For example, let's say you want to create an internal route to a product details page. This type of internal route requires a product code. The following example obtains the value of the product code from the URL instead of from the `"defaults"` object:
```
"routes" : [
{
"template": "sports/{categorySlug}/{productCode}",
"internalRoute": "ProductDetails"
}
]
```
Because the URL parameter name in the template, i.e. `"{productCode}"`, matches the name of the required parameter for the internal route, i.e. `"ProductCode"` (see the *Available Internal Routes* table), Kibo eCommerce uses the value of the URL parameter to complete the internal route. So if a URL on your site looks like `yourSite.com/sports/soccer/ball-203`, Kibo eCommerce routes the URL to the correct product details page using the product code "ball-203".
If you want to extract a value from the URL but do not want to give the URL parameter the same name as the required parameter for the internal route, you can use a mapping.
### Available Internal Routes and Corresponding Parameters
Refer to the following table for a list of the internal routes available in Kibo eCommerce and the parameters they require. You also have access to [global parameters](#global-parameters) available to all routes.
Capitalization doesn't matter when specifying either the route or the parameters.
#### Internal Routes and Parameters
| Internal Route | Required Parameters | Optional Parameters |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------------- |
| `ProductDetails` | ProductCode | vpc |
| `Category` | | |
| [CategoryId](#route-specific-parameters) or [CategoryCode](#route-specific-parameters)
|
| [Page](#route-specific-parameters) |
| | |
|
\| `Search` | |
[CategoryId](#route-specific-parameters)
|
| [Page](#route-specific-parameters) |
|
\| `CmsPage` |
[DocumentListName](#route-specific-parameters)
|
| [DocumentName](#route-specific-parameters) |
\| |
\| `CmsList` | [DocumentListName](#route-specific-parameters) | [ListView](#route-specific-parameters) |
\| `Cart` | | |
Refer to the following tables to learn about the required and optional route parameters. In addition to route-specific parameters, Kibo eCommerce provides global parameters accessible to all routes.
#### Route-Specific Parameters
| Route-Specific Parameter | Description |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ProductCode` | Specifies the Product Code property of a product. This should be a minimum of 3 characters, up to a maximum of 30. |
| `vpc` | Specifies the Variation Product Code property of a product with configurable options. This code enables you to route to a [product variant](/pages/product-variations). |
| `CategoryId` / `CategoryCode` | |
| Specifies the numeric ID of the category or the value of the Category Code property for the category. | |
**Note:** When creating a route, use either the CategoryId parameter or the CategoryCode parameter, but not both.
|
\| `Page` |
Specifies at which page to start displaying page results when you do not specify a start index.
When you specify the Page parameter, Kibo eCommerce determines the start index for page results by multiplying Page by the page size for your template.
|
\| `DocumentListName` | Specifies a document list name. |
\| `DocumentName` | Specifies a document name. |
\| `ListView` | Specifies a list view. |
#### Global Parameters
| Global Parameter | Description |
| ----------------------------------- | ----------- |
| `SortBy` | |
| Specifies how to sort page results. | |
You sort by a number of different properties available in Kibo eCommerce, such as Category ID, Product Price, etc., and provide an "asc" or "desc" direction for ascending or descending order. For example, `"sortBy: ProductPrice asc"`
This syntax matches what displays in URLs when sorting is applied to your site: `yourSite.com/products?sortBy=productprice asc`.
|
\| `Query` | Specifies the query string for searches. |
\| `StartIndex` | Specifies at which item to start displaying page results. The default is 0, which corresponds to the first item in the results. |
\| `PageSize` | Specifies how many results to display per page. |
\| `FacetValueFilter` | Specifies the facet to filter results with. |
## Create Mappings Between URL Parameters and Kibo eCommerce Objects
Mappings allow you to map the values of URL parameters to other JSON variables or to Kibo eCommerce objects such as facet values. Mappings work by adding or replacing entries in the Kibo eCommerce route dictionary. The following types of mappings are available for use:
* [Direct](#direct-mappings)
* [Facet](#facet-mappings)
* [Regex](#regex-mappings)
* [Use the beforeRouting Boolean for Category Mappings](#use-the-beforerouting-boolean-to-apply-mappings-to-category-parameters)
To configure mappings, you create a `"mappings"` object at the same level as the `"routes"` object. This `"mappings"` object contains the details of all the mappings available to your site. You also create a `"mappings"` object at the same level as the `"templates"` object within the `"routes"` object. This `"mappings"` object specifies the name of the mapping to use for a particular route.
If you want to apply a mapping to a template that includes a `categoryCode`, `categoryId`, or `categorySlug` parameter, you must add the [`"beforeRouting"` Boolean](#use-the-beforerouting-boolean-to-apply-mappings-to-category-parameters) to the mapping.
### Direct Mappings
Direct mappings reassign the value of a URL parameter to another value.
The following example demonstrates a route that reassigns the value of the `"{product}"` URL parameter. For the URL `yourSite.com/flowers/scarletRoses`, Kibo eCommerce executes a route to a product details page in the `"flowers"` category using `"redRoses"` as the new product code by applying the `"productMap"` mapping to the parameter `"product"`. Note that you must enable the [`"beforeRouting"` property](#use-the-beforerouting-boolean-to-apply-mappings-to-category-parameters) so that the mapping takes place before the route occurs.
```
{
"mappings": {
"productMap": {
"type": "direct",
"beforeRouting": true,
"mappings" : {
"scarletRoses" : "redRoses"
}
}
},
"routes" : [
{
"template": "{categorySlug}/{product}",
"defaults": {},
"internalRoute": "ProductDetails",
"mappings": {
"productMap": [
"product"
]
}
}
]
}
```
### Facet Mappings
Facet mappings allow you to assign the value of a URL parameter to one of the following search parameters:
* `Query`
* `CategoryId`
* `SortBy`
* `StartIndex`
* `Page`
* `PageSize`
* `FacetValueFilter`
Facet mappings are designed to work with Category and Search routes; they do not have practical value if used in conjunction with the other internal routes.
The following example demonstrates a route that assigns the value of the `"{color}"` URL parameter to the `"facetValueFilter"` search parameter. For the URL `yourSite.com/accessories/ties/red`, Kibo eCommerce executes a route to a `"accessories/ties"` category page using `"red"` as the faceting value by applying the `"facetMap"` mapping to the parameter `"color"`. In this example, the benefit of the mapping is that you can use an SEO-friendly URL for a faceted search results page that would otherwise require a character-heavy query string in the URL to display a list of red ties. Note that you must enable the [`"beforeRouting"` property](#use-the-beforerouting-boolean-to-apply-mappings-to-category-parameters) so that the mapping takes place before the route occurs.
```
{
"mappings": {
"facetMap": {
"type": "facetValueFilter",
"mapTo": "facetValueFilter",
"beforeRouting": true,
"facetId": "color"
}
},
"routes" : [
{
"template": "{parent-categorySlug}/{categorySlug}/{color}",
"defaults": {},
"internalRoute": "Category",
"mappings": {
"facetMap": [
"color"
]
}
}
]
}
```
You can also map URL parameters to facets using the `"_facetId_-facet"` token in the template. This syntax recognizes that the URL parameter should be mapped to a facet and doesn't require you to code the mapping details. Using this syntax, the previous example looks like:
```
{
"routes" : [
{
"template": "{parent-categorySlug}/{categorySlug}/{tenant~color-facet}",
"defaults": {},
"internalRoute": "Category",
"mappings": {}
}
]
}
```
### Regex Mappings
With a regex mapping, you can search for a string pattern in a URL parameter and replace it with another string of your choosing. Optionally, you can leave the URL parameter intact, and instead apply the new pattern to a custom key-value pair in the [routeData global variable](/pages/email-customization-theme-reference#global-variables-available-in-hypr-templates), which can later be accessed in a Hypr template or through an API Extension application.
The following example demonstrates a regex mapping that applies the `"toSpace"` mapping to the `"{categorySlug}"` parameter. The `"toSpace"` mapping searches for non-whitespace characters, such as underscores, and replaces them with spaces. The optional field, `"mapTo"`, applies the result of the replacement to the a custom key-value pair in the `routeData` global variable. If you wanted to apply the replacement to the URL parameter that the mapping targets, you would omit the `"mapTo"` field.
```
{
"mappings": {
"toSpace": {
"type": "regex",
"mapTo": "categoryName",
"pattern": "\\\\S",
"replacement": " "
}
},
"validators": {},
"routes": [
{
"template": "clearance/{categorySlug}/index",
"defaults": {
"documentListName": "pages@mozu"
},
"internalRoute": "CmsPage",
"toSpace": {
"": [
"categorySlug"
]
},
"canonical": true,
"validators": {}
}
]
}
```
### Use the "beforeRouting" Boolean to Apply Mappings to Category Parameters
When you apply a mapping to a template that includes a category parameter, such as `categoryCode`, `categoryID`, or `categorySlug`, you must include the `"beforeRouting"` Boolean (set to `true`) in the route. Otherwise, the route uses the value of the category parameter before the mapping has had a chance to take place. The following example demonstrates a mapping that reassigns `"coat"` category parameter values to `"jackets"`. For such a case, the `"beforeRouting"` Boolean is necessitated.
```
{
"mappings": {
"categoryMapping": {
"type": "direct",
"beforeRouting": true,
"mappings": {
"coats": "jackets"
}
}
},
"routes": [
{
"template": "winter/{categoryCode}",
"internalRoute": "Category",
"mappings": {
"categoryMapping": [
"categoryCode"
]
}
}
]
}
```
## Use Validators to Restrict Which URL Values Result in a Match
Validators require that URL parameters meet certain conditions before Kibo eCommerce considers the template a match. Take the following template as an example: `{categorySlug}/{attribute}`. Without a validator, a URL can have any number of values in the location of the `{attribute}` parameter and still match the template. With a validator in place, Kibo eCommerce checks whether the parameter value meets a set of specified criteria, for example, whether it corresponds with an existing attribute defined on your site, and only matches the template when this check is true.
You can use the following types of validators:
* [Attribute](#attribute-validator)
* [List](#list-validator)
* [Category](#category-validator)
* [Facet](#facet-validator)
### Attribute Validator
Attribute validators check whether a URL parameter corresponds to an existing attribute on your site. These validators require you to provide the administration name of an attribute in order for Kibo eCommerce to look up the values of the attribute and determine if a match exists.
The following example demonstrates how to implement an attribute validator. Let's assume that you have defined an attribute on your site with the administration name of `"color"` and that the attribute contains the values `"red"`, `"green"`, and `"blue"`. With the validator in place, the URL `yourSite.com/products/green` matches the template: Kibo eCommerce applies the `"colorVal"` validator to the `"{colorValue}"` parameter, checks whether `"green"` matches any of the values of the attribute with the administration name of `"color"`, and finds a match. On the other hand, the URL `yourSite.com/products/purple` does not match the template because `"purple"` is not a defined value for the `"color"` attribute.
```
{
"validators": {
"colorVal": {
"type": "productAttribute",
"attributeFqn" : "color"
}
},
"routes" : [
{
"template": "products/{colorValue}",
"internalRoute": "ProductDetails",
"validators": {
"colorVal": [
"colorValue"
]
}
}
]
}
```
### List Validator
List validators check whether a URL parameter matches any value within a list that you define in the JSON code.
The following example demonstrates how to implement a list validator. With the validator in place, the URL `yourSite.com/products/vacuum` matches the template: Kibo eCommerce applies the `"productVal"` validator to the `"{productValue}"` parameter, checks whether `"vacuum"` matches any of the values defined in the list, and finds a match.
```
{
"validators": {
"productVal": {
"type": "stringlist",
"values" : [
"broom", "mop", "vacuum"
]
}
},
"routes" : [
{
"template": "products/{productValue}",
"internalRoute": "ProductDetails",
"validators": {
"productVal": [
"productValue"
]
}
}
]
}
```
### Category Validator
Kibo eCommerce contains logic to automatically validate your category tree when you create routes to category and product pages (`"internalRoute": "Category"` and `"internalRoute": "ProductDetails"`, respectively). This saves you the trouble of having to explicitly add validators to check whether the value of a URL parameter corresponds to an existing category on your site.
To take advantage of this logic, name category parameters in your template according to the following syntax rules:
* To identify a URL parameter as a category that Kibo eCommerce should validate, use one of the names described in the following table. During validation, Kibo eCommercechecks whether the parameter value matches the corresponding property value of a category on your site.
| URL Parameter Name | Matching Category Property |
| ------------------ | -------------------------- |
| `{categorySlug}` | SEO Friendly URL |
| `{categoryId}` | Auto-generated numeric ID |
| `{categoryCode}` | Category Code |
* To identify a URL parameter as a parent category, use the prefix `parent-`. This allows you to validate and display a category structure in a URL, such as `yourSite.com/office-supplies/pens`.
* To identify a second level of parent category, use the prefix `grandParent-`.
* To identify additional levels of parent categories, use the prefix `great-` before `grandParent-`. You can string together additional `great-` prefixes to create additional category levels.
* As an alternative to the `parent/grandParent` syntax, you can place a colon after the category parameter and use the `ancestors(n)` token to specify parent levels, where `n` is the number of parent categories the template requires.
* To identify two separate category trees within the same URL, specify a constant prefix for one of the category trees.
The following table lists examples of templates that employ category parameters. The table also shows examples of URLs that contain category codes, SEO-friendly names, and IDs that match the pattern of the templates. Behind the scenes, Kibo eCommerce checks whether the values match to existing category values on your site.
| Template | Example of matching URL |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `{categorySlug}/{product}` | `sofas/recliner-01` |
| `{parent-categoryCode}/{categoryCode}/{product}` | `Seating3/Sofas/recliner-01` |
| `{grandParent-categoryId}/{parent-categoryId}/{categoryId}/{product}` | `19/14/21/recliner-01` |
| `{great-grandParent-categorySlug}/{grandParent-categorySlug}/{parent-categorySlug}/{categorySlug}/{product}` | `furniture/seating/living-room/sofas/recliner-01` |
| `{great-great-grandParent-categorySlug}/{great-grandParent-categorySlug}/{grandParent-categorySlug}/{parent-categorySlug}/{categorySlug}/{product}` | `home/furniture/seating/living-room/sofas/recliner-01` |
| `{categorySlug:ancestors(5)}/{product}` | `home/furniture/seating/living-room/sofas/recliner-01` |
| `specials/{specials-categorySlug}?cat={parent-categorySlug}/{categorySlug}` | `specials/dresses?cat=womens/designer-dresses` |
### Facet Validator
Kibo eCommerce contains logic to automatically validate whether a URL parameter corresponds to a valid facet value. To take advantage of this logic, use the following syntax for facet parameters in your template:
```
{_namespace_~_attributeName_\-facetValue}
```
If you construct a parameter using this syntax, Kibo eCommerce automatically validates whether the facet value exists for a given attribute (which is identified by its namespace and administration name). The following table shows an example of a template that employs a template parameter and a URL that matches the template. Before identifying a match, Kibo eCommerce validates whether `"south-america"` is a valid facet value for the `"tenant~region"` attribute.
| Template | Example of matching URL |
| -------------------------------------------------------- | -------------------------- |
| `{categorySlug:ancestors(2)}/{tenant~region-facetValue}` | `food/fruit/south-america` |
## Choose Which URLs Are Canonical
Custom routing allows you to map multiple URLs to the same content. For example, the URLs `yourSite.com/shop/green-tea` and `yourSite.com/healthy-drinks` can both link to the same category page for green teas. While there are many benefits to having multiple paths to the same content, search engines can penalize websites for displaying the same content on more than one web page.
To counteract this negative effect on SEO, Kibo eCommerce uses the `canonical` flag to mark a URL structure as the preferred one for search engine crawlers to index and for shoppers to see in the URL bar after the route executes. By default, the standard Kibo eCommerce URL structure (for example, `yourSite.com/{categorySlug}/c/{categoryCode}` for category pages) is marked as canonical. However, if you want the URL structure defined by one of your templates to be canonical instead (thereby displaying it to shoppers after the route executes and marking it to be indexed by search engine crawlers), apply the `canonical` flag.
```
{
"routes" : [
{
"template": "shop/{categoryCode}",
"internalRoute": "Category",
"canonical" : true
}
]
}
```
Non-canonical routes execute a 301 redirect to the canonical route, and any values specified in the `"defaults"` object of the non-canonical route are overwritten by the values in the `"defaults"` object of the canonical route. In the preceding example, if a shopper were to type in the standard URL to a Kibo eCommerce category page (`yourSite.com/{categorySlug}/c/{categoryCode}`), Kibo eCommerce would redirect them to `yourSite.com/shop/{categoryCode}`.
## Choose the URL Scheme for the Route
You can set the URL scheme for the route to either `http` or `https`. This allows you to set encryption on a route generated from a non-secure request. If you do not specify this property, the default is `http`.
```
{
"routes" : [
{
"template": "shop/{categoryCode}",
"internalRoute": "Category",
"urlScheme" : "https"
}
]
}
```
The scheme you set in the JSON overrides the scheme of the incoming request. For example, if an incoming HTTP request matches a template whose `"urlScheme"` property is set to `https`, then the route occurs as normal but changes the scheme to HTTPS.
## Verify that the Order of Templates Does Not Cause Conflicts
When Kibo eCommerce searches for a routing template to match an incoming URL request, it checks the templates in the order that the they are defined in the Custom Routing JSON Editor. Once Kibo eCommerce finds the first match, it does not evaluate the remaining templates in the editor to determine if there is a better match. This means that Kibo eCommerce may never evaluate a template if a more general template precedes it in the JSON code.
The following example shows the correct way to order your templates when there is a possibility of a match conflict. In the example, the `"offers/{price}"` template includes a validator that checks whether the `"{price}"` parameter matches to a value in the specified list. The `"offers/{new}"` template is more general and does not include a validator. If we have two incoming URLs, `yourSite.com/offers/under35` and `yourSite.com/offers/desk-ornaments`, the first URL matches to the `"offers/{price}"` template and the second URL matches to the `"offers/{new}"` template.
However, what would happen if we reversed the order of the templates in the JSON editor? In this case, a match conflict renders one of the templates useless because Kibo eCommerce would match both URLs to the `"offers/{new}"` template and never evaluate the more restrictive `"offers/{price}"` template.
```
{
"validators": {
"priceVal": {
"type": "stringlist",
"values" : [
"under35", "35-50", "over50"
]
}
},
"routes" : [
{
"template": "offers/{price}"
"internalRoute": "Category",
"validators": {
"priceVal": [
"price"
]
}
},
{
"template": "offers/{new}",
"internalRoute": "Category",
}
]
}
```
## Create a Route to an API Extension Function
You can use the `http.storefront.routes` action to bind an API Extension function to a route on your site. This allows you to run the API Extension function when the route is requested versus having to respond to a specific event on a page—providing you more flexibility to run functions independently from the events used in other functions. For example, you can create an arbitrary URL for a third-party service to POST to and have the function process the data when it is received.
Before completing the steps in this topic, you should be familiar with the API Extensions framework and also with setting up custom routes:
* [Configure Custom Routing](#define-url-routes)
* [API Extensions Help](/pages/what-you-can-do-with-api-extensions)
Complete the following steps to create the route:
1. Scaffold an API Extension application that contains the `http.storefront.routes` action.
2. Add code to the custom function tied to the action. For example, in the `http.storefront.routes.js`file:
```
module.exports = function(context) {
context.response.body = "Hello Custom Routing!";
context.response.end();
};
```
3. Note the name of the function in the `storefront.manifest.js` file, located in the `assets/src` directory. The default name matches the action name, but you can change the name if you wish. In the following example, the default function name is changed to `hello_custom_routing`.
```
'hello_custom_routing': {
actionName:'http.storefront.routes',
customFunction: require('./domains/storefront/http.storefront.routes')
}
```
4. Build and upload the application to Dev Center.
5. Install the application to a sandbox.
6. From Admin, ensure that the `http.storefront.routes` action is enabled in the Action Management JSON Editor.
7. In the Custom Routing JSON Editor, create a route to the function using:
* `"internalRoute": "Arcjs",`
* `"functionId": "_yourFunctionName_",`
8. You can add mappings, validators, and any other custom route features that you wish, as discussed in the main [custom routing section](#define-url-routes).
```
{
"mappings": {},
"validators": {},
"routes": [
{
"template": "shop/deals",
"defaults": {},
"internalRoute": "Arcjs",
"functionId": "hello_custom_routing",
"mappings": {},
"validators": {}
}
]
}
```
## Custom Routing Examples
View JSON sample code for the following custom routing scenarios:
* [Route to a Document](#route-to-a-document)
* [Route to a Product](#route-to-a-product)
* [Route to a Document Through a Regex Mapping](#route-to-a-document-through-a-regex-mapping)
* [Modify the Category Slug for Routes to Specific Designer Pages](#modify-the-category-slug-for-routes-to-specific-designer-pages)
* [Include Key-Value Pairs Within a Document Route](#include-custom-key-value-pairs-within-a-document-route)
* [Route to an API Extension Function](#route-to-an-api-extension-function)
#### Route to a Document
`yourSite.com/sales/may` routes to the document named `may` within the `sales@yourSite` document list.
```
{
"mappings": {},
"validators": {},
"routes": [
{
"template": "sales/{documentname}",
"defaults": {
"documentListName": "sales@yourSite"
},
"internalRoute": "CmsPage",
"mappings": {},
"validators": {},
}
]
}
```
#### Route to a Product
The default route to a product details page is `yourSite.com/{productSlug}/p/{productCode}`. If you want to provide an alternative route to a product details page, use the following custom route as an example:
If you want your alternative route to be indexed by search engines and to be the URL that shoppers see on the product details page, set the `canonical` flag to `true`.
```
{
"mappings": {},
"validators": {},
"routes": [
{
"template": "shop/{productSlug}/{productCode}/info",
"defaults": {},
"internalRoute": "ProductDetails",
"mappings": {},
"canonical": false,
"validators": {},
}
]
}
```
#### Route to a Document Through a Regex Mapping
You can route to a document using a regex mapping, as shown in the following example, which removes whitespace from category slugs that match a specific format and then renders a resulting route to the correct document. A case where this may be useful is when mapping a productName parameter to a productCode, as shown in the first example of this guide. Using a regex allows you to strip or replace the spaces from your productName to match the productCode.
```
{
"mappings": {
"category-regex": {
"type": "regex",
"mapTo": "documentname",
"pattern": "\\\\s",
"replacement": ""
}
},
"validators": {},
"routes": [
{
"template": "variations/{variations-categorySlug}/index",
"defaults": {
"documentListName": "pages@mozu"
},
"internalRoute": "CmsPage",
"mappings": {
"category-regex": [
"variations-categorySlug"
]
},
"canonical": true,
"validators": {}
}
]
}
```
#### Modify the Category Slug for Routes to Specific Designer Pages
You can replace or modify how specific designer category URLs display, as shown in the following example, where for specific designer pages any instance of `mens` in the URL category slugs is replaced with `men` instead:
```
{
"mappings": {
"singular": {
"type": "regex",
"beforeRouting": true,
"pattern": "mens",
"replacement": "men"
}
},
"validators": {
"designers": {
"type": "stringlist",
"values": [
"designerA",
"designerB",
"designerC"
]
}
},
"routes": [
{
"template": "{designer}/{categorySlug:ancestors(5)}",
"defaults": {
"categorySlug": "shop",
"isDesignerPage": "true"
},
"internalRoute": "Category",
"mappings": {
"singular": [
"categorySlug",
"parent-categorySlug",
"grandParent-categorySlug",
"great-grandParent-categorySlug",
"great-great-grandParent-categorySlug",
"great-great-great-grandParent-categorySlug"
]
},
"canonical": true,
"validators": {
"designer": [
"designers"
]
}
}
]
}
```
#### Include Custom Key-Value Pairs Within a Document Route
You can route to a document while including key-value pairs in the `"defaults"` object, which are then accessible in the resulting page's Hypr template through use of the [routeData](/pages/email-customization-theme-reference#global-variables-available-in-hypr-templates) global variable. In the following example, the key-value pairs that you make accessible to the Hypr template are `"list": "pages@mozu"` and `"isOffersPage": "true"`. You can then use these specific values to modify the content that the template displays in response to the route that executes.
```
{
"mappings": {},
"validators": {},
"routes": [
{
"template": "pages/{name}/{documentListFQN}/{documentProperty-page_type_definition}",
"defaults": {
"list": "pages@mozu",
"isOffersPage": "true"
},
"internalRoute": "CmsPage",
"mappings": {},
"canonical": false,
"validators": {}
}
]
}
```
#### Route to an API Extension Function
You can create a route that serves as an endpoint for a custom API Extension function to execute on. For example, you can create a route that runs a custom function for your PayPal integrations whenever the `paypal/checkout` endpoint is hit:
```
{
"mappings": {},
"validators": {},
"routes": [
{
"template": "paypal/checkout",
"defaults": {},
"internalRoute": "Arcjs",
"functionId": "myPayPalFunction",
"mappings": {},
"validators": {}
}
]
}
```
# Custom SDKs
Source: https://docs.kibocommerce.com/pages/custom-sdks
If you want an SDK for a language that Kibo does not provide, you can use open source software to develop your own for any language. Kibo recommends using the OpenAPI Generator tool and then improving its API authentication process as shown in our provided packages.
While you can view API endpoints and request/response models in our [API documentation](/api-overviews/getting-started), you can also access their OpenAPI specifications through [this repository](https://github.com/KiboSoftware/kibo-open-api-specs).
## OpenAPI Generator
You can access the OpenAPI Generator in two ways:
* Directly from the [open source repository](https://github.com/OpenAPITools/openapi-generator)
* Using a [cli wrapper](https://www.npmjs.com/package/@openapitools/openapi-generator-cli) around the above repository
Refer to the ReadMe files of those repositories for the most up-to-date usage instructions. As an example, the high-level steps for creating a Kibo SDK in Java with the cli wrapper would be:
1. Install the cli tool with `npm install -g @openapitools/openapi-generator-cli`
2. Clone [Kibo's OpenAPI specifications](https://github.com/KiboSoftware/kibo-open-api-specs).
3. Run cli pointing to the file in the OpenAPI specs folder with `openapi-generator-cli generate -g java -i kibo-open-api-specs/main/docs/openapi_commerce.json -o /var/tmp/java-commerce-client`
## SDK Authentication
The OpenAPI Generator doesn't automatically generate the best API authentication. To improve this process, Kibo provides the following public packages for you to reference while implementing similar authentication in your desired language.
* [TypeScript/JavaScript authentication package](https://github.com/KiboSoftware/sdk-authentication)
* [Java authentication package](https://github.com/KiboSoftware/kibo.auth.sdk)
### Example
Kibo recommends using the TypeScript/JavaScript package if possible, as it includes cleaner code. The below steps describe how to use that package.
1. Install with `npm install @kibocommerce/sdk-authentication`
2. Ensure you have the following information for configuration.
* `authHost`: Kibo Commerce Authentication Host Server. It is used to request an access token from the Kibo Commerce OAuth 2.0 service.
* `clientId`: Unique Application (Client) ID of your application. This is viewable from your Dev Center.
* `sharedSecret`: Secret API key used to authenticate your application/client ID.
3. Run the following code for authorization:
```
// import API Auth Client
import { APIAuthClient } from '@kibocommerce/sdk-authentication'
// configuration parameters
const config = {
clientId: 'client_id'
sharedSecret: 'secret',
authHost: 'home.mozu.com'
}
const apiAuthClient = new APIAuthClient(config, fetch)
const kiboAccessToken = await apiAuthClient.getAccessToken()
const response = await fetch('https://some-kibo-api', { headers: { 'Authorization': \`Bearer ${kiboAccessToken}\` }})
```
Alternatively, if you are using an version of Node prior to Version 18 or need to use a custom Fetch client:
```
// import API Auth Client
import { APIAuthClient } from '@kibocommerce/sdk-authentication'
// import Fetch API compatible client
import fetch from 'node-fetch';
// configuration parameters
const config = {
clientId: 'client_id'
sharedSecret: 'secret',
authHost: 'home.mozu.com'
}
const apiAuthClient = new APIAuthClient(config, fetch)
const kiboAccessToken = await apiAuthClient.getAccessToken()
const response = await fetch('https://some-kibo-api', { headers: { 'Authorization': \`Bearer ${kiboAccessToken}\` }})
```
### Token Refresh
Kibo access tokens are valid for one hour and Kibo recommends reusing them as much as possible. This package will automatically handle the refresh of tokens. The client constructor accepts an optional `authTicketCache`.
A simple example of an in-memory cache:
```
interface AuthTicketCache {
getAuthTicket: (clientId:string) => Promise
setAuthTicket: (clientId: string, kiboAuthTicket: AppAuthTicket) => void
}
const memo = {}
const memCache: AuthTicketCache = {
getAuthTicket: async (clientId:string) => {
return memo[clientId]
},
setAuthTicket: (clientId: string, kiboAuthTicket: AppAuthTicket) => {
memo[clientId] = kiboAuthTicket
}
}
// import API Auth Client
import { APIAuthClient } from '@kibocommerce/sdk-authentication'
// import Fetch API compatible client
import fetch from 'node-fetch';
// configuration parameters
const config = {
clientId: 'client_id'
sharedSecret: 'secret',
authHost: 'home.mozu.com'
}
const apiAuthClient = new APIAuthClient(config, fetch, memCache)
const kiboAccessToken = await apiAuthClient.getAccessToken()
```
# Customer Account Access
Source: https://docs.kibocommerce.com/pages/customer-account-access
Control customer account access by enforcing two-factor authentication, resetting passwords, disabling accounts, and unlocking accounts (which may have been locked due to the user failing to input the correct password).
## 2FA and OTP Authentication
You can trigger these authentication features on your storefront wherever you choose to in the buying journey—such as when the customer is creating an account, logging into their account, or immediately before checkout.
* **Two-Factor Authentication (2FA)**: This emails a 6-digit code to the customer after they attempt to log in with their username and password. This can be triggered upon every login, when a new device fingerprint is detected, or when they are accessing your site from a different region than their previous visit. This can also be triggered upon sign up.
* **One-Time Password (OTP)**: This is an alternative login method that sends a temporary password to the customer as a 6-digit code. This may be useful during account signup to ensure that only users with valid email addresses can register for an account.
You can enable both of these authentication strategies at the same time if you want to. When either one is triggered, the customer will have three minutes to input a valid code. If the time expires or they enter an incorrect code three times, they must request a new one.
### Enable Authentication Options
Before integrating these functions into your storefront, enable them in your site settings:
1. Go to **System** > **Settings** > **General** > **Storefront**.
2. Scroll down to the the Customer Login Settings section.
3. Enable 2FA and/or OTP options depending on how you want to authenticate customers.
* **Always Require Two-Factor Authentication**: Triggers 2FA on every login attempt or signup attempt. If enabled, the Fingerprint Change and Region Change options will be disabled.
* **Two-Factor Authentication** **on Fingerprint Change**: Triggers 2FA when a login attempt is made from a new or unverified device fingerprint, including if there is no pre-existing device fingerprint to compare against. This can be enabled alongside Requires 2FA on Region Change.
* **Two-Factor Authentication** **on Region Change**: Triggers 2FA when a login attempt is detected from a different geographic region than the last validated region. This can be enabled alongside Requires 2FA on Fingerprint Change.
* **Allow Login using Email** **OTP**: Allows customers to request an email with a one-time password to log in with. This can be enabled alongside any 2FA settings.
4. Click the **Emails** tab and then toggle on **OTP for login** under Miscellaneous Emails.
5. Subscribe to the Email Requested [application event](/pages/event-subscription#configure-subscriptions "Event Subscription") (in the Email category) in order to trigger your own communications if you prefer not to use Kibo's emails.
6. Click **Save**.
### Call OTP from the Storefront
To implement OTP in your storefront:
1. Provide a button or link on your storefront for the customer to request a code, which calls the Generate OTP Code endpoint (POST `.../api/commerce/customer/authtickets/otp/request`).
2. Include their User ID and email in the request body as shown below, as well as their device fingerprint and/or region. The email should generally be the address that the customer entered in the username field, or the address associated with their account if the username is not a valid address.
```
{
"userId": "string",
"email": "string",
"fingerprint": "string",
"region": "string"
}
```
3. Once the customer enters a code on your storefront, call the Validate OTP endpoint (POST `.../api/commerce/customer/authtickets/otp/auth`) with the below IDs and entered code value.
```
{
"userId": "string",
"customerAccountId": 00000,
"otpCode": "string",
"fingerprint": "string",
"region": "string"
}
```
4. A successful validation will return a 200 OK response with `"requires2fa" = false` and a new auth token, allowing the customer to proceed. A 401 Unauthorized error with `"requires2fa" = true` instead indicates that the code was invalid and they should try again.
### Call 2FA from the Storefront
To implement 2FA on your storefront:
1. When the user attempts to log in, call the [Create User Auth Ticket API](/api-reference/storefrontauthticket/create-user-auth-ticket) and provide the region and/or device fingerprint that you obtain from the user's device.
```
{
"username": "string",
"password": "string",
"accountId": 00000,
"fingerprint": "string",
"region": "string"
}
```
2. The system will verify the region and/or device fingerprint against their previously validated records and update the user claims to indicate whether the `requires2fa` flag is true or false. Check these user claims after making the request to determine your next step.
3. If 2FA is required, call the Generate 2FA Code endpoint (POST `.../api/commerce/customer/authtickets/2fa/request`) and provide the customer's User ID in the request body. The email with a code will be sent to the address associated with their account.
```
{
"userId": "string"
}
```
4. Once the customer enters a code on your storefront, call the Validate 2FA and Create Auth Ticket endpoint (POST `.../api/commerce/customer/authtickets/2fa/auth`). Provide the User ID and code that they entered in the request body.
```
{
"userId": "string",
"otpCode": "string"
}
```
5. A successful validation will return a 200 OK response with `"requires2fa" = false` and a new auth token, allowing the customer to proceed. A 401 Unauthorized error with `"requires2fa" = true` instead indicates that the code was invalid and they should try again.
### Bypass 2FA
The embedded ARC action allows dynamic control over 2FA requirements and can be used to bypass Two-Factor Authentication (2FA) flows during customer sign-up and sign-in processes.
## Reset Shopper Passwords
If a customer has forgotten their password or having other issues logging in, you can reset it from the Admin UI. Bear in mind that only registered shopper accounts have passwords; guest accounts cannot log in.
1. Go to **Main** > **Customers** > **Customers**.
2. Browse or search for the account you want to reset the password for.
3. Select the account.
4. Click **Reset Password** next to the **Account Status** value.
5. Confirm.
All registered customers' passwords must be at least six characters in length, and include at least one number and one letter. For security purposes, the reset link will remain active for only 72 hours.
## Disable Shopper Access
If needed, you can fully disable a customer's access to their account. Keep in mind that you can only disable registered shopper accounts; guest accounts cannot log in. Furthermore, disabling an account only prevents the shopper from logging in with the email address associated with the account. It does not prevent that individual from registering for another account with a different address.
1. Go to **Main** > **Customers** > **Customers**.
2. Browse or search for the shopper account you want to disable.
3. Select the account.
4. Select the **Disable Account** checkbox below the **User Name** field.
5. Click **Save**.
## Unlock Locked Accounts
If a shopper tries and fails to log in too many times, the account may become locked. To unlock it:
1. Go to **Main** > **Customers** > **Customers**.
2. Browse or search for the shopper account you want to reset the password for.
3. Select the account.
4. Click **Unlock Account** next to the **Account Status** value.
5. Confirm.
# Customer Account Segment View
Source: https://docs.kibocommerce.com/pages/customer-account-segment-view
The Customer Account Segment view provides dimensions describing the customer segments you have defined and allows you to connect your customers with segments.
See how to create and manage customer segments
The measures calculated by this view are:
| Name | Measure Type | Description |
| --------------------- | ------------ | --------------------------------- |
| Account Segment Count | Count | Count of account segment records. |
The dimensions included in this view are:
| Name | Data Type | Description |
| ---------------------------- | --------- | --------------------------------------------------------------------- |
| Account Segment Created Date | Datetime | Date and time when the segment-account relationship was created. |
| Account Segment Updated Date | Datetime | Date and time when the segment-account relationship was last updated. |
| Customer Account ID | Number | Unique identifier of the customer account. |
| Segment Code | String | User-provided identifier for the segment. |
| Segment Created Date | Datetime | Date and time when the segment was created. |
| Segment ID | Number | System-generated unique identifier for the segment. |
| Segment Updated Date | Datetime | Date and time when the segment was last updated. |
# Customer Attributes
Source: https://docs.kibocommerce.com/pages/customer-attributes
Customer attributes are attributes that you can apply to customer accounts to add further definition for special uses, such as marketing campaigns, or discounts. These are primarily used by instances of the Kibo Composable Commerce Platform with the Kibo eCommerce solution, rather than Order Management-only implementations.
See how to create and manage customer attributes
You can configure customer attribute values to display only in Admin, or in both Admin and on the storefront. You can also specify whether the definition or selection of associated values can be done by shoppers, administrators, or both. You can choose various input and data types with various input parameters.
## Create a Customer Attribute
To create a customer attribute:
1. Go to **System** > **Schema** > **Customer Attributes**.
2. Click **Create New Customer Attribute**.
3. Enter an **Attribute Label**. Keep in mind that this may appear on the storefront if you specify it to display there with the next step.
* If you want to give it a different name for administration purposes, edit the **Administration Name**. The default name is the **Attribute Label**.
* If you want to customize the **Attribute Code**, edit the value accordingly. This field automatically populates based on the **Attribute Label**.
4. Select a **Display Group**. This field determines whether the attribute displays in the Admin UI only or in both the Admin and storefront.
5. Select a **Value Source** to determine whether this attribute's value can be set via the Admin UI and/or Storefront. If you chose the Admin Only display group, then Admin Entered is the only valid source.
6. Select an **Input Type**.
* If you choose **List**, select a **Data Type** and enter the selection options in the **Values** field.To allow users to select multiple options from this list, select the **Allow Multi Select** checkbox.
* If you choose **Text box**, select a **Data Type**. Optionally, you can define input parameters in the **Min char/val** and **Max char/val** fields, or enter a regular expression in the **Input validation** field.
* If you choose **Text area**, you can optionally define a **Max char** value.
* If you choose **Date**, you can optionally define a start and/or end date for the selectable range.
7. Toggle on **Available for Discounts** if you want this attribute to be available for use in [discount conditions](/pages/configure-discounts#attribute-conditions "Configure Discounts").
8. Click **Save**.
For example, you might create a customer attribute called Communication Preferences that you want to use in order to keep track of how your customers prefer to be contacted. When creating the customer attribute, you can specify the following:
## Apply a Customer Attribute
If an attribute is set to either the **Admin Entered** or **Admin & Shopper Entered** value source:
1. Go to **Main** > **Customers** > **Customers**.
2. Select the customer account to which you want to apply the attribute.
3. In the **Customer Attributes** section, select the value of your choice.
# Customer Contact View
Source: https://docs.kibocommerce.com/pages/customer-contact-view
The Customer Contact view provides dimensions describing the contact information for your customers.
The measures calculated by this view are:
| Name | Measure Type | Description |
| ------------- | ------------ | ------------------------- |
| Contact Count | Count | Count of contact records. |
The dimensions included in this view are:
| Name | Data Type | Description |
| -------------------- | --------- | ----------------------------------------------------------- |
| Address 1 | String | The first line of the street address. |
| Address 2 | String | The second line of the street address. |
| Address 3 | String | The third line of the street address. |
| Address 4 | String | The fourth line of the street address. |
| City or Town | String | The contact's city or town. |
| Contact Created Date | Datetime | The date and time that the contact record was created. |
| Contact ID | Number | The unique identifier for the contact. |
| Contact Updated Date | Datetime | The date and time that the contact record was last updated. |
| Country Code | String | The country code of the contact's address. |
| Customer Account ID | String | Internal unique identifier of the customer account. |
| Home Phone | String | The home phone number for the contact. |
| Middle Name | String | The contact's middle name or initial. |
| Mobile Phone Number | String | The mobile phone number for the contact. |
| Postal Code | String | The postal code for the address. |
| State or Province | String | The state or province for the contact address. |
| Work Phone Number | String | The work phone number for the contact. |
# Customer Dashboard
Source: https://docs.kibocommerce.com/pages/customer-dashboard
The Customer dashboard provides key metrics related to customers. This can be viewed at **Kibo Standard Reports** > **Customer** > **Customer Dashboard** in the navigation menu.
See the Customer API documentation for programmatic access
The supported filters that can be applied to this dashboard are:
| Name | Description | Default |
| --------- | ---------------------------------------------------------------------------- | ------- |
| Is Active | Filter results by whether accounts are flagged as active, inactive, or both. | Yes |
The measures that are calculated by this dashboard are:
| Name | Description |
| ------------------------ | ----------------------------------------------------------- |
| Customer Count | The count of all customer records. |
| Days Since Last Login | The number of days since the last log in by the customer. |
| Days Since Last Purchase | The number of days since the last purchase by the customer. |
| Days Since Signup | The number of days since the customer account was created. |
| Lifetime Value | The sum of all purchases made by the customer. |
| Order Count | The number of orders placed by the customer. |
| Order Frequency | The average duration between purchases by the customer. |
| Wishlist Length | The count of items on the customer's wishlist. |
The tiles that make up this dashboard are:
| Name | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Active Customers | The customer count for all customers where "Is Active" equals yes. |
| Average Order Count | The average order count for all customers. |
| Average Order Frequency | The average order frequency for all customers. |
| Average Wishlist Length | The average wishlist length for all customers. |
| Average Days Since Signup | The average days since sign up for all customers. |
| Average Days Since Last Login | The average days since last login for all customers. |
| Average Days Since Last Purchase | The average days since last purchase for all customers. |
| Average Lifetime Value | The average lifetime value for all customers. |
| Order Count | The order count per customer, grouped by tier. |
| Top Locales | The customer count grouped by locale. |
| Tax Exempt | Pie chart comparing how many customer accounts are tax exempt and how many are not. |
| Accepts Marketing | Pie chart comparing how many customer accounts accept marketing and how many do not. |
| Days Since Last Login | The count of customer accounts with the number of days since last login falling under specific tiers. |
| Days Since Last Purchase | The count of customer accounts with the number of days since last purchase falling under specific tiers. |
| Lifetime Value | The count of customer accounts with a lifetime value falling under specific tiers. |
# Customer Purchase Orders
Source: https://docs.kibocommerce.com/pages/customer-purchase-orders
Kibo eCommerce's purchase order functionality allows your shoppers to use a purchase order as a payment method on your storefront.
Before a customer can use the purchase order payment method on your storefront, you must first enable the purchase order payment method for your site(s). Once you've enabled the purchase order payment method for your site(s), you can then enable the ability for a customer to use the purchase order payment method.
Refer to [Enable Purchase Orders](/pages/purchase-orders#enable-purchase-orders) for more information about purchase orders and enabling the purchase order payment method for your site(s).
Customers must have an existing customer account before you can enable the purchase order payment method for them. You enable the purchase order payment method on a per customer basis.
## Enable Purchase Orders for a Customer
To allow a customer to use purchase orders:
1. Go to **Main** > **Customers** > **Customers**.
2. Select the applicable customer account for which you want to enable purchase orders.
3. Under the **Payment Info** section, enable **Purchase Orders**:
The Payment Info section expands to include more Customer Settings.
4. Enter a **Credit Limit** for the customer.\
The credit limit is specific to the purchase order payment method. This is the total monetary credit amount the customer can spend using purchase orders. When a customer pays either a part or the total amount of their purchase order payment, their credit limit increases equal to the amount the customer pays.
5. Specify an **Overdraft Allowance** for the customer.\
The overdraft allowance is how much the customer can spend over their total credit limit. You can specify either a set amount or a percentage of the credit limit.
6. For each of your sites, choose the **Payment Terms** for the customer. The list of payment terms is populated by the complete set of payment terms you filled out when you enabled the purchase order payment type.
For example, you can specify the following settings for a customer:
# Customer Segments
Source: https://docs.kibocommerce.com/pages/customer-segments
Customer segments allow you to group accounts together for special uses, such as marketing initiatives, discounts, or price lists. Segments can be more useful than attributes for creating broad customer classifications.
See how to create and manage customer segments
For example, you want to reward loyal, high-value customers with a free shipping discount on all future orders, and you've determined that all shoppers who spend more than \$1,000.00 lifetime should qualify. You can create a VIP customer segment, add all applicable shoppers to the segment, and create a discount that applies to the segment.
In most cases when using price lists, customer segments also drive the product pricing for which shoppers are applicable. Refer to [Price Lists](/pages/price-lists) for more information.
Customer segments are primarily used by instances of the Kibo Composable Commerce Platform with the Kibo eCommerce solution, rather than Order Management-only implementations.
## Create a Customer Segment
To create a segment:
1. Go to **Main** > **Customers** > **Customer Segments**.
2. Click **Create New Customer Segment**.
3. Enter a **Code**, **Name**, and (Optional) a **Description** that have meaning to you.
For example, you can create the following VIP segment:
## Add Customers to Segments
You can either add multiple customers at a time to a single customer segment, or you can add multiple segments at a time to a single customer account. Refer to the following sections for more information.
### Add Multiple Customers to Single Segment
To add multiple customer accounts to a single segment:
1. Go to **Main** > **Customers** > **Customer Segments**.
2. Expand the actions menu next to the customer segment you want and click **Add Customers**.
3. Select the appropriate customers using the checkboxes:
4. Click **Apply**.
### Add Multiple Segments to Single Customer
To add multiple segments to a single customer account:
1. Go to **Main** > **Customers** > **Customers**.
2. Select the customer account to which you want to add to the segment(s).
3. In the **Customer Segments** section, click **Add**:
4. Select the appropriate segment(s) using the checkboxes:
5. Click **Apply**.
6. In the customer account details page, click **Save**.
# Customer Sets
Source: https://docs.kibocommerce.com/pages/customer-sets
Customer sets allow you to control the specific sites your customers can access using the same login credentials, as well as what customer My Account information is shared between sites. Customer accounts can only belong to one customer set at a time. Refer to [Customer Sets](/pages/structure-customer-sets) for more information.
See how to create and manage customer sets
When either a CSR or a shopper creates a customer account, the customer account is automatically added to the same customer set to which the applicable site belongs. For example, John creates a customer account on your Mystic Sports site. Mystic Sports belongs to the B2C customer set so John's customer account is automatically added to the B2C customer set.
## Assign Customers to Customer Set
You can assign customer accounts to different customer sets if you no longer want them to belong to their current customer set. For example, you reassign several sites to a different customer set, and you don't want the current customers of that customer set to access those newly reassigned sites.
To assign a customer to a customer set:
1. Go to **Main** > **Customers** > **Customers**.
2. Click a customer account.
3. Under **General**, use the **Customer Set** drop-down menu to add the customer to a customer set:
Customers can belong to only one customer set.
# Customers Overview
Source: https://docs.kibocommerce.com/pages/customers-overview
Customer accounts represent the end users of your site(s) who have either registered with your business or purchased from you, or both. A customer account allows you to view and manage a visitor's activity across all sites associated with a tenant, including contact information, purchase history, wish list items, store credit activity, and more.
See how to create new B2C customer accounts through the storefront and admin UI
Learn how to manage B2C customer accounts
The Kibo eCommerce solution uses the full functionality of the customer object, including customer sets and segments as well as managing shopper accounts where customers can log into the storefront. An Order Management-only implementation of the Kibo Composable Commerce Platform does not include these storefront or marketing functions, but still tracks customer data for order management purposes and allows customer records to be viewed and edited.
Refer to the [Customers API documentation](/api-overviews/openapi_customer_overview) for the API requests associated with this feature.
To erase a customer's personal data in response to a right-to-deletion or data subject erasure request under GDPR, CCPA, and other privacy regulations, see the [Redaction Services](/developer-guides/redaction-services "Redaction Services") guide.
## Types of Customer Accounts
There are two types of customer accounts: registered shopper accounts and guest accounts. Both can be created organically by visitors or by administrators during a storefront visit or a Admin session, or by an administrator when importing customer data through the [Kibo Composable Commerce Platform API](/api-overviews/openapi_customer_overview) or using the [Kibo eCommerce Import/Export Tool](/pages/introduction-to-import-export).
* **Registered shopper accounts:** Created through a registration event, with or without a purchase. They feature a username and password as login values. By default, the username is the shopper's email address, but you or the shopper can change this value to any valid character string. Certain account functions are only available to registered shoppers. For example, you can disable accounts for security purposes, or unlock them when a shopper becomes locked out for too many failed login attempts. You can also trigger a password reset email on a shopper's behalf.
* **Guest accounts:** Created when an order is placed without accompanying registration. They feature a unique ID number as the primary identifier. These accounts allow you to keep track of purchasing history for visitors who prefer not to register. A single email address may be used on an unlimited number of guest accounts, but it can only be used on one registered shopper account.
## Customers Page
You can perform the following actions on the customers page at **Main** > **Customers** > **Customers**:
* Search for shopper accounts.
* Sort your shoppers by clicking a column heading.
* View the available steps, such as unlocking or editing, you can apply to an account by expanding the actions menu.
* Click a row to view or edit account details.
### View Additional Customer Fields
Some fields do not display by default. To view additional fields:
1. In the right-hand corner of the customer grid, expand the actions menu (represented by three dots).
2. From the drop-down menu, select the fields that you want to view on the Customers grid.
# Customizing the BPM
Source: https://docs.kibocommerce.com/pages/customizing-the-bpm
You can create a custom BPM by forking the Kibo-Fulfillment-Workflows repository of your codebase and creating a new BPM process. This BPM is then uploaded with assistance from Kibo Professional Services, enabled through API, and executed via the Kibo Fulfiller UI. This allows you to fine-tune your fulfillment methods, such as by:
* Adding custom steps with buttons like proceed, back, and skip.
* Displaying a static message on a custom step.
* Changing the name or look and feel of custom steps.
This documentation uses the jBPM Business Central application for authoring and testing BPM workflows locally. Alternatively, you can use an Integrated Development Environment (IDE) such as Eclipse which is documented at [jbpm.org](https://www.jbpm.org/). Click **Read Documentation** on the jBPM home page and search the referenced document for **Eclipse Developer Tools** to get more details.
Additionally, since custom BPMs are implemented on a separate fork of Kibo’s fulfillment workflows, that means that any future enhancements Kibo may add to the default BPM will not be reflected on the fork. In this case, you will have to code the changes into your version of the forked BPMs in order to add them to the new fulfillment workflows.
## Step 1: Set Up jBPM with Business Central
The jBPM Server distribution is the easiest way to start with jBPM, as the included Business Central application is useful for authoring processes. To get up and running quickly, use the jBPM single distribution which can be downloaded at [jbpm.org](https://www.jbpm.org/). Look at the [Getting Started guide](https://www.jbpm.org/learn/gettingStartedUsingSingleZipDistribution) to get yourself familiar with Business Central.
By default, Business Central is available [here](https://docs.jbpm.org/7.17.0.Final/jbpm-docs/html_single/#_wb.workbench).
## Step 2: Fork the Fulfillment Workflows Repository
Forking the repository is a simple two-step process:
1. On GitHub, navigate to the [Kibo Fulfillment Workflows](https://github.com/KiboSoftware/kibo-fulfillment-workflows) repository.
2. In the top-right corner of the page, click **Fork**.
### Keep Your Fork Synchronized
It's a good practice to regularly synchronize your fork with the upstream repository. To achieve this, you'll need to use Git via the command line by following the below steps:
1. Set Up Git
2. Create a Local Clone of Your Fork
3. Configure Git to Synchronize with the Original Repository
4. Make Changes to the Fork
#### Set Up Git
If you haven't yet, first set up Git. Don't forget to set up authentication to GitHub from Git as well.
#### Create a Local Clone of Your Fork
Right now, you have a fork of the [Kibo Fulfillment Workflows](https://github.com/KiboSoftware/kibo-fulfillment-workflows) repository on GitHub but you don't have the files in that repository on your computer. Let's create a clone of your fork locally on your computer.
1. On GitHub, navigate to your fork of the repository.
2. Under the repository name, click **Code** and then the desired **Clone** or **Download** option.
3. To clone the repository using HTTPS, click the clipboard icon under **Clone with HTTPS**. To clone the repository using an SSH key, including a certificate issued by your organization's SSH certificate authority, click **Use SSH** and then click **Clone URL**.
4. Open Terminal.
5. Type `git clone`, and then paste the URL you copied earlier. It will look like this, with your GitHub username instead of `YOUR_USERNAME`:
```text theme={null}
$ git clone https://github.com/YOUR_USERNAME/YOUR_FORK
```
6. Press **Enter**. Your local clone will be created.
```text theme={null}
$ git clone https://github.com/YOUR_USERNAME/YOUR_FORK
> Cloning into \`YOUR_FORK\`...
> remote: Counting objects: 1033, done.
> remote: Total 1033 (delta 0), reused 0 (delta 0), pack-reused 1033
> Receiving objects: 100% (1033/1033), 1.22 MiB | 173.00 KiB/s, done.
> Resolving deltas: 100% (405/405), done.
```
#### Configure Git to Synchronize with the Original Repository
When you fork a project, you can configure Git to pull changes from the original (or upstream) repository into the local clone of your fork.
1. On GitHub, navigate to the [Kibo Fulfillment Workflows](https://github.com/KiboSoftware/kibo-fulfillment-workflows) repository.
2. Under the repository name, click **Code** and then the desired **Clone** or **Download** option. To clone the repository using HTTPS, click the clipboard icon under **Clone with HTTPS**. To clone the repository using an SSH key, including a certificate issued by your organization's SSH certificate authority, click **Use SSH** and then click **Clone URL**.
3. Open Terminal.
4. Change directories to the location of the fork you cloned in Create a Local Clone of Your Fork.
* To go to your home directory, type just `cd` with no other text.
* To list the files and folders in your current directory, type `ls`.
* To go into one of your listed directories, type `cd your_listed_directory.`
* To go up one directory, type `cd ..`
5. Type `git remote -v`and press **Enter**. You'll see the current configured remote repository for your fork.
```text theme={null}
$ git remote -v
> origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
> origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
```
6. Type `git remote add upstream` , paste the URL you copied, and press **Enter**. It will look like this:
```text theme={null}
$ git remote add upstream https://github.kibocommerce.com/KiboSoftware/kibo-fulfillment-workflows.git
```
7. To verify the new upstream repository you've specified for your fork, type `git remote -v` again. You should see the URL for your fork as origin, and the URL for the original [Kibo Fulfillment Workflows](https://github.com/KiboSoftware/kibo-fulfillment-workflows) repository as upstream.
```text theme={null}
$ git remote -v
> origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
> origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
> upstream https://github.kibocommerce.com/KiboSoftware/kibo-fulfillment-workflows
(fetch)
> upstream https://github.kibocommerce.com/KiboSoftware/kibo-fulfillment-workflows
(push)
```
#### Make Changes to the Fork
You have the flexibility to make various changes to your fork, which includes creating and opening branches. You will have to synchronize your custom fork with the upstream repository as well as with your jBPM Business Central repository.
* **Creating Branches:** Branches allow you to build new features or test out ideas without putting your main project at risk.
* **Opening Pull Requests:** If you are hoping to propose a change to the original repository, you can send a request to Kibo to pull your fork into their repository by submitting a pull request.
## Step 3: Modify Forked Repository Files
To update your pom.xml file:
1. Modify **pom.xml** by changing the following elements to match your project requirements:
```text theme={null}
YOUR_DEVCENTER_ACCOUNT_KEY
YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME
1.0.0-SNAPSHOT
kjar
YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME
```
2. Commit changes to your local copy of the forked repository.
```text theme={null}
$ git add pom.xml
$ git commit -m "Provide a meaningful commit message here"
$ git push origin develop
```
## Step 4: Import Assets into Business Central
You can easily import the forked business assets project into Business Central, as it's a valid Git repository:
1. Create a git branch named **master** from the default **develop** branch.
```text theme={null}
$ git checkout -b master
Switched to a new branch 'master'
---
$ git branch
develop
* master
```
The assumption here is that there's no existing `master` branch in your forked repository. The name `master` is used to align with the default branch name used by the development jBPM instance.
2. Log in to Business Central and go to **Menu** > **Design** > **Projects**.
3. Select `Import Project` from the Add Project menu and enter the filesystem location of the project git repository within the `Repository URL` field. For example:
```text theme={null}
file://{filesystem location of forked repository}
```
4. Click **Import**, confirm the project to be imported, and click **Ok.** Note that if attempting upload within a Docker container, a volume must be mapped.
5. Once the business assets project is successfully imported into Business Central, you can begin working on it. Navigate to the project and make additions or modifications to assets such as business processes, forms, rules, decision tables, and more.
## Optional: Pick Wave Requirement
If you intend to use this custom fulfillment workflow for pick waves, then it must have a "picked" signal component in order for shipment progression to follow your routing logic upon closing a pick wave. This is required for compatibility with the [Close Pick Wave API](/api-reference/pickwave/close-pick-wave).
1. Include the Picked Signal
* Ensure your BPMN workflow includes a signal event named "picked."
2. Enable Triggering via API
* Position the signal so it can be triggered when the fulfillment service calls the Pick Wave Close API.
3. Route to the Next Task
* Once triggered, the workflow must route to the appropriate user task or fulfillment step—either an existing or a custom task—based on the custom signal route.
4. Ensure Proper Workflow Progression
* This signal-driven routing allows shipments associated with the pick wave to continue progressing through the workflow as intended.
## Step 5: Pull Custom Assets to the Fork
Updated business assets need to be pulled back to the forked project source code repository:
1. Go to Settings of the project within Business Central.
2. Copy the **URL** value from the **General Settings** view.
3. Go to the filesystem location of the forked and imported repository.
4. Type `git remote -v` and press **Enter**. You'll see the current configured remote repositories.
5. Type `git remote add jbpm`, and then paste the URL you copied in Step 2. Modify the value to include `wbadmin@` and press **Enter**. It will look like this:
```text theme={null}
$ git remote add jbpm ssh://wbadmin@localhost:8001/MySpace/YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME
```
6. To verify the new **jbpm** repository you've specified for your fork, type `git remote -v` again. You should see the URL for the jBPM Business Central project as **jbpm**, the URL for your fork as **origin**, and the URL for the original repository as **upstream**.
```text theme={null}
$ git remote -v
> jbpm ssh://wbadmin@localhost:8001/MySpace/YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME (fetch)
> jbpm ssh://wbadmin@localhost:8001/MySpace/YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME (push)
> origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
> origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
> upstream https://github.com/KiboSoftware/kibo-fulfillment-workflows.git (fetch)
> upstream https://github.com/KiboSoftware/kibo-fulfillment-workflows.git (push)
```
7. Pull or fetch your custom business assets from jBPM Business Central to your forked git repository.
```text theme={null}
$ git checkout master
$ git pull jbpm master - when prompted enter wbadmin as password
```
or
```text theme={null}
$ git checkout master
$ git fetch jbpm
$ git rebase jbpm/master
```
If you encounter issues connecting to the jBPM generated Git repository over SSH, you can change the protocol to **http** within the same Business Central **Settings** view for your project.
8. Synchronize the **develop** branch of your fork with the **origin** repository on GitHub.
```text theme={null}
$ git checkout develop
$ git pull origin develop
```
9. Rebase your updated local **master** branch commits on the synchronized **develop** branch.
```text theme={null}
$ git checkout master
$ git rebase develop
```
10. Squash all dedicated jBPM Business Central changes in the **develop** branch of your fork.
```text theme={null}
$ git checkout develop
$ git merge --squash master
```
11. Add & commit the merged changes to the **develop** branch and then push to your fork on GitHub.
```text theme={null}
$ git add -A
$ git commit -m "some useful comment"
$ git push origin develop
```
12. Reset the jBPM Business Central **master** branch using the updated **develop** branch.
```text theme={null}
$ git checkout master
$ git reset --hard develop
$ git push -f jbpm master
```
13. With your custom business assets now part of the forked project source tree, Maven commands can be used to build and publish the KJAR artifact to a Maven repository without using the standalone jBPM server.
```text theme={null}
$ mvn clean install
```
## Step 6: Deploy Custom Assets to KIE Server
After adding assets to your project in Business Central, you can easily deploy it to a running KIE server instance:
1. Navigate to your project and click **Deploy**.
2. After a few seconds, you should see the project successfully deployed.
## Step 7: Interact with Deployed Assets
You can use **Process Definitions** and **Process Instances** perspectives of Business Central to interact with your newly deployed business assets, such as processes or user tasks.
## Step 8: Install Custom Workflows
Provide Kibo Professional Services with your repository. They will verify and upload your workflows, as well as provide any further instructions needed to modify or install your BPMs.
## Step 9: Enable Workflows for Location Groups
Update your location group configuration settings to use customized processes, referencing the new containerId(s) and processId(s) by shipmentType. Some example cURL requests are listed below.
Get all location groups for a tenant and site:
```text theme={null}
curl --request GET 'http://t123.mozu.com/api/commerce/admin/locationGroups' \\
--header 'x-vol-tenant: 123' \\
--header 'x-vol-site: 456' \\
--header 'Authorization: Bearer *******'
```
Get configuration for a specific location group:
```text theme={null}
curl --request GET 'http://t123.mozu.com/api/commerce/admin/locationGroupConfiguration/2' \\
--header 'x-vol-tenant: 123' \\
--header 'x-vol-site: 456' \\
--header 'Authorization: Bearer *******'
```
Set a custom BPM configuration for a location group:
```text theme={null}
curl --request PUT 'http://t123.mozu.com/api/commerce/admin/locationGroupConfiguration/2' \\
--header 'x-vol-tenant: 123' \\
--header 'x-vol-site: 456' \\
--header 'Authorization: Bearer *******' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"tenantId": 123,
"siteId": 456,
"locationGroupId": 2,
"locationGroupCode": "2",
...
"bpmConfigurations": [
{
"shipmentType": "BOPIS",
"workflowContainerId": "YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME",
"workflowProcessId": "fulfillment.FulfillmentProcess-BOPIS"
},
{
"shipmentType": "STH",
"workflowContainerId": "YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME",
"workflowProcessId": "fulfillment.FulfillmentProcess-STH"
},
{
"shipmentType": "Transfer",
"workflowContainerId": "YOUR_DEVCENTER_ACCOUNT_KEY.YOUR_DEVCENTER_APP_NAME",
"workflowProcessId": "fulfillment.FulfillmentProcess-Transfer"
}
],
...
}'
```
## Step 10: Execute Custom Workflows in Fulfiller UI
To execute custom workflows as a fulfiller user, such as for testing the new workflow:
1. Log in to the Admin UI and select the appropriate tenant.
2. Create a new order and shipment type matching the custom workflow configuration.
3. Go to **Main** > **Fulfiller** and locate the corresponding shipment.
4. Proceed through the workflow tasks for the shipment and confirm functionality.
## Step 11: Sync Custom Fork with Upstream Repository
To sync your custom forked repository with the upstream repository:
1. Open Terminal.
2. Change the current working directory to your local project.
3. Fetch the branches and their respective commits from the upstream repository. Commits to develop will be stored in a local branch, `upstream/develop`.
```text theme={null}
$ git fetch upstream
> remote: Counting objects: 8, done.
> remote: Compressing objects: 100% (8/8), done.
> remote: Total 8 (delta 3), reused 0 (delta 0), pack-reused 0
> Unpacking objects: 100% (8/8), done.
> From https://github.com/KiboSoftware/kibo-fulfillment-workflows
> * [new branch] develop -> upstream/develop
```
4. Check out your fork's local `develop` branch.
```text theme={null}
$ git checkout develop
> Switched to branch 'develop'
```
5. Merge the changes from `upstream/develop` into your local `develop` branch. This brings your fork's `develop` branch into sync with the upstream repository, without losing your local changes.
```text theme={null}
$ git merge upstream/develop
> Merge made by the 'recursive' strategy.
```
6. If your local branch didn't have any unique commits, Git will instead perform a "fast-forward":
```text theme={null}
$ git merge upstream/develop
> Updating 34e91da..16c56ad
> Fast-forward
> README.md | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
```
Syncing your fork updates only your local copy of the repository. To update your fork on GitHub, you must push your changes. For more information about syncing a fork, see [the GitHub documentation](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork).
## **Configuring Workflow Step Behaviors**
Once your custom BPM is deployed and executing in the Fulfiller UI, you can configure additional on-complete behaviors for any workflow step — including custom steps you have defined in your BPM and out-of-the-box steps. These behaviors are configured in your Fulfiller theme's language file, not in the BPM process itself, and require no changes to your KJAR or BPM authoring.
The following behaviors are available per step:
* **Instructions pop-up** — a configurable modal dialog displayed when the user clicks **Continue** on the step
* **Dashboard redirect** — returns the user to the shipments dashboard after step completion
* **Email notification** — triggers an outbound email using a specified template and recipient audience
For full configuration details, see [Fulfiller Theme Customization — Workflow Step On-Complete Behaviors](/pages/fulfiller-theme-customization#workflow-step-on-complete-behaviors).
# CyberSource Decision Manager Application
Source: https://docs.kibocommerce.com/pages/cybersource-decision-manager-application
![CyberSource logo]() |
| Platforms: Legacy eCommerce, KCCP eCommerce and eCommerce+OMS |
Looking for Cybersource Payment Gateway? See the [Payment Gateways documentation](/pages/payment-gateways).
Cybersource's [Decision Manager](http://www.cybersource.com/products/fraud_management/decision_manager/) provides a fraud protection platform that features the World's Largest Fraud Detection Radar as well as a flexible rules engine that lets you customize rules to suit your business case. With Decision Manager, you can screen orders for risk in an effort to prevent fraud.
The Cybersource Decision Manager application integrates your Decision Manager account with your Kibo site so that orders you receive on your site are automatically screened by Decision Manager. Orders receive a fraud score and a validation result from Decision Manager that eCommerce uses to either accept, reject, or flag an order for further review.
### Application Features
* Automatically sends information about submitted orders to Decision Manager, including the shopper's browser type, IP address, device type, billing information, etc.
* Validates orders against your Decision Manager rules to determine a fraud score and validation result.
* Updates order status in eCommerce to Accepted, Pending Review, or Cancelled based on Decision Manager validation results.
* Syncs order status information with Decision Manager at scheduled intervals.
* Avoids excessive overhead for low-value orders by allowing you to set a monetary threshold below which orders *are not* screened for fraud.
* Maps eCommerce data to Decision Manager to facilitate the creation of fraud detection rules based on fields such as a shopper's email address or payment type.
* Complete a combined authorization and fraud validation check in one call from eCommerce to Decision Manager. In this scenario, if you capture a partial payment, Kibo will send the authorization and fraud validation check to Decision Manager. At this stage, the Decision Manager Application status is Review and the Kibo order status is Pending Review. Then, if you capture more of the payment with the same credit card, Kibo will NOT resend the fraud validation check to Decision Manager. For subsequent payment captures on the order, the Kibo status is Processing and the DM status is Accepted. This functionality requires set up on your tenant. Submit a [Kibo Support](https://help.kibocommerce.com/) ticket to request this functionality.
## Install the Application
As of Version 3.0.0, the application is integrated with CyberSource's REST APIs. Previous versions utilized SOAP APIs with different authentication keys, which is now being deprecated by CyberSource. You can [self-install Version 3.0.0 here](https://developer.mozu.com/console/marketplace/mzint.decisionmanager.3.0.0). If the link redirects you to the launchpad, select any developer account and it will take you to the Marketplace where you can select your tenant.
For assistance, please reach out to your SI partner or Kibo's professional services and enablement team.
## Configure Decision Manager
To begin setting up Decision Manager in Kibo, ensure that you have the following requirements:
* The Cybersource Decision Manager application must be installed on your tenant.
* You must have an active Decision Manager account
Then, continue with the following sections to configure the application:
1. [Obtain Decision Manager Account Information](#obtain-decision-manager-account-information)
2. [Provide Applications Credentials](#provide-application-credentials)
3. [Configure Fraud Detection and Order Synch](#configure-fraud-detection-and-order-synch)
4. [Map Kibo eCommerce Fields to Custom Fraud Detection Rules](#create-custom-rules)
5. [Enable the Application](#enable-the-application)
### Obtain Decision Manager Account Information
Note your Decision Manager account credentials. You will enter these credentials in eCommerce.
1. Log in to [Cybersource](https://ebc.cybersource.com/ebc2/). Note the Account ID and Merchant ID in the top banner of the dashboard; this is the Merchant ID that will soon be used for the gateway in KCCP.
2. Generate a REST API Key and Shared Secret according to [Cybersource's instructions](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-http-message-intro/restgs-security-key-pair-intro).
* If you have already generated these credentials while setting up a [payment gateway](/pages/payment-gateways "Payment Gateways"), you can reuse them for Decision Manager.
### Provide Application Credentials
1. In Admin, go to **System** > **Customization** > **Applications**.
2. Click **Cybersource Decision Manager 3.0.0**.
3. Click **Configure Application**.
4. Go to the **Settings** tab.
5. Enter your **Merchant Id**, **API Key**, and **API Shared Secret**.
6. Continue with the other configurations detailed below before clicking **Save**.
### Configure Fraud Detection and Order Synch
In the Settings tab of the Configure Application modal, set the following options as needed to configure your fraud detection and order synchronization.
| Setting | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Threshold Enabled** | (Optional) Sets a monetary value below which orders are not sent to Decision Manager. You can use this setting to optimize performance for customers making low-value orders that do not carry significant fraud risk. The **Threshold Value** only applies to the largest payment that is an enabled payment type (7) for fraud validation. |
| **Cancel Order When Rejected in DM** | (Optional) Specifies to automatically cancel orders in Kibo that are rejected by Decision Manager. If not enabled, orders rejected by Decision Manager are set to Pending Review. Cancelled orders cannot be reverted to a non-cancelled state. |
| **Export Order Item Price as 0.00** | (Optional) Specifies to export orders to Decision Manager with the price for individual line items set to 0.00. Selecting this option will make the total amount of the order 0.00 in Decision Manager. If you want to zero out line items but still see the full order amount in Decision Manager, you can add the **Order Total** as a [custom mapping](#create-custom-mappings-from-kibo-ecommerce). |
| **Select Payment Type** | Specifies the payment types to check for fraud in Decision Manager. Kibo sends ONLY the payment types you select to Decision Manager. If you select multiple payment types, Kibo sends only the *largest* selected payment type applied to a given order to Decision Manager for screening. Note that PayPal Express is only supported for the legacy version of Kibo eCommerce PayPal, implemented through Kibo eCommerce Core 8 and earlier. If you are implementing PayPal support through the PayPal Express Certified Kibo eCommerce Application, Decision Manager does not check PayPal payments for potential fraud. Cybersource's current tooling requires a billing address with every order. PayPal Express obscures billing information for security reasons, so Kibo cannot provide it to Cybersource. |
| **Environment** | Specifies the Decision Manager environment to use for fraud checking. If you select **Test**, the application sends order information to Decision Manager's test site, where you can evaluate fraud detection rules in a sandbox setting. When you are satisfied with the rules you set in Decision Manager, choose **Production** to enable live fraud detection on your site. |
| **Order Synch Frequency** | (Optional) Specifies how often Kibo queries Decision Manager for updates on orders. If you accept or reject an order in Decision Manager that is Pending Review in Kibo eCommerce, the order synch frequency determines how long it takes for the order status to update in Kibo eCommerce. If this option is **Disabled**, Kibo does not query Decision Manager, and you must manually process the order in Kibo eCommerce. |
### Create Custom Rules
If you want to add to the rules that Decision Manager uses to screen an order for fraud risk, you can use the Cybersource Business Center to modify the existing rules or create new custom rules. To help you build custom rules, you can map eCommerce fields, such as email address and payment types, to available merchant-defined data (MDD) fields in Decision Manager. Afterwards, you can associate the MDD fields with custom fields in Decision Manager and use the custom fields in your fraud detection rules.
At least one rule must exist in order for the transaction to go through the Decision Manager. To create custom mappings:
1. Open the Decision Manager app configuration settings dialog.
2. Go to the **Custom Mapping** tab.
This tab only appears after you configure and save your account information on the **Settings** tab.
3. Select the **Merchant ID** for the Cybersource account you are mapping.
4. Click **Add Custom Mapping** and fill in the following fields.
* **Merchant ID**: The Decision Manager Merchant ID you selected on the previous page.
* **Domain**: The type of eCommerce data you are mapping. The value you choose determines the options that appear in the Mozu Data menu.
* **Mozu Data**: The specific order or customer data field from eCommerce. Once a field is mapped, it no longer appears in the list.
* **Cybersource Data**: The Decision Manager merchant-defined data field to which you are mapping the Mozu Data. Only available fields appear in the list.
* **Include in Offer Details**: Specifies whether to include the custom mapping as a column in the Decision Manager Offer Details table.
* **Offer Detail Value Column**: Specifies which column in the Decision Manager Offer Details table displays the mapped data. If you select Price, the mapped data must be a decimal. SKU can display any data type.
After you create mappings in Kibo, you must log in to Decision Manager account and associate a custom field with a mapped merchant-defined data field. Creating this association is necessary because fraud detection rules don't access merchant-defined data fields directly.
For example, if you create a mapping in eCommerce that assigns a customer's email address to Merchant-Defined Data 7, complete the following steps to create the custom field in Decision Manager:
1. Log in to the [Cybersource Business Center](https://ebc.cybersource.com/ebc/login/Login.do).
2. Go to **Decision Manager** > **Configuration** > **Custom Fields**.
3. Click **Add Custom Field**.
4. Select **merchant\_defined\_data7** as the **Order Element** and give the field a logical name, such as **Email**.
5. Click **Save** to create the field.
You can now go to **Configuration** > **Custom Rules** to create a new rule. In the **Rule Conditions**, your custom fields appear in the **Order Element** drop-down. For more information on creating custom rules and fields in Decision Manager, refer to the *Decision Manager User Guide* available through the Cybersource Business Center.
## Enable the Application
If you were previously using Version 2.0.0 of the Decision Manager application, you must disable it before enabling the new one:
1. Go to **System** > **Customization** > **Applications**.
2. Click **Cybersource Decision Manager 2.0.0**.
3. Toggle off **Enable Application**.
4. Ensure that all Order [events](/pages/event-subscription "Event Subscription") are disabled for this application.
To enable the new application:
1. Go to **System** > **Customization** > **Applications**.
2. Click **Cybersource Decision Manager 3.0.0**.
3. Toggle on **Enable Application**.
4. Ensure that all [events](/pages/event-subscription "Event Subscription") are enabled for this application.
5. Install [this Dev Center application](https://developer.mozu.com/console/marketplace/mzint.dmarc.2.0.0). If the link redirects you to the launchpad, select any developer account and it will take you to the Marketplace where you can select your tenant.
6. Go to **System** > **Customization** > **API Extensions** and update the [Payment Action (Before) API Extension](/pages/action-before "Action (Before)") to reference the new application key, if it wasn't automatically updated. See [Getting Started with API Extensions](/pages/getting-started-with-api-extensions#6-enable-the-action "Getting Started with API Extensions") for more details.
```
{
"actionId": "embedded.commerce.payments.action.before",
"contexts": [
{
"customFunctions": [
{
"applicationKey": "mzint.dmarc.2.0.0.Release",
"functionId": "embedded.commerce.payments.action.before",
"enabled": true
}
]
}
]
}
```
* If you are using a custom implementation of the Decision Manager API Extension and migrating from SOAP to REST versions of Cybersource, modify the following lines by removing those marked with `-` and adding the `+` lines. If you are setting up a new instance, your code should already contain the correct lines.
```
function getSettings(context) {
- var entityListFullName = 'mozu-decisionmanager-tenantsettings@' + getDevAccountNS(context);
+ var entityListFullName = 'mozu-decisionmanager3-tenantsettings@' + getDevAccountNS(context);
...
function getMerchantCustomFieldMap(merchantId, context) {
- var entityListFullName = 'merchant_custom_field_map@' + getDevAccountNS(context);
+ var entityListFullName = 'dm3_merchant_custom_field_map@' + getDevAccountNS(context);
...
- console.log('no mozu-decisionmanager-tenantsettings found ');
+ console.log('no mozu-decisionmanager3-tenantsettings found ');
...
- console.log('settings mozu-decisionmanager-tenantsettings has no merchantId ');Add commentMore actions
+ console.log('settings mozu-decisionmanager3-tenantsettings has no merchantId ');
```
7. Log into Cybersource and go to **Decision Manager** > **Configuration** > **Extended Settings** and update the Notification URL to the appropriate CSDM3 address (where `{tenant}` may be `tp1`, `tp2`, `tp3`, or so forth depending on your environment).
* Sandbox: `https://integrations2-sb.mozu.com/CSDM3/listener/`
* Production: `https://integrations2-{tenant}.mozu.com/CSDM3/listener/`\\
## Add the Decision Manager Widget to Your Theme
For each fraud screen it performs, Decision Manager requires a device fingerprint that helps identify the computer or device from which an order originates. You must add the Decision Manager Widget, available on [GitHub](https://github.com/Mozu/Integration-DecisionManagerWidget), to the checkout page of your eCommerce site(s) to capture each customer's device fingerprint and send it to Decision Manager.
The [Mozu/Integration-DecisionManagerWidget](https://github.com/Mozu/Integration-DecisionManagerWidget) repository is private. Contact [Kibo Support](https://help.kibocommerce.com/) with your GitHub username to request access to this repo.
### Update Your Theme
1. Clone or download the [GitHub repository](https://github.com/Mozu/Integration-DecisionManagerWidget).
2. Add or merge the files listed above.
3. Run Grunt to build the theme.
4. Upload the resulting ZIP file to Dev Center.
5. Install the updated theme to the sandbox you’re working in.
6. In Admin, go to **Main** > **Content** > **Themes**, right-click the new theme, and click **Apply**.
### Add the Widget to Your Checkout Page
You can only perform this step if you are using a Kibo site.
1. In Admin, go to **Content** > **Editor**.
2. In the Site tree, navigate to **Templates** > **Checkout**.
3. Click **Widgets** at the top of the editor.
4. Drag the **DecisionManager Device Fingerprint** widget to any dropzone on the checkout page. The widget is not visible to customers, so placement on the page is not important.
## Use the App
Once you have installed, configured, and enabled the Cybersource Decision Manager Application, the app automatically begins sending eCommerce orders to Decision Manager for fraud detection. The amount of work you must do to process orders depends on your app configuration. For example, in the most streamlined scenario (you enabled both an **Order Synch Frequency** and **Cancel Order When Rejected in DM**), you only have to process orders in Decision Manager.
Refer to the [Application Logic](#application-logic) section at the end of this document for a diagram of the order status change process.
When an order is sent to Decision Manager, the status of the order in Kibo changes to `Pending Review`. Decision Manager screens the order and attaches one of the following validation results: accept, review, or reject. If the validation result is review, further action is required in Decision Manager to either accept or reject the order.
### Process Orders in Decision Manager
In Decision Manager, Kibo orders appear with their Kibo order number as the Merchant Reference Number. This makes it easy for users to locate the order in Decision Manager:
1. Log in to Decision Manager and navigate to **Case Management** > **Case Search** in the left navigation menu.
2. Use the **Search Parameters** to locate the order(S) that need processing. If you know the order number, you can search for it explicitly using the **Field and value** search.
3. (Optional) If your search returns multiple results, click the order number in the **Results** table to view the Case Management Details.
4. Review the order. Note that the Case Management Details list the order number as the **Merchant Ref Number**.
5. Process the order in Decision Manager as you normally would.
### Process Orders in Kibo eCommerce
#### Automatic Order Processing
All orders are set to `Pending Review` when they are sent to Decision Manager. If you [configured order synching](#optional-configure-order-synching), the Decision Manager App automatically updates the order status after a Decision Manager result is received.
Additionally, if the order was manually reviewed in Decision Manager, the reviewer name and comments from Decision Manager appear in the Orders module in Admin, on the **Order Details** tab:
If you *did not* set up order synching, you must [manually process the order in eCommerce](#manual-order-processing) to change its status.
The basic status mapping for auto updates is as follows:
| Decision Manager Validation Result | Kibo Order Status |
| ---------------------------------- | ----------------- |
| accept | Accepted |
| review | Pending Review |
| reject | Cancelled1 |
1 If you enabled **Cancel Order When Rejected in DM** in the app Configuration settings, an order that is rejected in Decision Manager is automatically moved to Cancelled in Kibo. If you *did not* enable **Cancel Order When Rejected in DM**, an order that is rejected in Decision Manager remains in Pending Review until you manually change the order status.
These status mappings apply regardless of whether the state change in Decision Manager is triggered manually by a fraud reviewer or automatically by a rule.
Refer to the [Application Logic](#application-logic) section at the end of this document for a diagram how order status is mapped from Decision Manager to Kibo.
#### Manual Order Processing
If you *did not* enable order synching, all orders sent to Decision Manager remain in `Pending Review` until you manually process them in Admin:
1. In Admin, go to **Main** > **Fulfillment** > **Orders**.
2. Locate the order and click the row to open the Orders editor.
3. On the **Order Details** tab, locate **Attributes**.
4. Use the **Decision Manager Fraud Results** to review the reasons the order is pending review.
1. Note whether Decision Manager accepted, rejected, or marked the order for further review.
2. Consider fraud risk information such as the fraud score result (**afsResult**), risk factor codes (**afsFactorCode**), and reason code (**ReasonCode**). For example, in the preceding screenshot, you can determine that Decision Manager rejected the order due to a fraud score result that may be above your ignore threshold based on risk factor codes that include phone inconsistencies and high account usage.
For help interpreting all the values listed in the Decision Manager results, refer to the *Decision Manager Developer Guide: Using the Simple Order API* available through the Cybersource Business Center.
5. If you think the order is fraudulent, click **Cancel Order**. Otherwise, click **Accept Order**.
You can also use the Decision Manager website to accept or cancel orders pending review. If you update an order through the Decision Manager website, you see the update in Kibo in accordance with the order synchronization interval you set in the configuration settings.
## Application Logic
This section provides decision trees to help illustrate how the Cybersource Decision Manager Application makes two key decisions:
* Whether send an order to Decision Manager for fraud detection.
* How to change the status of a Kibo order based on the fraud detection results.
The branches in each diagram depend on how you configure the app. Review the [App Configuration Settings](#open-the-app-configuration-settings) for additional context.
### Perform Fraud Detection?
**Figure 1:**
Process for determining whether to send an order to Decision Manager for fraud detection.
### Update Order Status?
**Figure 2:** Process for determining whether to update Kibo order status based on Decision Manager fraud result.
# Order Item Details Dashboard
Source: https://docs.kibocommerce.com/pages/dashboards-order-detail-dashboard
The Order Item Details dashboard provides detailed information about the order items purchased on the site. It can be viewed under the order topic at **Kibo Standard Reports** > **Order** > **Order Item Details Dashboard** in the navigation menu.
The supported filters that can be applied to this dashboard are:
| Name | Description | Default |
| ----------------------- | ----------------------------------------------------------------------------------- | ------------- |
| Site | Restrict results to one or more of your sites. | All |
| Order Created Date | Limit results to only orders created within this time range. | Past one days |
| Order Status | The status of the order such as Completed, Submitted, or Cancelled. | All |
| Item Fulfillment Status | The status of the order item such as Fulfilled, NotFulfilled or PartiallyFulfilled. | All |
There are no special measures that are calculated by this dashboard.
The tiles that make up this dashboard include:
| Name | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Order Item Details | Table providing the following dimensions for each Order Item: Order Created Date (Sort Descending), Order Number, Order Status, Item Fulfillment Status, Product Code, Product Variant Code, Product Name, Quantity, and Item Total. |
# Deferred Sales Dashboard
Source: https://docs.kibocommerce.com/pages/deferred-sales-dashboard
The Deferred Sales dashboard lists orders where payment has been collected but the order is not yet completed. This can be viewed under the payments topic at **Kibo Standard Reports** > **Payments** > **Deferred Sales Dashboard**.
The supported filters that can be applied to this dashboard are:
| Name | Description | Default |
| ------------------ | ------------------------------------------------------------ | ------------ |
| Site | Restrict results to one or more of your sites. | All |
| Order Created Date | Limit results to only orders created within this time range. | Past one day |
There are no special measures calculated by this dashboard.
The tiles that make up this dashboard are:
| Name | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Deferred Sales | The order created date, order number, order status, order total, amount requested, and and amount collected for valid orders where the order status is not completed and an order payment has a payment status of paid or collected. |
# Delete Cart (After)
Source: https://docs.kibocommerce.com/pages/delete-cart-after
**Related API:** This extension modifies the [Delete Cart](/api-reference/cart/delete-cart) operation.
This action occurs after the cart is deleted. Changes made to the cart or cart items in this action do not persist in Kibo eCommerce.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.carts.deleteCart.after |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: Cart
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that deletes a cart.
## Get
### get.cart
Obtains a response that includes information about the current cart.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cart();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setData
Sets custom key/value data on the current cart.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| key | string | Key of the data to set on the cart. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the specified cart.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from the cart. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------- |
| key | string | Key of the data to set on the cart item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the cart item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the cart item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from a cart item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemAllocation
Sets soft allocation information on a cart item.
| Parameter | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the cart item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for a cart item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItem
Removes an item from the cart.
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| itemId | string | Id of the item to remove. |
Example:
```
context.exec.removeItem("123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Cart (Before)
Source: https://docs.kibocommerce.com/pages/delete-cart-before
**Related API:** This extension modifies the [Delete Cart](/api-reference/cart/delete-cart) operation.
This action occurs before the cart is deleted. Changes made to the cart or cart items in this action do not persist in Kibo eCommerce.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.carts.deleteCart.before |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: Cart
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**\
This action corresponds to the microservice that deletes a cart.
## Get
### get.cart
Obtains a response that includes information about the current cart.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cart();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setData
Sets custom key/value data on the current cart.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| key | string | Key of the data to set on the cart. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the specified cart.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from the cart. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------- |
| key | string | Key of the data to set on the cart item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the cart item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the cart item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from a cart item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemAllocation
Sets soft allocation information on a cart item.
| Parameter | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the cart item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for a cart item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItem
Removes an item from the cart.
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| itemId | string | Id of the item to remove. |
Example:
```
context.exec.removeItem("123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Item (After)
Source: https://docs.kibocommerce.com/pages/delete-item-after
**Related API:** This extension modifies the [Delete Cart Item](/api-reference/cart/delete-cart-item) operation.
This action occurs after an item is deleted from the cart. Changes made to the cart or cart items in this action do not persist in Kibo eCommerce.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.carts.deleteItem.after |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: Cart Item
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**
This action corresponds to the microservice that updates an item in a cart.
## Get
### get.cart
Obtains a response that includes information about the current cart.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cart();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### get.cartItem
Obtains a response that includes information about the current cart item. Only available for actions specific to cart items.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cartItem();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setData
Sets custom key/value data on the current cart.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| key | string | Key of the data to set on the cart. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the specified cart.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from the cart. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------- |
| key | string | Key of the data to set on the cart item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the cart item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the cart item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from a cart item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemAllocation
Sets soft allocation information on a cart item.
| Parameter | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the cart item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for a cart item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItem
Removes an item from the cart.
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| itemId | string | Id of the item to remove. |
Example:
```
context.exec.removeItem("123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Item (Before)
Source: https://docs.kibocommerce.com/pages/delete-item-before
**Related API:** This extension modifies the [Delete Cart Item](/api-reference/cart/delete-cart-item) operation.
This action occurs before an item is deleted from the cart. Changes made to the cart or cart items in this action do not persist in Kibo eCommerce.
| Action Type | [Embedded](/pages/types-of-actions) |
|---|
| Full Action ID | embedded.commerce.carts.deleteItem.before |
|---|
| Runs multiple custom functions? | No |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: Cart Item
The methods and objects documented here are available to this action through the use of the `context` argument.
**Microservice Operation**
This action corresponds to the microservice that updates an item in a cart.
## Get
### get.cart
Obtains a response that includes information about the current cart.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cart();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### get.cartItem
Obtains a response that includes information about the current cart item. Only available for actions specific to cart items.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.cartItem();
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Exec
### exec.setData
Sets custom key/value data on the current cart.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| key | string | Key of the data to set on the cart. |
| value | object | Value of the data to set. |
Example:
```
context.exec.setData("customField", value);
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeData
Removes custom key/value data from the specified cart.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| key | string | Key of the data to remove from the cart. |
Example:
```
context.exec.removeData("customField");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemData
Sets custom key/value data on a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------- |
| key | string | Key of the data to set on the cart item. |
| value | object | Value of the data to set. |
| itemId | string | Id of the cart item to which the data is applied. |
Example:
```
context.exec.setItemData("customField", value, "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItemData
Removes custom key/value data from a cart item.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Key of the data to remove from the cart item. |
| itemId | string | Id of the item from which to remove data if applied to a line item that is not the current line item. Current line item only applies when called from a cart item action. |
Example:
```
context.exec.removeItemData("customField", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.setItemAllocation
Sets soft allocation information on a cart item.
| Parameter | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allocationId | int | Id of the allocation to set on the cart item. |
| expiration | date/time | Date/time of the allocation expiration. |
| productCode | string | Code of the product or product variation that is allocated. |
| itemId | string | Id of the item to set the allocation on if applied to a line item that is not the current line item. Current line item only applies when called for a cart item action. |
Example:
```
context.exec.setItemAllocation(5, dateVariable, "LUC-SAMPLE-PROD", "123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
### exec.removeItem
Removes an item from the cart.
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| itemId | string | Id of the item to remove. |
Example:
```
context.exec.removeItem("123");
```
Response:
```
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"changeMessages": [
{
"amount": "decimal",
"appId": "string",
"appKey": "string",
"appName": "string",
"correlationId": "string",
"createDate": "DateTime",
"id": "string",
"identifier": "string",
"message": "string",
"metadata": "object",
"newValue": "string",
"oldValue": "string",
"subject": "string",
"subjectType": "string",
"success": "bool",
"userFirstName": "string",
"userId": "string",
"userLastName": "string",
"userScopeType": "string",
"verb": "string"
}
],
"channelCode": "string",
"couponCodes": "string",
"currencyCode": "string",
"customerInteractionType": "string",
"data": "string",
"discountedSubtotal": "decimal",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"expirationDate": "DateTime",
"extendedProperties": [
{
"key": "string",
"value": "string"
}
],
"feeTotal": "decimal",
"fulfillmentInfo": {
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"fulfillmentContact": {
"address": {
"address1": "string",
"address2": "string",
"address3": "string",
"address4": "string",
"addressType": "string",
"cityOrTown": "string",
"countryCode": "string",
"isValidated": "bool",
"postalOrZipCode": "string",
"stateOrProvince": "string"
},
"companyOrOrganization": "string",
"email": "string",
"firstName": "string",
"id": "int",
"lastNameOrSurname": "string",
"middleNameOrInitial": "string",
"phoneNumbers": {
"home": "string",
"mobile": "string",
"work": "string"
}
},
"isDestinationCommercial": "bool",
"shippingMethodCode": "string",
"shippingMethodName": "string"
},
"handlingTaxTotal": "decimal",
"id": "string",
"invalidCoupons": [
{
"couponCode": "string",
"createDate": "DateTime",
"discountId": "int",
"reason": "string",
"reasonCode": "int"
}
],
"items": [
{
"auditInfo": {
"createBy": "string",
"createDate": "DateTime",
"updateBy": "string",
"updateDate": "DateTime"
},
"data": "string",
"discountedTotal": "decimal",
"discountTotal": "decimal",
"extendedTotal": "decimal",
"feeTotal": "decimal",
"fulfillmentLocationCode": "string",
"fulfillmentMethod": "string",
"handlingAmount": "decimal",
"id": "string",
"isRecurring": "bool",
"isTaxable": "bool",
"itemTaxTotal": "decimal",
"lineId": "int",
"localeCode": "string",
"product": {
"allocationExpiration": "DateTime",
"allocationId": "int",
"bundledProducts": [
{
"allocationExpiration": "DateTime",
"allocationId": "int",
"creditValue": "decimal",
"description": "string",
"fulfillmentStatus": "string",
"goodsType": "string",
"isPackagedStandAlone": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"name": "string",
"optionAttributeFQN": "string",
"optionValue": "object",
"productCode": "string",
"productReservationId": "int",
"quantity": "int"
}
],
"categories": [
{
"id": "int",
"parent": "self"
}
],
"description": "string",
"discountsRestricted": "bool",
"discountsRestrictedEndDate": "DateTime",
"discountsRestrictedStartDate": "DateTime",
"fulfillmentStatus": "string",
"fulfillmentTypesSupported": "string",
"goodsType": "string",
"imageAlternateText": "string",
"imageUrl": "string",
"isPackagedStandAlone": "bool",
"isRecurring": "bool",
"isTaxable": "bool",
"measurements": {
"height": {
"unit": "string",
"value": "decimal"
},
"length": {
"unit": "string",
"value": "decimal"
},
"weight": {
"unit": "string",
"value": "decimal"
},
"width": {
"unit": "string",
"value": "decimal"
}
},
"mfgPartNumber": "string",
"name": "string",
"options": [
{
"attributeFQN": "string",
"dataType": "string",
"name": "string",
"shopperEnteredValue": "object",
"stringValue": "string",
"value": "object"
}
],
"price": {
"creditValue": "decimal",
"msrp": "decimal",
"price": "decimal",
"salePrice": "decimal",
"tenantOverridePrice": "decimal"
},
"productCode": "string",
"productReservationId": "int",
"productType": "string",
"productUsage": "string",
"properties": [
{
"attributeFQN": "string",
"dataType": "string",
"isMultiValue": "bool",
"name": "string",
"values": [
{
"stringValue": "string",
"value": "object"
}
]
}
],
"upc": "string",
"variationProductCode": "string"
},
"productDiscount": {
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
},
"productDiscounts": [
{
"appliesToSalePrice": "bool",
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"discountQuantity": "int",
"excluded": "bool",
"impact": "decimal",
"impactPerUnit": "decimal",
"productQuantity": "int"
}
],
"quantity": "int",
"shippingDiscounts": [
{
"discount": {
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
},
"discountQuantity": "int",
"impactPerUnit": "decimal",
"methodCode": "string"
}
],
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"subtotal": "decimal",
"taxableTotal": "decimal",
"total": "decimal",
"unitPrice": {
"extendedAmount": "decimal",
"listAmount": "decimal",
"overrideAmount": "decimal",
"saleAmount": "decimal"
}
}
],
"itemTaxTotal": "decimal",
"lastValidationDate": "DateTime",
"orderDiscounts": [
{
"couponCode": "string",
"discount": {
"expirationDate": "DateTime",
"id": "int",
"itemIds": "string",
"name": "string"
},
"excluded": "bool",
"impact": "decimal"
}
],
"shippingSubTotal": "decimal",
"shippingTaxTotal": "decimal",
"shippingTotal": "decimal",
"siteId": "int",
"subtotal": "decimal",
"taxTotal": "decimal",
"tenantId": "int",
"total": "decimal",
"userId": "string",
"visitId": "string",
"webSessionId": "string"
}
```
For information about the properties in the response, refer to the [REST API Help](/api-overviews/openapi_commerce_overview).
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Order Item (After)
Source: https://docs.kibocommerce.com/pages/delete-order-item-after
**Related API:** This extension modifies the [Delete Order Item](/api-reference/return/delete-order-item) operation.
This action manipulates the HTTP request or response after the DeleteOrderItem operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deleteOrderItem.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/deleteOrderItem](/api-reference/return/delete-order-item) operation.
**HTTP Request**
DELETE `api/commerce/returns/{orderId}/items/{orderItemId}?updatemode={updateMode}&version={version}`
**Request Body**\
No request body content for this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Order Item (Before)
Source: https://docs.kibocommerce.com/pages/delete-order-item-before
**Related API:** This extension modifies the [Delete Order Item](/api-reference/return/delete-order-item) operation.
This action manipulates the HTTP request or response before the DeleteOrderItem operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deleteOrderItem.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/deleteOrderItem](/api-reference/return/delete-order-item) operation.
**HTTP Request**
DELETE `api/commerce/returns/{orderId}/items/{orderItemId}?updatemode={updateMode}&version={version}`
**Request Body**\
No request body content for this action.
**Response Body**\
Use context.response.body to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Package (After)
Source: https://docs.kibocommerce.com/pages/delete-package-after
**Related API:** This extension modifies the [Delete Return Package](/api-reference/return/delete-return-package) operation.
This action manipulates the HTTP request or response after the DeletePackage operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deletePackage.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/packages/deletePackage](/api-reference/return/update-return-package) operation.
**HTTP Request**
DELETE `api/commerce/returns/{returnId}/packages/{packageId}`
**Request Body**\
No request body content for this action.
**Response Body**\
No response body content for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Package (Before)
Source: https://docs.kibocommerce.com/pages/delete-package-before
**Related API:** This extension modifies the [Delete Return Package](/api-reference/return/delete-return-package) operation.
This action manipulates the HTTP request or response before the DeletePackage operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deletePackage.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/packages/deletePackage](/api-reference/return/update-return-package) operation.
**HTTP Request**
DELETE `api/commerce/returns/{returnId}/packages/{packageId}`
**Request Body**\
No request body content for this action.
**Response Body**\
No response body content for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Return (After)
Source: https://docs.kibocommerce.com/pages/delete-return-after
**Related API:** This extension modifies the [Delete Return](/api-reference/return/delete-return) operation.
This action manipulates the HTTP request or response after the DeleteReturn operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deleteReturn.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/deleteReturn](/api-reference/return/delete-return) operation.
**HTTP Request**
DELETE `api/commerce/returns/{returnId}`
**Request Body**\
No request body for this action.
**Response Body**\
No request body for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Return (Before)
Source: https://docs.kibocommerce.com/pages/delete-return-before
**Related API:** This extension modifies the [Delete Return](/api-reference/return/delete-return) operation.
This action manipulates the HTTP request or response before the DeleteReturn operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deleteReturn.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/deleteReturn](/api-reference/return/delete-return) operation.
**HTTP Request**
DELETE `api/commerce/returns/{returnId}`
**Request Body**\
No request body for this action.
**Response Body**\
No request body for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Shipment (After)
Source: https://docs.kibocommerce.com/pages/delete-shipment-after
**Related API:** This extension modifies the [Delete Return Shipment](/api-reference/return/delete-return-shipment) operation.
This action manipulates the HTTP request or response after the DeleteShipment operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deleteShipment.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/shipments/deleteShipment](/api-reference/return/delete-return-shipment) operation.
**HTTP Request**
DELETE `api/commerce/returns/{returnId}/shipments/{shipmentId}`
**Request Body**\
No request body content for this action.
**Response Body**\
No response body content for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delete Shipment (Before)
Source: https://docs.kibocommerce.com/pages/delete-shipment-before
**Related API:** This extension modifies the [Delete Return Shipment](/api-reference/return/delete-return-shipment) operation.
This action manipulates the HTTP request or response before the DeleteShipment operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.deleteShipment.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/shipments/deleteShipment](/api-reference/return/delete-return-shipment) operation.
**HTTP Request**
DELETE `api/commerce/returns/{returnId}/shipments/{shipmentId}`
**Request Body**\
No request body content for this action.
**Response Body**\
No response body content for this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# DeleteCredit (Before)
Source: https://docs.kibocommerce.com/pages/deletecredit-before
**Related API:** This extension modifies the [Delete Credit](/api-reference/credit/delete-credit) operation.
This action manipulates the HTTP request or response before the DeleteCredit operation occurs in Kibo eCommerce.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.customer.credits.deleteCredit.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo eCommerce.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [api/commerce/customer/credits/deleteCredit](/api-reference/credit/delete-credit) operation.
**HTTP Request**
DELETE `/commerce/customer/credits/{code}`
**Request Body**\
No request body content.
**Response Body**\
No response body content.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Delivery
Source: https://docs.kibocommerce.com/pages/delivery
The Kibo Composable Commerce Platform (KCCP) enables shoppers to select delivery services for their products when placing an order, in which the fulfillment location will either deliver a product to the customer using their own trucks or dispatch it to a provider. KCCP's updated Delivery BPM provides a comprehensive workflow to support shipments through the dispatch process.
## How Delivery Works
All items that are ordered for delivery will be grouped into a shipment of the [Delivery fulfillment type](/pages/delivery). This fulfillment process is initially similar to Ship to Home, but includes additional steps to prepare, dispatch, and confirm the delivery via either the fulfiller's own trucks or a delivery provider.
* **Accept Shipment**: The order has been accepted and is ready to be sent through fulfillment.
* **Print Pick Sheet**: The pick sheet is generated for store associates to collect shipment items. You can also include Delivery shipments in [pick waves](/pages/pick-waves "Pick Waves").
* **Validate Items in Stock**: Confirm whether all items were available for picking. If not all items are in stock and [Delivery Consolidation](/pages/sth-and-delivery-consolidation "STH and Delivery Consolidation") is not enabled, then you will be prompted to split the shipment (if you have partial inventory available) or reassign it to a new location (if you have none of the inventory available).
* **Wait for Transfer**: The shipment goes through this optional state if inventory was not available and a transfer is requested.
* **Print Packing Slip**: All items are at the fulfillment location and the packing slip is printed.
* **Prepare for Delivery:** The shipment has been packed and is ready to be delivered. If the shipment includes [assembly](/pages/fulfillment-service-items "Fulfillment Service Items"), then that must be completed.
* **Dispatch:** The items are ready to hand off to a delivery provider.
* **Delivery Confirmation:** The shipment is pending delivery confirmation from the provider.
* **Complete:** The shipment has been successfully delivered to the customer.
This diagram illustrates the basic delivery process flow, with options for whether a transfer is needed to supply missing inventory or consolidate shipments.
## Configure Delivery Fulfillment
The Delivery fulfillment type is available out-of-the-box alongside STH and BOPIS.
Fees are determined by the delivery provider's shipping method rates, which can be retrieved via the [Get Rates API](/api-reference/shipping/get-rates). The API documentation will be updated soon with the associated fields.
### Enable Locations for Delivery
Delivery fulfillment must be configured at both the product and location level. Fulfillment locations that offer this service must have the Delivery fulfillment type enabled:
1. Go to **Main** > **Supply** > **Locations**.
2. Click a location (or click **Edit** from the dropdown menu on that location in the table).
3. From the Fulfillment Types drop-down menu, select **Delivery**.
4. Click **Save**.
### Enable Products for Delivery
In order for a product to be purchased for delivery, that fulfillment option must also be available for the product in the catalog. To enable this option for a specific product:
1. Go to **Main** > **Sell** > **Products**.
2. Click the product that will allow delivery (or click **Edit** from the dropdown menu on that product in the table).
3. Under the Shipping section, check **Delivery**.
4. Click **Save**.
### Configure Routing Logic
Delivery [routing scenarios](/pages/scenarios "Scenarios") should be configured to handle shipment assignment cases if the customer does not specify one, as well as if you want the optimal delivery location to be displayed on the storefront based on the shopper's address. This logic will determine how a location is selected to assign Delivery shipments to, such as by prioritizing the closest distance from the shopper's address.
### Optional: Enable Consolidation
Delivery also supports consolidation via transfers. If the delivery location doesn't have any inventory available but there is inventory at transfer locations, then transfers will be created to consolidate all items at one location (either the delivery location selected by the customer or the location determined to have the shortest distance from the customer). If you want to use this feature, refer to the [Consolidation guide](/pages/sth-and-delivery-consolidation "STH and Delivery Consolidation") for more details and configurations instructions.
## Storefront Options
Once set up in your tenant, the shopper can opt into delivery as their fulfillment method.
You can modify your storefront product details and/or cart pages to ask the shopper for their zip code (or use a saved address, if applicable), which Order Routing will use to suggest the optimal delivery location. This is done via the Suggest Candidates API, which you can integrate with using the [Suggest Candidates API Extensions](/pages/extensible-order-routing "Order Routing") to display its suggestion on the page.
## Fulfillment Example
For more information about fulfillment flows, see the [Fulfillment Method Types guide](/pages/fulfillment-method-types). Any customer emails that notify the customer their shipment is ready for delivery or out for delivery should be sent by your delivery provider or third-party integration.
### View Delivery Information
On the [Fulfiller UI homepage](/pages/fulfiller-ui-overview "Fulfiller UI Overview"), there is a card for the Delivery fulfillment type that lists the number of shipments in each step of that process. Click a step on the card to be taken to the list of shipments in that step. When viewing shipment details, any delivery information is displayed at the top indicating the expected date, delivery instructions, and any other notes.
### Initial Fulfillment Steps
The Accept Shipment, Print Pick Sheet, Validate Items in Stock, Wait for Transfer (if applicable), and Print Packing Slip sections of a Delivery shipment are the same as those of the [Ship to Home process](/pages/ship-to-home "Ship to Home"). If [Package Consolidation](/pages/package-consolidation "Package Consolidation") is enabled for your implementation, that will be available to Delivery shipments if there are other qualifying shipments for the same customer to consolidate with.
If not all inventory is available during the Validate Stock step, while rejecting a shipment, or substituting an item, then you can choose to temporarily block any further assignments to that location. This is done using the same options as when [splitting Ship to Home shipments](/pages/ship-to-home#split-the-shipment "Ship to Home").
### Prepare for Delivery
When a Delivery shipment enters the Prepare for Delivery step, all items should be packed and made ready for dispatch. Enter the details of each package such as the dimensions and weight, then print the delivery label(s). You can also reprint a packing slip if needed.
If the shipment includes a service such as assembly, then that should be performed as well. Click **Ready for Dispatch** when everything is complete.
### Dispatch
During the Dispatch step, place the prepared shipment into the delivery area of your fulfillment location and click either **Handover to Delivery Provider** or **Return to Preparation for Delivery** (if corrections to the package are needed).
Once handed over, the shipment will be marked with the Dispatched status and you will be redirected back to the FFUI dashboard. You can return to the shipment for the next step once delivery is completed.
### Delivery Confirmation
This step displays all of the delivery information and the current status (such as Dispatched). Click **Order Was Delivered** to manually confirm that delivery is complete and mark the shipment Fulfilled.
# Delivery Solutions Integration
Source: https://docs.kibocommerce.com/pages/delivery-solutions-integration
![Delivery Solutions logo]() |
| Platforms: KCCP eCommerce+OMS |
[Delivery Solutions](https://deliverysolutions.co/) is a service that provides orchestration for fulfillment needs such as last-mile delivery. If you have a business account with Delivery Solutions, you may want to send your Kibo shipments to them at various points during the order creation and fulfillment flow to control when the order is dispatched.
For example, you may send shipments to Delivery Solutions when:
* The shipment is created and assigned to a location.
* Pick & Pack is complete, as that assures that the order is ready to be picked up by Delivery Solutions.
* Stock has been validated, or anywhere in the fulfillment flow that works best for your processes.
For more information about how Delivery fulfillment works in Kibo, see the [general Delivery guide](/pages/delivery "Delivery").
## Delivery Fulfillment Process
After Kibo is integrated with Delivery Solutions and the storefront theme is updated, the usual order creation and fulfillment process is:
1. When a product is enabled for delivery fulfillment, the storefront displays the Delivery option on the product details page and the cart. To proceed with this option, at least one Kibo location must be able to fulfill the items and at least one location must be a Delivery Solutions provider.
2. Available date and time windows at the Delivery Solutions location are displayed for the shopper to select their desired delivery window. If none is available, then they will not be able to continue with delivery and must choose a different fulfillment option.
3. Upon checkout, a single delivery fee is charged (regardless of the amount of items in the delivery). A single Kibo order is created that contains all delivery items in one shipment, while non-delivery items are placed in their respective shipment types.
4. Delivery Solutions fulfills the shipment and sends a confirmation notification to Kibo, who updates the shipment status to Delivered. If the delivery is unsuccessful, Kibo instead receives an Unable to Deliver notification and changes the shipment status to either Cancelled or Customer Care (depending on the BPM flow).
Actions from Delivery Solutions, such as Order Dispatched, are sent as [events](/pages/event-notifications-overview "Event Notifications Overview") to Kibo that can be consumed and handled as desired. Updates on the shipment in Kibo, such as a change in quantity, are also sent as events that can be consumed and handled as desired by Delivery Solutions.
Once the shipment has been dispatched to Delivery Solutions, you can perform actions that are not allowed on the Kibo shipment such as cancelling or editing it.
## Configure Delivery Solutions
For Delivery Solutions to work seamlessly with Kibo, make sure that these are configured in your business account:
1. [Smart Windows](https://userguide.deliverysolutions.co/#SmartWindows)
2. [API keys for integration with Kibo](https://docs.deliverysolutions.co/reference/authentication)
3. [At least one Kibo location](https://userguide.deliverysolutions.co/#Stores)
4. [Providers with rates, fees, and other options](https://userguide.deliverysolutions.co/#Access)
Delivery Solutions supports three configuration options for dispatch timing: **Scheduled** (in which specific pickup and drop-off times are selected and the order is scheduled, or those times are sent as null and the order is dispatched immediately), **Manual** (which can dispatch the order at any step in the BPM flow), or **Immediate** (in which the order is dispatched as soon as it is received).
## Configure Kibo and Storefront
Ensure that the details of the [Kibo fulfillment location(s)](/pages/manage-locations "Manage Locations") that you want to use match what you set up in Delivery Solutions. Then, configure the following:
1. [Enable Locations for Delivery](#enable-locations-for-delivery)
2. [Enable Delivery on Existing Products](#Enable-Delivery-on-Existing-Products)
3. [Configure Routing Logic](#configure-routing-logic) 5. [Update Your Storefront](#update-your-storefront) 7. [Display Custom Data in Fulfiller UI (Optional)](#display-custom-data-in-fulfiller-ui-optional)
### Enable Locations for Delivery
Delivery fulfillment must be configured at both the product and location level. Fulfillment locations that offer this service must have the Delivery fulfillment type enabled:
1. Go to **Main** > **Supply** > **Locations**.
2. Click a location (or click **Edit** from the dropdown menu on that location in the table).
3. From the Fulfillment Types drop-down menu, select **Delivery**.
4. Click **Save**.
### Enable Delivery on Existing Products
In order for a product to be purchased for delivery, that fulfillment option must also be available for the product in the catalog. To enable this option for a specific product:
1. Go to **Main** > **Sell** > **Products**.
2. Click the product that will allow delivery (or click **Edit** from the dropdown menu on that product in the table).
3. Under the Shipping section, check **Delivery**.
4. Click **Save**.
### Configure Routing Logic
In order to assign Delivery shipments to a fulfillment location, [routing scenarios](/pages/scenarios "Scenarios") should be configured to handle shipment assignment cases in case the customer does not specify one. You can also use this to [display the optimal delivery location](/pages/delivery#storefront-options "Delivery") on the storefront based on the shopper's address. This logic will determine how a location is selected to assign Delivery shipments to, such as by prioritizing the closest distance from the shopper's address.
### Update Your Storefront
This integration is available for Vercel and Next.js storefronts. You can customize this implementation by forking the Next.js and Vercel repositories as detailed in the [headless implementation guides](/pages/getting-started "Headless Integrations"). Update your storefront's environment variables with your new product type name and instant delivery product code, such as:
```text theme={null}
DELIVERYSOLUTIONS_PRODUCT_TYPE: Delivery Product Type
DELIVERYSOLUTIONS_PRODUCT_CODE: InstantDelivery
```
Additionally, if you want to display a suggestion of the optimal delivery location for the client's location, you can do so with the Suggest Candidates API and API Extensions. Refer to the [general Delivery guide](/pages/delivery#storefront-options "Delivery") for links to more information about this.
### Display Custom Data in Fulfiller UI (Optional)
If desired, you can display shipment-level custom data fields in the Fulfiller UI by [customizing the theme](/pages/fulfiller-theme-customization "Fulfiller and Returns Customization"). For example, you could display the Dispatch Status that Kibo receives from Delivery Solutions to allow fulfiller users more visibility into the process. These will always be key:value pairs in the `shipment.data` object.
If custom data exists for the shipment and the theme has been customized to display it, then a Custom Data tab will be displayed when viewing the shipment fulfillment details. If no custom data values exist for that shipment, then the tab will not be displayed.
# Dev Center and Your Local Environment
Source: https://docs.kibocommerce.com/pages/dev-center-and-your-local-environment
Dev Center is an online administrative portal for managing developer accounts, creating applications and theme records, and uploading, installing, and testing code before deploying it to a production site. It’s separate from your local development environment where you write code and manage source control repositories. Refer to [Set Up Your System](/pages/set-up-your-system) for more information about configuring Dev Center.
Before you start developing applications and themes, you’ll need to set up a local development environment. At a minimum, you need a text editor (e.g., Notepad++, Sublime Text) and source control system (e.g., Git, Subversion, Mercurial). After you set up your local development environment, use [Developer Tools](/pages/set-up-your-system) to build-out local directories with the necessary files to start developing applications and themes.
Since Kibo releases updates to the Core theme through Git, we highly recommend that you use Git as your source control system. Kibo also provides several [command-line tools](/pages/set-up-your-system) that leverage Git to make creating and updating themes and applications easier.
## Elements of Dev Center
Dev Center includes the following components:
| Item | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| DevAccounts | Your client account that virtually partitions all Kibo data, configuration, operations, and users for your organization. |
| Developer Accounts | User accounts that can be invited to work on one or more DevAccount. Developer Accounts can be assigned different roles for different DevAccounts. |
| Production Tenants | Tenants used for publishing applications, themes, and catalog updates to a live website. |
| Sandbox Tenants | Tenants used exclusively for development purposes, such as testing applications and theme appearance. |
| Console | Manage developer accounts, create applications and theme records, and test your work in sandboxes. |
## For More Information
For information about how to provision your own sandboxes and request production tenants, see [Set Up Your System](/pages/set-up-your-system).
See the [Email Customization documentation](/pages/email-template-customization "Email Customization") for the basic steps of setting up a theme and editing its Hypr files. If you need to learn about back-end development, check out our [application documentation](/pages/applications-1a6c791-introduction) and [SDKs](/pages/sdk-overview). When you're finished developing applications and themes locally, you use Dev Center to upload and deploy these assets to test and production environments.
# Developer Tools
Source: https://docs.kibocommerce.com/pages/developer-tools
Kibo provides several command-line tools to make developing applications and themes (used for email templates and the Fulfiller interface) across your local development environment and Dev Center easier. To install and use these tools, your system must meet the following requirements.
Get an introduction to the Kibo Dev Center
* [Node.js](https://nodejs.org/): Provides a platform for creating scalable network applications. Includes the [npm](https://www.npmjs.com/) package manager, which you’ll use to install additional software and tools.
* [Yeoman](http://yeoman.io/): Provides an ecosystem of generators for scaffolding web applications. Kibo provides several generators for quickly creating and updating the basic structure of applications and themes, including specifying build configurations and retrieving dependencies.
* [Grunt.js](http://gruntjs.com/): Provides a platform for automating build tasks. Kibo development tools use Grunt plugins for checking, building, and optimizing applications and themes and uploading theme to Dev Center.
* [Git](https://git-scm.com/): Provides a version control system for managing your theme files. The Theme Generator uses Git to configure repositories for your local projects. Kibo uses Git to release theme updates, making Git an essential part of your upgrade path.
The Git installation process attempts to install Git Bash, which is a simulated Unix-like command line environment for Windows. However, Node.js applications that rely on a command line interface aren’t compatible with Git Bash. Refer to the Node.js [issue](https://github.com/nodejs/node/issues/3006) for more information. If you install Git on a Windows system, select the following option when prompted to avoid compatibility issues:
Refer to the following table for a list of Kibo development tools and links to more information on installing and using them:
| Third-Party Software | Kibo Tools |
|---|
| Yeoman | - Actions Generator: Generates the application directory structure, JavaScript templates that correspond to the actions you choose to install, and a test framework for validating your code before uploading it to Dev Center.
- Theme Generator: Generates the theme directory structure, common theme files, build process, and test framework for validating your code before uploading it to Dev Center. This tool also configures your local directory as a Git repository and can connect other theme Git repositories as remotes to make upgrading themes easier.
- Kibo Application Generator: Configures code in an existing application or theme directory with a new Dev Center application key so you can upload the files to your developer account.
Refer to the following topics for more information: |
| Grunt | - mozutheme: Runs “compile” or “check” commands (depending on your configuration) during the build process. This task is built into the Theme Utility Helpers for compiling and maintaining themes.
- mozusync: Takes an environment configuration (supplied either manually in Gruntfile.js or through mozu.config.json) and synchronizes application or theme files in a local directory with Dev Center.
Refer to the following topic for more information: |
| npm | - Theme Utility Helpers: Provides a library of common tasks for checking, compiling, and maintaining themes.
- API Extension Utility Helpers: Provides a library for running common tasks in API Extension actions.
- API Extension Action Simulator: Provides unit and integration tests for API Extension actions.
- Sync Utility Helpers: Provides the library for the mozusync Grunt task.
- Node.js SDK: Provides the base library for all Node.js communication with the API.
- Multipass: Provides an authentication storage plugin for the Node.js SDK.
|
## Theme Generator
Themes are designed to leverage inheritance, so all of your theme development should extend the latest Core theme. We recommend using the [Theme Generator](https://www.npmjs.com/package/generator-mozu-theme) to manage your theme assets. The Theme Generator:
* Creates new themes that inherit from the latest Core theme or clones an existing theme from a Git repository to a local directory. You can also use the generator to upgrade existing themes. Refer to [Upgrade a Legacy Theme](#upgrade-a-legacy-theme) for more information.
* Configures your local theme directory as a Git repository.
* Connects the Core theme Git repository (or any other theme Git repository) to your theme as a remote so you can merge upstream changes.
### Create a New Theme
The [Theme Generator](https://www.npmjs.com/package/generator-mozu-theme) is a Yeoman plugin that generates the scaffolding (e.g., directory structure, reference files, and build files) necessary to package a theme and upload it to Dev Center. It’s designed to augment, not overwrite, existing themes. If you have a theme that extends the Core theme, you can safely run this tool in that directory without overwriting your existing files. Whenever Kibo releases a Core theme upgrade, you can use this tool to merge changes from the Core theme ( or any other theme Git repository) with your theme.
To create a brand new theme that inherits from the latest Core theme:
1. Open a terminal (OS X) or a command prompt (Windows).
2. Install the Yeoman command-line tool globally:\
`npm install -g yo`
3. Install the Grunt command-line tool globally:\
`npm install -g grunt-cli`
4. Install the Theme Generator globally:\
`npm install -g generator-mozu-theme`
5. Create a new folder for your theme on your local machine and navigate to it:\
`mkdir your_theme && cd your_theme`
6. Run the Yeoman generator inside your theme directory:\
`/your_theme/$ yo mozu-theme`
7. If you have an old version of the tool installed, you’ll be prompted to update it. Press `` to exit the application and enter the following command: `npm install -g generator-mozu-theme`
8. Select **Brand new theme**.
9. Enter the public name of your theme.
10. (Optional) Enter a short description of your theme.
11. Enter the initial version.
12. Select **Mozu Core Theme** as the base theme from which your new theme will inherit.
13. Select which version of the Core theme from which your new theme will inherit.
14. Enter your theme’s Dev Center Application Key. If you’re using a package other than Release, make sure you enter the correct Application Key. Package names are appended to the Application Key of each package for identification purposes. The build tools rely on the Application Key to upload files to the right place in Dev Center.
15. Enter your Developer Account login email.
16. Enter your Developer Account password.
17. Select your developer account.
You now have a blank theme based on the latest Core theme, which you can modify, build, and upload to Dev Center. Since the Core theme Git repository is connected to this Git repository as a remote, you’ll be able to merge upstream updates from the Core theme with your theme in the future.
Although the Theme Generator is the recommended method for creating and uploading themes, you can also complete the process manually. To manually upload theme files from within Dev Center:
1. Compress your local theme project into a .zip file.
2. Log in to Dev Center.
3. Click **Develop** > **Themes**.
4. Double-click the theme where you want to upload files.
5. Click the **Packages** tab.
6. Select the package you want to upload files to from the **Active Package** drop-down menu.
7. Click **More** > **Upload**.
8. Drag and drop your theme .zip file into the **Upload files** dialog box.
9. Wait for confirmation that the upload is complete.
10. Click **Done**.
11. You should see the contents of your theme in the **Packages** tab.
### Merge Updates from the Latest Core Theme
If the latest Core theme is already connected to your repository as a remote, you can merge changes from the Core repository into your theme. You must resolve any merge conflicts that arise and commit your changes to complete the upgrade process. Kibo recommends conducting user acceptance, automated unit, and end-to-end testing of your site to ensure the latest Core theme works for your site.
To merge updates from the latest Core theme:
1. Examine the merged Github [Pull Requests](https://github.com/Mozu/core-theme/pulls?utf8=%E2%9C%93\&q=is%3Apr) to see what individual features are coming over from the latest Core theme. You can also use the [Compare View](https://github.com/blog/612-introducing-github-compare-view) in Github to compare different versions of the Core Theme.
2. Open a terminal or command prompt and navigate to your local theme directory.
3. Enter `grunt mozutheme:check` to see if any updates are available.\\
4. Select the version you’d like to merge with your theme and use the following command syntax to merge: `git merge `
5. Replace `` with the value displayed next to the selected version:\\
6. Resolve all merge conflicts and ensure your repository is in a clean state before proceeding.
7. Install your upgraded Core-based theme on a development sandbox and activate it.
8. Activate Debug Mode in the storefront by adding the query parameter `debugMode=true` to any storefront URL. For example, `yourSite.com/about-us?debugMode=true`.
9. Visually examine your theme for problems.
10. Test your site for issues:
* View a category
* Search for products
* Configure a product
* Manipulate the cart
* Check out and place an order
* Make changes to your account page, etc.
11. Make any necessary corrections based on visual or console errors.
12. Continue testing and developing until your theme is free from errors and regressions.
### Upgrade a Legacy Theme
You must manually upgrade themes that extend legacy versions of the Core theme (version 8 and earlier) to use the latest Core theme instead. The Theme Generator connects the latest Core theme to your repository as a remote so you can merge changes from the Core Git repository into your theme. You must resolve all merge conflicts and commit your changes to complete the upgrade process. Kibo recommends conducting user acceptance, automated unit, and end-to-end testing of your site to ensure the latest Core theme works for your site.
To upgrade a legacy theme:
1. Examine the merged Github [Pull Requests](https://github.com/Mozu/core-theme/pulls?utf8=%E2%9C%93\&q=is%3Apr) to see what individual features are coming over from the latest Core theme. You can also use the [Compare View](https://github.com/blog/612-introducing-github-compare-view) in Github to compare different versions of the Core Theme.
2. Run the Theme Generator to upgrade your theme to inherit from the latest Core theme:
1. Open a terminal or command prompt and navigate to your local theme directory.
2. Enter `yo mozu-theme`.
3. Select **Upgrade now**.
4. Resolve all merge conflicts and ensure your repository is in a clean state before proceeding.
3. Install your upgraded Core-based theme on a development sandbox and activate it.
4. Activate Debug Mode in the storefront by adding the query parameter `debugMode=true` to any storefront URL.
5. Visually examine your theme for problems.
6. Test your site for issues:
* View a category
* Search for products
* Configure a product
* Manipulate the cart
* Check out and place an order
* Make changes to your account page, etc.
7. Make any necessary corrections based on visual or console errors.
8. Continue testing and developing until your theme is free from errors and regressions.
## Build and Sync Files with Dev Center
You need to build and upload your theme files to Dev Center in order to apply your theme to a site. You can manually compress and upload your theme files, but we recommend using the theme build tools instead. To prepare and upload your theme files using the build tools:
1. Open a terminal (OS X) or a command prompt (Windows).
2. Navigate to the root directory containing your theme files.
3. Run a Grunt plugin command:
What does `grunt` do and what are the common options you can use with it?
`grunt:`
* Checks your JSON and JavaScript for syntax and style errors
* Compares your theme with the remote base theme and notifies you if updates are available for merging
* Compiles your theme's JavaScript according to the `./build.js` file that you either inherit or override
* Uploads changed files to Dev Center into the theme specified by the Application Key you provided when configuring the Theme Generator tool
* If you’ve added new files at the root level of your theme directory, you must add each file name to the `mozusync.upload.src` section of `Gruntfile.js` to upload them using the `grunt` command.
`grunt build-production:`
* Checks your JSON and JavaScript for syntax and style errors
* Compiles your theme's JavaScript according to the `./build.js` file that you either inherit or override
* Compress and minify the compiled JavaScript for production
* Creates a `.zip` containing your theme files suitable for sharing or manually uploading within Dev Center (The ZIP file you upload contains only the contents of the theme folder that have changed and not the theme folder itself.)
`grunt mozusync:wipe && grunt:`
* Cleans up the theme in Dev Center by deleting all files and then re-uploading your theme files
`grunt watch:`
* Listens for any changes to your theme files
* If you save a change to a theme file, `grunt` automatically builds and uploads your theme to Dev Center.
## SSO Authentication for Grunt
If your Kibo account uses Single Sign-On (SSO), the legacy inline password prompt cannot authenticate your credentials. Recent versions of `grunt-mozu-appdev-sync` open a browser window for web login by default, so your SSO credentials are authenticated through the browser.
### Requirements
Your project must use `grunt-mozu-appdev-sync` version **2.4.5 or later**.
Check your current version:
```bash theme={null}
npm list grunt-mozu-appdev-sync
```
If you are on an older version, update it:
```bash theme={null}
npm install grunt-mozu-appdev-sync@2.4.5 --save-dev
```
### Running Grunt with SSO
No configuration or environment variable is needed. Run `grunt` as usual:
```bash theme={null}
grunt
```
The CLI opens a browser window for authentication instead of prompting for a password. After you log in via SSO, the CLI stores the token and continues with the sync.
### Forcing the Legacy Password Prompt
If you need the old inline password prompt instead of browser-based login, for example for an account that does not use SSO or while troubleshooting, set the `KIBO_LEGACY_LOGIN` environment variable. The correct syntax depends on your shell:
**Windows Command Prompt:**
```cmd theme={null}
set KIBO_LEGACY_LOGIN=true && grunt
```
**PowerShell:**
```powershell theme={null}
$env:KIBO_LEGACY_LOGIN="true"; grunt
```
**macOS / Linux:**
```bash theme={null}
KIBO_LEGACY_LOGIN=true grunt
```
## Application Generator
You may download a theme, application, or API Extension action from a colleague or from a public repository that hasn’t been configured to sync with Dev Center. You can configure existing code to upload to your Developer Account just by adding a `mozu.config.json` file in the working directory.
### Configure an Existing Theme to Sync with Dev Center
1. Open a terminal (OS X) or a command prompt (Windows).
2. Install the Yeoman command-line tool globally:\
`npm install -g yo`
3. Install the Application Generator globally:\
`npm install -g generator-mozu-app`
4. Navigate to your local working directory.
5. Run the generator:\
`yo mozu-app`
It will prompt you only for the information it needs to create a configuration file. It will not store your password in plain text; it only uses your password to download your list of developer accounts at the time that it runs.
### Options
* `--configure`: Only create a `mozu.config.json` file. Use this option to add existing code to an application in your developer account.
* `--skip-install`: Skips the automatic execution of npm install after scaffolding has finished.
* `--skip-prompts`: You may find yourself rerunning the generator in the same directory multiple times. Use this option to save answers to the prompts so you want to quickly rerun the generator without prompts. This option won’t work if you’ve never run the generator in this directory.
* `--quick`: Equivalent to `--skip-install --skip-prompts`.
* `--internal`: Allows integration with nonproduction environments. The prompts will include an extra question about which environment to sync with.
# Digital Gift Card Overview
Source: https://docs.kibocommerce.com/pages/digital-gift-card-overview
You can create a digital gift card as a product that shoppers can buy on your storefront. There are two different types of digital gift cards: standard product gift cards and configurable gift cards with value options. The configuration steps are similar to creating a normal product in your catalog, but there are some unique steps that are required to create the digital gift card on your storefront.
For information about processing gift cards as payment methods rather than products, see [Gift Card Processing](/pages/gateway-gift-cards).
## Digital Gift Card Types
It is important to identify the type of digital gift card you want to create first.
### Standard Product Gift Cards
Standard product gift cards have one set value amount that shoppers cannot change on the storefront. The price you set is the only amount shoppers can buy for the gift card.
For example, you create a \$50 standard product gift card. This gift card appears on your storefront as a product with a \$50 price, and shoppers cannot select a different amount.
### Configurable Gift Cards
Unlike standard product gift cards, configurable gift cards allow you to specify more than one value for gift cards. They allow you to group multiple monetary amounts, which the shopper can choose from, on the same storefront product page. Since a configurable gift card with value options is a product with variations, each of the monetary amounts have their own product code related to the base product's code.
For example, you create the base configurable gift card and you set its price to \$0. Then you add value options for \$5, \$10, and \$20 to the base product. Each of these options has its own product code and the shopper can choose one of these options on the storefront page.
## Digital Gift Cards in Admin UI
When an order is created and a digital gift card is one of its line items, then the gift card is placed into a "Digital" shipment that only contains digital items. This shipment is automatically marked as Fulfilled and its payment is immediately captured. You can view this shipment in the Order Admin UI as shown in the example below. The order's shipment details screen will include an additional tab for Digital Item Details where the gift card number, contact information, and gift message are displayed.
Edit the recipient's name, email address , or gift message by typing in the text boxes and clicking **Save**, or click **Resend Digital Item Email** to send the customer notification again. This email is enabled by default [in your site settings](/pages/general-settings#email "General Settings") (under the Miscellaneous email options), but if disabled then an error message will be displayed after clicking the button.
# Discount Dashboard
Source: https://docs.kibocommerce.com/pages/discount-dashboard
The Discount dashboard provides an overview of how discounts are performing and identifies the top performing discounts. It can be viewed under the discounts topic at **Kibo Standard Reports** > **Discount** > **Discount Dashboard** in the navigation menu.
The supported filters that can be applied to this dashboard are:
| Name | Description | Default |
| ------------------ | --------------------------------------------------------------------------- | --------------- |
| Site | Restrict results to one or more of your sites. | All |
| Order Created Date | Limit results to only orders created within this time range. | Past five weeks |
| Discount Type | Specifies whether this is a product, shipping, or order discount. | All |
| Discount Level | Specifies whether the discount is applied at the order or order item level. | Order |
The measures that are calculated by this dashboard are:
| Name | Description |
| -------------------- | ------------------------------------------------------------------------------- |
| Order Discount Count | The number of times a discount was applied. |
| Total Order Subtotal | The sum of the subtotal for all orders. |
| Average Order Value | The order total divided by the valid order count. |
| Total Impact | The total order, shipping, or product amount affected by applying the discount. |
The tiles that make up this dashboard are:
| Name | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Top Ten Discounts by Redemptions | The ten discounts with the highest order discount count. |
| Top Ten Discounts By Revenue | The ten discounts with the highest total order subtotal. |
| Top Ten Discounts By Impact | The ten discounts where the average order value was highest on orders where they were applied. |
| Discounted vs. Non-Discounted IPO | The items per order for orders where a discount was applied compared to orders where no discount was applied. |
| Discounted vs Non-Discounted AOV | The average order value for orders where a discount was applied compared to the average order value for orders where no discount was applied. |
| Discounted vs. Non-Discounted Revenue | The sum of the order subtotal for all orders with an order discount applied compared to the sum for all orders with no order discount applied. |
| Performance By Order Status | The order discount count as a percentage of total orders grouped by order status |
| Discount Usage by Week | The order discount count grouped on a weekly basis. |
| Discount Performance | The order discount count, total impact, total subtotal, and average order value for each discount. |
# Discount Extensibility
Source: https://docs.kibocommerce.com/pages/discount-extensibility
Discount extensibility allows you to utilize custom attributes as additional discount conditions, giving you more flexibility over how discounts are applied in your implementation.
While configuring customer, B2B, order, or location attributes, you can indicate whether they are enabled for discounts. Then, the attributes can be used to define specific conditions in discount configurations.
## Use Cases
The following sections describe example scenarios in which discounts may be useful with custom attributes.
### B2B and Customer Attributes
B2B and customer attributes can be used as conditions for both line item and order-level discounts. Both types require the shopper to be logged into their account in order to apply the discount, and can be applied in either the cart or checkout. These may be useful in scenarios such as:
* Offering discounts to Harvard alumni based on whether an "alumni" attribute is set to "Harvard."
* Offering discounts to customers using long-term payment plans based on whether a "paymentTermMonths" attribute is set to at least "3".
### Order Attributes
Order attributes can only be used as condition for order-level discounts and can be applied in either the cart or checkout. They may be useful in scenarios such as:
* Offering discounts for deliveries based on whether a “deliveryInfo” attribute is not null.
* Offering discounts on orders with completed feedback surveys based on a "feedbackSurvey" attribute set to "true."
### Location Attributes
Location attributes can only be used as condition for line item-level discounts and can be applied in either the cart or checkout. They may be useful in scenarios such as:
* Offering discounts for frozen items from locations with a "supportsRefrigeration" attribute set to "true."
* Offering discounts for eCommerce-specific locations based on a "storeType" attribute set to "ecomm."
## Enable Attributes for Discounts
You must make the attribute available to discounts in its configurations in order to use it as a discount condition. For more information about creating and configuring attributes in general, see the following documentation:
* [B2B Attributes](/pages/b2b-attributes "B2B Attributes")
* [Customer Attributes](/pages/customer-attributes)
* [Order Attributes](/pages/order-attributes "Order Attributes")
* [Location Attributes](/pages/location-attributes "Location Attributes")
In the general settings of each attribute type, locate and toggle on the **Available for Discounts** option and click **Save**. The below example shows the option for a B2B attribute.
The below example shows the option for a customer attribute.
The below example shows the option for an order attribute.
The below example shows the option for a location attribute.
## Create Discounts with Attribute Conditions
Once enabled, you will be able to select the attribute in discount configurations. While [configuring a discount](/pages/configure-discounts "Configure Discounts"):
1. Locate the Attribute Conditions section.
2. Click **Add**.
3. Select an **Attribute Type** (B2B, Customer, Order, or Location) from the drop-down menu.
4. Select the attribute you want to add from the **Attributes** drop-down menu.
5. Select the **Operator Type**. The available operators will depend on the attribute's data type.
6. If you select a comparison operator, another field will appear where you should enter the value that the attribute should be compared to. For example, you may set the operator type as "greater than" and the value as "2."
7. Click **Add**. This attribute and its selected logic will now be displayed in the Attribute Conditions table.
# Discount Folders
Source: https://docs.kibocommerce.com/pages/discount-folders
The Discounts page at **Main** > **Sell** > **Discounts** displays all discounts in your catalogs in a folder hierarchy structure, allowing you to more easily organize your discounts.
Learn about pricing strategies and configuration
Understand how promotions and discounts work
See the Pricing API documentation for programmatic access
However, using the folder functionality is optional: discounts do not have to be placed into any folders. If not placed in a folder, they will be listed at the root level instead.
## Discounts Homepage
Both active and scheduled discounts are displayed on the Discounts homepage by default.
Each catalog has its own independent set of discounts and folders. You can select the catalog you want to view discounts for in the top header of the page. Additionally, you can customize which columns are displayed in the discounts table by expanding the edit menu (the three dots) in the top right of the table and selecting which columns you want shown from the list that appears.
The search bar at the top of the page will always perform a global search across all folders in the catalog. Even if you perform a search while viewing a particular subfolder, the current subfolder will be unselected and the query will return results from all folders. Likewise, the Advanced Filter options (which allow you to narrow your search to features like coupon codes, discount statuses, start/end dates, and more) will be applied globally and return search results from all folders.
## Manage Folders
You can perform the following actions on individual folders:
* **Create**: Add a new subfolder within the selected folder. This will open a pop-up for you to enter the name of the new folder. Validations for special characters and folder name length will be performed.
* **Delete**: Remove the selected folder. A folder cannot be deleted if it has discounts in it or has subfolders. If there are either subfolders or discounts in it, an error message will be displayed prompting you to empty the folder before deleting it.
* **Move**: Move the selected folder and all of its discounts to a new location in the hierarchy. You will be prompted to select the destination for the folder to be placed under.
* **Rename**: Change the name of the selected folder. Validations for special characters and folder name length will be performed.
Since each catalog is independent, folder names do not have to be unique between catalogs. However, you cannot have duplicate folder names within the same parent folder.
## Manage Discounts Within Folders
Clicking **Create New Discount** in the top right of the Discounts page will open a new tab to configure the new discounts and will always create the new discount in the current folder you are viewing.
For existing discounts, you can perform the following actions.
* **Delete**: Remove the discount from this catalog. This can only be performed on one discount at a time.
* **Move**: Change this discount's location in the folder hierarchy. This can be performed on multiple discounts at a time.
* **Edit**: Open the discount configuration editor, similar to that for creating a discount. This can only be performed on one discount at a time.
* **Duplicate**: Create a new discount with the same configurations as the previous. This can only be performed on one discount at a time.
### Move Discounts
If you select multiple discounts, then only the **Move** action will be available. You are able to select all discounts on the page if desired, as well as individual discounts from across multiple pages.
After initiating the Move action, a modal will appear asking you to select the destination folder. Make your selection and click **Move** to confirm.
# Discount View
Source: https://docs.kibocommerce.com/pages/discount-view
The Discount view provides dimensions and measures for the discount data model.
The measures calculated by this view are:
| Name | Measure Type | Description |
| -------------- | ------------ | ----------------------- |
| Discount Count | Count | Count of all discounts. |
The dimensions included in this view are:
| Name | Data Type | Description |
| --------------------- | --------- | ----------------------------------------------------------------------------------- |
| Coupon Code | String | The coupon code that a shopper uses to redeem an associated discount on a purchase. |
| Discount Created Date | Datetime | The timestamp of the date and time the discount was created. |
| Discount End Date | Datetime | The timestamp of the date and time the discount expires. |
| Discount ID | String | Internal unique identifier of the discount. |
| Discount Name | String | The user supplied name for the discount. |
| Discount Start Date | Datetime | The timestamp of the date and time the discount becomes active. |
| Discount Updated Date | Datetime | The timestamp of the date and time the discount was most recently updated |
# Discounts Overview
Source: https://docs.kibocommerce.com/pages/discounts-overview
You can promote your products using discounts, which are managed at the catalog level. Discounts enable you to apply special promotions or sales to the products in your catalog. For example, you can apply free shipping to orders over \$50, or create a 40% off coupon for shoppers to use during a 3-day holiday sale.
Get an introduction to marketing and discount capabilities
See how to create free shipping order discounts
See how to configure the general section of an order discount
Discounts are located in the Admin at **Main** > **Sell** > **Discounts**, where they are arranged in a [folder hierarchy](/pages/discount-folders) and you can [configure new discounts](/pages/configure-discounts). Follow the guides in this section to learn more about creating and managing different types of discounts.
# Display Groups
Source: https://docs.kibocommerce.com/pages/display-groups
When [adding property attributes to a product type,](/pages/property-attributes#add-properties-to-product-types) you can specify whether the property and its values are available to be displayed on specific storefront page types using the **Display Group** drop-down menu.
You can control whether or not a property is actually displayed on your storefront using your theme. The **Display Group** selection only specifies whether or not the property is available to your theme on specific storefront page types.
## Display Group Options
Refer to the following table for more information about the possible display group selections:
| Display Group | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Storefront Details and Listings** | The property and its values are available on product detail pages as well as product listing pages, such as categories and search results. |
| **Storefront Details** | The property and its values are available only on product detail pages. |
| **Admin Only** | The property and its values are not available on storefront pages, and display only in Admin. |
## Set Display Group
To specify a **Display Group** selection:
1. Go to **System** > **Schema** > **Product Types**.
2. Click the product type you want to assign to a display group.
3. In the **Properties** section, select a value in the drop-down **Display Group** menu.
# Dispose Return Items (After)
Source: https://docs.kibocommerce.com/pages/dispose-return-items-after
**Related API:** This extension modifies the [Dispose Return Items](/api-reference/return/dispose-return-items) operation.
This action manipulates the HTTP request or response after the DisposeReturnItems operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.disposeReturnItems.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/disposition](/api-reference/return/dispose-return-items) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/disposition/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Dispose Return Items (Before)
Source: https://docs.kibocommerce.com/pages/dispose-return-items-before
**Related API:** This extension modifies the [Dispose Return Items](/api-reference/return/dispose-return-items) operation.
This action manipulates the HTTP request or response before the DisposeReturnItems operation occurs in Kibo.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.returns.disposeReturnItems.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [commerce/returns/disposition](/api-reference/return/dispose-return-items) operation.
**HTTP Request**
POST `api/commerce/returns/{returnId}/disposition/?responseFields={responseFields}`
**Request Body**\
Use `context.request.body` to read/write the HTTP request body using this action.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Download Reports
Source: https://docs.kibocommerce.com/pages/download-reports
You can download full reports directly from the dashboard, download individual tiles, schedule a recurring report for automatic send, and export custom reports to S3 on a one-time or recurring basis.
## Download a Report
To download a report from the dashboard:
1. Expand the options menu in the top right and click **Download**.
2. You will be prompted to select PDF or CSV.
* Downloading as a PDF offers more options such as single column format, expanding tables, and paper size.
* Downloading as a CSV includes no additional options.
3. When you have finished selecting your options, click **Open in Browser** to view in the browser or **Download** to download the file.
## Download a Tile
Alternatively, individual tiles from a dashboard can be downloaded:
1. Expand the three dots in the top right corner of a tile that appear on hover, and click **Download data**.
2. Select your desired format (TXT, Excel, CSV, JSON, HTML, Markdown, or PNG).
3. You can expand the **Advanced data options** to further specify how you want visualization included, how to format the data, and the rows to include.
## Scheduling a Report
Instead of immediately receiving the email send, a report can instead be scheduled for delivery at a future date and time. This report will be sent as an attachment to the email.
1. Expand the options menu in the top right and click **Schedule delivery**.
2. A modal appears with scheduling options.
3. In the **Settings** tab, set the recurrence, time, file format (PNG, CSV zip file, or PNG visualization), destination (email, webhook, Amazon S3, SFTP, or Google Drive) and the details of the selected destination.
4. In the **Filters** tab, you can change the configuration of filter logic that will be used to generate the scheduled report.
5. In the **Advanced options** tab, you can set additional options depending on the file and delivery format you selected. For example, if emailing the report then you can add a custom message to be included in the body of the email. You can also select the delivery time zone, paper size, and how to format the data.
6. Click **Test now** to immediately send a test delivery to review the format and other configurations before confirming the scheduling.
7. Click **Save** to confirm the schedule.
Click **Schedule** to view the options for this future report delivery. The same options for file format and filters are supported as in the immediate email send. A test email can be sent to review the format and other configurations before confirming the scheduling.
## Exporting to S3
If you export report data to an S3 drop point, rather than downloading the reports directly or scheduling an email, then the end result will be a set of JSON files copied to an Amazon S3 bucket. This can be performed on custom reports as either a one-time export or a recurring export that is generated on a given schedule.
### Prerequisites
In order to perform either type of export, the following items must already be set up:
* You have created an AWS S3 bucket
* You have configured an AWS IAM user with write permissions to the S3 bucket.
The following data will have to be provided during the export process:
* S3 bucket name
* AWS region where S3 bucket lives
* Access key and secret key for the IAM user
### Creating a One-Time Export
From the Reporting UI, navigate to **Shared** > **Custom Reports** in the folder directory and click a custom report. When viewing a custom report, it is possible that the format of the report header and menu buttons may change to an older version. In this case, you can still navigate the folder directory from the top right.
To begin the export process:
1. Click the gear icon in the top right (where you also have options for direct download and schedule) and click **Send**.
2. A modal will appear with options to fill out with the various fields, including advanced options. The standard options are listed below.
* **Title:** This will be combined with a timestamp to form the file name sent to S3.
* **Destination:** S3.
* **Bucket Name:** The bucket name in AWS.
* **Optional Path:** If you would like the files to be placed in a folder within the bucket, enter it here.
* **Access Key**: The AWS access key for the IAM user
* **Secret Key**: The AWS secret key for the IAM user
* **Region**: The AWS region where the bucket exists
* **Data Format**: JSON – Simple
* **Filters**: Select the date range that you wish to export.
3. In the **Filters** section, configure the filter logic that you want the report to be generated with.
4. In **Advanced options**, you can set the following additional configurations.
* **Limit:** All Results
* **Format Options:** Check all if you want data to be formatted, such as currency symbols; uncheck all if you want raw data.
5. When the form is complete, click **Send** to trigger the export. The report will be viewable in the S3 drop point when the export is finished.
### Scheduling a Recurring Export
From the Reporting UI, navigate to **Shared** > **Custom Reports** in the folder directory and click a custom report. When viewing a custom report, it is possible that the format of the report header and menu buttons may change to an older version. In this case, you can still navigate the folder directory from the top right.
To begin the export process:
1. Click the gear icon in the top right and click **Schedule.
**
2. The configuration form is similar to the one used for a one-time S3 export, but includes additional options for the report recurrence. The standard options are listed below.
* **Name**: This will be combined with a timestamp to form the file name sent to S3.
* **Destination**: S3.
* **Bucket Name**: The bucket name in AWS.
* **Optional Path**: If you would like the files to be placed in a folder within the bucket, enter it here.
* **Access Key**: The AWS access key for the IAM user.
* **Secret Key**: The AWS secret key for the IAM user.
* **Region**: The AWS region where the bucket exists.
* **Data Format**: JSON – Simple.
3. Select whether you want to **Trigger** the report on a repeating interval or when a particular datagroup updates.
* If you select **Repeating** **interval**, set the interval and time.
* If you select **Datagroup update**, select the particular datagroup.
4. It is recommend to leave the **Filters** section as the default.
5. In the **Advanced options** section, select any criteria for sending the scheduled report, the email and format options, time zone, and result limits.
Reporting data is updated on an hourly basis, so a more frequent interval will not result in more recent data. Note that this also means that some records will be repeated in subsequent export files.
# Drafts
Source: https://docs.kibocommerce.com/pages/drafts
Kibo eCommerce understands changes to either site content or product content as drafts, and distinguishes between the two types of drafts. You can publish content drafts or product drafts from the Drafts page located at **Main** > **Storefront** > **Drafts**. Updates to storefront content and product catalogs will be drafts when the appropriate [Publishing Settings](/pages/publishing-settings) option is set to Staged.
This page has separate tabs for Content and Product drafts. As noted when configuring the settings, content changes can be applied on a site-by-site basis while product changes must apply across every single site that uses that master catalog. You cannot stage or publish catalog changes on one site while staging it for another site; catalog updates are all or nothing.
## Content Drafts
Content publishing enables you to make draft changes to content, such as web pages or blog posts, before publishing them to a site. For each site associated with a tenant, you can set the content publishing mode to either live or pending mode in Admin.
### Pending Mode
When a site is in pending mode, Kibo eCommerce creates a draft version of all new and changed content. The draft version increments the content changes until they are published or discarded. You can then publish or discard the drafts for all pending changes or for individual documents. If you switch the content publishing mode to live, Kibo eCommerce automatically publishes all pending drafts.
### Live Mode
When a site is in live mode, Kibo eCommerce immediately performs all operations for changed content. The live version of the content appears on the website, except when previewing the website in pending mode.
### Content Publishing Tasks
From the Content tab on the Drafts page, you can perform the following tasks:
* [Publish Individual Content Draft](#publish-individual-content-draft)
* [Publish Multiple Content Drafts](#publish-multiple-content-drafts)
* [Preview Individual Content Draft](#preview-individual-content-draft)
* [Discard Individual Content Draft](#discard-individual-content-draft)
* [Content Publishing Best Practices](#content-publishing-best-practices)
### Publish Individual Content Draft
To publish an individual content draft:
1. Go to **Main** > **Storefront** > **Drafts**.
2. Select the relevant site from the site list at the top of the page.
You need to know which site you made changes to in order to view the pending content drafts for that site only.
3. From the **Drafts** grid, select the **Content** tab.
4. Select a draft and then click **Publish Now** from the selection list.
### Publish Multiple Content Drafts
If you wish to publish multiple content drafts at once, Kibo eCommerce recommends moving the content drafts into a Publish Set and then either publishing the Publish Set immediately or specifying a future date to publish the Publish Set.
You can also select multiple content drafts in the **Drafts** grid, and then select **Publish Now** from the selection list.
Refer to [Publish Sets](/pages/publish-sets) for more information about using Publish Sets.
### Preview Individual Content Draft
You can preview individual content drafts to see how the draft appears on your site. You can use this to quickly decide whether to publish or discard the draft.
To preview an individual content draft:
1. Go to **Main** > **Publishing** > **Drafts**.
2. Select the relevant site from the context switcher at the top of the page.
You need to know which site you made changes to in order to view the pending content drafts for that site only.
3. From the **Drafts** grid, select the **Content** tab.
4. Select a draft and then click **Preview** from the selection list.
### Discard Individual Content Draft
Before discarding an individual content draft, Kibo eCommerce recommends previewing the draft first in order to know what you're discarding.
To discard a specific content draft:
1. Go to **Main** > **Storefront** > **Drafts**.
2. Select the relevant site from the context switcher at the top of the page.
You need to know which site you made changes to in order to view the pending content drafts for that site only.
3. From the **Drafts** grid, select the **Content** tab.
4. Select a draft and then click **Discard Drafts** from the selection list.
### Content Publishing Best Practices
Establish a standard operating procedure or hierarchy for publishing since multiple users and roles have **Publish** permissions.
Without a well-defined workflow, it's possible for multiple users to make different content changes to the same page.
## Product Drafts
The product publishing service enables you to make draft changes to products in the master catalog before publishing them in live mode. For each master catalog associated with a tenant, you can set the product publishing mode to either live or pending.
### Pending Mode
When a master catalog is in pending mode, Kibo eCommerce creates a draft version of all new and changed products. The draft version increments the product changes until they are published or discarded. If products have pending changes, you must publish or discard the drafts before you can switch the master catalog product publishing mode to live.
#### Publishing Product Overrides
When you make updates that override product content for a specific catalog, Kibo eCommerce creates a draft version of the product in all catalogs associated with the master catalog. When publishing the pending changes, the product changes only apply to the overridden catalog. By default, the storefront does not display pending product changes; however, you can modify the request using the Kibo eCommerce API to view the pending product draft.
### Live Mode
When the master catalog product publishing mode is live, Kibo eCommerce immediately publishes all changes to products in the catalog. The live version of the product appears on the website, except when previewing the website in pending mode.
### Product Publishing Tasks
From the Product tab on the Drafts page, you can perform the following tasks:
* [Publish Individual Product Draft](#publish-individual-product-draft)
* [Publish Multiple Product Drafts](#publish-multiple-product-drafts)
* [Discard Individual Product Draft](#discard-individual-product-draft)
* [Product Publishing Best Practices](#product-publishing-best-practices)
### Publish Individual Product Draft
To publish an individual product draft in a specific catalog:
1. Go to **Main** > **Storefront** > **Drafts**.
2. Select the relevant catalog from the context switcher at the top of the page.
You need to know which catalog(s) the product was assigned to during creation.
3. From the **Drafts** grid, select the **Product** tab.
4. Select a draft and then click **Publish Now** from the selection list.
### Publish Multiple Product Drafts
If you wish to publish multiple product drafts at once, Kibo eCommerce recommends moving the product drafts into a Publish Set and then either publishing the Publish Set immediately or specifying a future date to publish the Publish Set.
You can also select multiple product drafts in the **Drafts** grid, and then select **Publish Now** from the selection list.
Refer to [Publish Sets](/pages/publish-sets) for more information about using Publish Sets.
### Discard Individual Product Draft
To discard a specific product draft:
1. Go to **Main** > **Storefront** > **Drafts**.
2. Select the relevant catalog from the context switcher at the top of the page.
You need to know which catalog(s) the product was assigned to during creation.
3. From the **Drafts** grid, select the **Product** tab.
4. Select a draft and then click **Discard Drafts** from the selection list.
### Product Publishing Best Practices
If your product publishing settings are set to **Staged** rather than **Live**, establish a standard operating procedure or hierarchy for publishing.
If one user saves a new product to staging while another user is actively discarding the current product updates for that site, some products may inadvertently be deleted. If a new product was never published, it will disappear completely from Admin and cannot be recovered.
The following workflow helps prevent you from permanently deleting a product before it can be published:
1. When creating a new product, complete all required fields and set the product's **Status** to **Disabled**.
2. Immediately publish the product.
3. Make any necessary, additional changes to the product.
4. Set the product to **Active**, and resubmit it for publishing.
Setting a product to **Disabled** and publishing it ensures that the product is created before it can be deleted. Then once the product's details are complete, you can set the product to **Active** so that it appears on your site.
**Scheduled** products will work the same way as Active products even if they are not yet displayed on the storefront per the scheduled start date. They will follow the [Publishing Settings](/pages/publishing-settings) and be placed into a draft if set to Staged. However, Kibo recommends that you publish these products before or on their scheduled start date in order to take maximum advantage of their available duration.
Refer to [Products](/pages/product-attributes-overview) for more information about managing products, including scheduling behavior.
# Dropship Overview
Source: https://docs.kibocommerce.com/pages/dropship-overview
# **Kibo Commerce Conceptual Guide: Dropship**
## **1. Strategic Overview**
**Concept Definition**
Dropship is the Kibo Commerce capability that lets operators expand their assortment by routing customer orders directly to onboarded third-party vendors who ship to the end customer — without the operator holding the inventory.
**Business Context**
Dropship is delivered as a native, pre-integrated module on the Kibo platform. It adds dedicated vendor management capabilities to the existing Operator Portal (Kibo Admin) — invitation, document review, item mapping, contract pricing, location mapping, and shipping configuration — and introduces a Vendor Portal where third-party suppliers self-onboard, configure fulfillment locations, and process the orders routed to them.
**Value Drivers**
1. **Catalog expansion without inventory risk:** Operators widen their assortment with vendor-sourced SKUs shipped directly to the customer, with zero upfront inventory investment, while preserving fulfillment quality through the same Kibo OMS that handles owned-inventory orders.
2. **Native, pre-integrated capability:** Dropship runs on the same data model, routing engine, inventory service, and pricing services as the rest of the platform — removing the lag, reconciliation errors, and integration overhead of a separate dropship system, and lowering total cost of ownership.
3. **Predictable, auditable vendor operations:** A configurable onboarding journey, document review, item mapping with contract pricing, and a deterministic two-step fulfillment workflow combine with SLA indicators, capacity limits, and an immutable activity log to deliver consistent execution across a heterogeneous vendor network.
**Scope Statement**
* **In Scope:** Platform prerequisites; the two-portal model; the vendor lifecycle and onboarding stepper; document verification; vendor user management (invite, resend, edit role, and delete users in the Vendor Portal; resend vendor invitations in the Operator Portal);item mapping with contracted pricing; operator-side location mapping; vendor roles; the Locations module (operating hours, cut-off times, override hours, capacity, attributes); the vendor shipping mode and in-portal label generation; the Order Module; the two-step Fulfillment Workflow; the Order Details page; and the EDI message set used in Dropship integrations.
* **Explicitly Excluded:** API endpoint specifications, JSON payloads, UI walkthroughs, screenshots, Kibo Admin routing-engine internals, EDI Orderful platform configuration, payment/refund processing, and theme-level customization.
## **2. Core Concepts Explained**
### **What is Dropship?**
Dropship operates across two surfaces. The **Operator Portal** (Kibo Admin) gains vendor management, document review, item mapping, contract pricing, location mapping, and the vendor shipping-mode setting. The **Vendor Portal** is a separate, vendor-facing interface where each vendor self-onboards, configures fulfillment locations, and processes routed orders.
An order travels through the system as follows. A customer places an order on the operator's storefront. The Kibo order routing engine evaluates eligible locations — owned and dropship-vendor — against the routing strategy, operating hours, cut-offs, attributes, and capacity limits, and creates a shipment per fulfillment node. A shipment assigned to a vendor location appears in that vendor's Order Module as an incoming order; the vendor-facing PO Number and order id equals the operator's Kibo Admin shipment number, so the record is trackable from both sides. The vendor then runs the order through the two-step Dropship workflow — Order Acknowledgement (Step 1) and Prepare Shipments / ASN (Step 2) — and the operator sees real-time progress on the corresponding shipment in Kibo Admin.
### **Why does Dropship matter?**
1. **Operational:** A configurable document set and in-app review let vendors go live without out-of-band email. Vendor locations participate in the same routing engine, inventory service, and SLA framework as owned locations — no parallel system to operate or reconcile.
2. **Financial:** Contracted pricing on every item mapping makes vendor invoices reflect negotiated cost, not storefront price. Capacity limits guard against overcommitment, and SLA indicators expose late-fulfillment risk at the order-list level.
3. **Customer experience:** A unified routing engine over owned and third-party inventory gives consistent availability and delivery promises. A deterministic two-step workflow, partial-fulfillment branching, multi-package shipments with per-slip tracking, and a full audit log deliver traceable fulfillment across a heterogeneous vendor network.
### **When to deploy Dropship?**
1. **Catalog expansion add-on:** A merchant already on Kibo wants incremental revenue without growing inventory exposure; Dropship is added on the existing platform.
2. **System consolidation:** A merchant replacing operational systems adopts Dropship alongside an OMS/commerce replacement, eliminating a separate dropship platform.
### **The Dropship Vendor Lifecycle**
1. **Invitation** — operator creates a vendor record (Vendor Name, invitation email, vendor type). Duplicate names/emails error before the invite is sent.
2. **Onboarding In Progress** — the invited user registers and works through the four-step stepper; operators review documents and map items in parallel.
3. **Active** — operator flips status to Active once requirements are met; orders begin to flow.
4. **Inactive** — operator can deactivate at any time; inactive vendors stop receiving routed orders.
## **3. Functional Components & Configuration Deep Dive**
### **Prerequisites**
Before Dropship can be used, three platform prerequisites must be in place: the DropShipEnabled tenant attribute is enabled by Kibo support; the operator creates a dropship location group with the dropship fulfillment workflow assigned; and the catalog must include the UPCs that vendors will be mapped to. Once these are configured, a vendor reaches **Active** status as soon as at least one item mapping exists and a primary-contact phone number is on record.
### **Component Architecture**
1. **Platform Foundation** — the DropShipEnabled tenant attribute and a dedicated dropship location group with the dropship fulfillment workflow assigned. These activate the module and route vendor-destined shipments into the two-step sequence.
2. **Operator Portal — Vendor Module** — the vendor listing, Invite New Vendor flow, and per-vendor record with three tabs: Overview (vendor information, status control, and the **Mapped Locations** section), Documents, and Item Mapping. The operator also sets the **vendor shipping mode** at Settings → Vendor.
3. **Vendor Portal** — three modules: Onboarding (four-step stepper), Locations (Location, Hours, Cut-Off Times, Attributes), and Orders (summary cards, list, fulfillment workflow, order details).
4. **Fulfillment Workflow** — a deterministic two-step sequence on every order: Step 1 (Order Acknowledgement and stock validation, with partial-fulfillment branching) and Step 2 (Prepare Shipments / ASN, packing slips, tracking, invoice). In Step 2 the shipping experience branches on the vendor shipping mode — label generation on the operator's carrier accounts, or manual tracking entry.
### **Configuration-Level Deep Dive**
#### **Vendor Invitation Fields (Operator Portal)**
| **Attribute** | **Business Purpose** | **Impact and Trade-offs** | **Concrete Example** |
| :------------------- | :--------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------- |
| Vendor Name | Identifies the vendor across both portals; search key in the vendor listing. | A duplicate name throws an error before the invitation is sent. | ”Portlynk Solution” is set as the Vendor Name. |
| Vendor Type | Classifies the vendor for routing and reporting. | All vendors route through the dropship fulfillment workflow. | The Vendor Type dropdown shows only “Dropship”. |
| User Email to Invite | Destination for the invitation email containing the registration link. | A duplicate throws an error. Becomes the vendor’s primary admin login. | The operator enters the vendor’s onboarding contact email. |
#### **Onboarding Step 1 — Basic Corporate Information**
The vendor captures three groups of information in this step: Company Information (Company Name, Legal Business Name, Tax ID/EIN, Business Type, Website, Company Description, Founded Year, Number of Employees range), Business Address (Street Address, City, State/Province, ZIP/Postal Code, Country), and Contact Information (Primary Contact Name, Primary Contact Email, Primary Contact Phone, Billing Email, Support Email). The Primary Contact Phone is mandatory for operator-side activation — without it, the vendor cannot be marked Active. The email used during invitation is non-editable on the registration screen.
#### **Item Mapping & Contracted Pricing (Operator Portal)**
Maps the operator's UPC to the Vendor SKU and stores the Contracted Price (the cost the operator pays — not the storefront price). At least one mapping is required before activation; the contract price drives vendor-facing order items and invoices.
#### **Mapped Locations (Operator Portal).**
On the Overview tab, lists every location a vendor can fulfill from, with a running count. Operators **Add Location** from a searchable, multi-select modal (effective immediately, no approval) and **Remove** via a confirmation that warns when active orders exist (in-progress orders are unaffected; new orders stop routing there). The relationship is **bidirectional**: operator-added locations appear in the Vendor Portal automatically, and vendor-created locations appear here automatically.
#### **Locations & Fulfillment Settings (Vendor Portal).**
Each location captures basic information, address (with latitude/longitude for routing), and contact. Fulfillment settings include **Processing Times** (feed EDD and the SLA timer) and **Capacity Limits** (max orders/day; once reached the location is skipped in routing). **Operating Hours** and **Cut-Off Times** are time-zone-scoped and feed routing and EDD; Cut-Off Times also support holiday/maintenance overrides.
| Attribute | Business Purpose | Impact / Trade-off | Example |
| :--------------- | :-------------------------------- | :--------------------------------------------- | :----------------------- |
| Processing Times | Hours to process before shipping. | Feeds EDD and SLA timer. | 24h standard processing. |
| Capacity Limits | Max orders/day per location. | At cap, the location is not routed new orders. | Capped at 250/day. |
#### **Vendor Shipping Mode & Label Generation (Operator Portal setting + Vendor Portal Step 2)**
A single tenant-level setting (Settings → Vendor) selects how vendors ship; it defaults to **vendor-managed** (manual tracking). In **operator-managed** mode, vendors generate shipping labels in the portal using the operator's carrier accounts, with manual tracking as a fallback. Carriers, predefined packages, and unit type are read from the **Location Group** tagged to the vendor location.
| Attribute | Business Purpose | Impact / Trade-off | Example |
| :------------------------------ | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| Vendor Shipping Mode | Tenant setting ("Allow vendors to use operator carrier accounts"). | Defaults OFF (vendor-managed): vendors enter tracking only. ON (operator-managed): Print Shipping Label with tracking fallback. Stored once per tenant. | Operator turns ON tenant-wide to ship on negotiated FedEx/UPS rates. |
| Carrier & Package Inheritance | Resolves carriers, predefined packages, and unit type from the tagged Location Group. | Keeps operator-branded shipping (FROM = operator location) and confines vendors to approved carriers. | Dallas group exposes FedEx/UPS + Small/Medium/Large boxes. |
| Package / Weight / Units | Vendor selects a package or enters dimensions; weight manual; units from the group. | Predefined package locks L×W×H; no predefined packages → manual editable dimensions; weight always manual; vendor cannot change units. | Vendor picks "Medium Box"; dimensions auto-fill and lock. |
| Carrier & Service Pre-Selection | Honors the order's checkout shipping method. | Carrier/service pre-selected from shipping method; vendor can override within configured options; service filtered by carrier. | "2-Day" pre-selects FedEx 2Day. |
| Label & Tracking Capture | Generates the label and records tracking. | Carrier API called with operator account; PDF label produced; tracking captured automatically (no manual entry). One label per packing slip; reprint returns the same label; edit creates a new label + new tracking. | Two-box order has Shipping Label 1 and 2, each with its own tracking. |
**Order Page.**
The canonical record of an order. Header shows Order ID, placement timestamp, and actions (Cancel Order, Download Invoice, Start Fulfillment). Tabs: **Order Items** (contract price, qty, discount, adjustment, total + price breakdown); **Canceled Items** (conditional; product, qty canceled, reason); **Shipping** (carrier, delivery-status badge, tracking, Track Package per packing slip — auto-captured from the label in operator-managed mode, or the manually entered number in vendor-managed mode); **Activity** (reverse-chronological timeline); **Invoice** (preview + download).
**Activation Mechanics.** To flip a vendor to Active: at least one Item Mapping must exist, and a Primary Contact phone number must be on record. The dropship location group with its workflow assignment must also exist, or vendor fulfillment will not route.
## **4. Key Capabilities and Business Applications**
### **Self-Service Vendor Onboarding via a Configurable Stepper**
A newly invited vendor is guided through Basic Corporate Information, Add Users, Business Verification, and Integration Setup, with a right rail showing completion progress. The document set is operator-configurable (title, Required/Optional); rejected documents carry a comment back with the upload re-enabled. Vendors can build locations and platform while document review is in progress, removing the usual onboarding bottleneck.
### **Item Mapping with Contracted Pricing**
Performed operator-side, it bridges the operator UPC to the vendor SKU and captures the contract cost. It gates activation (≥1 mapping required) and drives vendor-facing prices and invoices, distinct from the storefront selling price.
*Example — Electronics retailer:* a smart-lock retails at \$199 but is mapped at a \$90 contracted cost; a two-unit order shows the vendor \$90/unit and a \$180 invoice total, with no markup exposed.
### **Unified Routing Across Owned and Third-Party Inventory**
Vendor locations are exposed to the same routing engine as owned locations and evaluated on proximity, hours, cut-offs, capacity, and routing attributes — no distinction between owned and vendor nodes, so the same scenarios, sort strategies, and assignment preferences apply.
*Example — B2B distributor:* 6 owned warehouses + 25 vendors are evaluated together; a vendor 80 miles away with stock and capacity wins over a distant owned warehouse, preserving owned capacity and avoiding a parallel routing system.
### **Two-Step Fulfillment with Partial-Fulfillment Branching**
Every order flows through Order Acknowledgement (Step 1) and Prepare Shipments / ASN (Step 2). In Step 1 the vendor validates stock; if any quantity is reduced, the row highlights, a banner shows the partial count, and on confirmation the system creates a separate **Canceled order** with the unfulfilled units and reasons while the original proceeds with fulfilled quantities. Reason capture supports apply-to-all, per-product overrides, a defined catalog, and a free-text "Other".
*Example — DTC brand:* a vendor finds 1 of 4 units damaged, reduces to 3, selects "Damaged Or Defective Item"; a one-unit Canceled order is created, the three-unit order ships, and reporting can later quantify damage-driven cancellations.
### **Operator-Managed Location Mapping with Bidirectional Sync**
The Mapped Locations section makes the Vendor Profile the single source of truth for a vendor's fulfillment footprint. Operators map existing Kibo Admin locations via a searchable, multi-select modal and remove them via a guarded confirmation that flags active orders. Mapping/unmapping is immediate with no approval. Vendor-created locations surface to the operator automatically and vice versa, eliminating context-switching between Vendor Management and Location Management.
*Example — Dropship operator:* an operator pre-maps a vendor's two DCs before activation; when the vendor later opens a third warehouse in the portal, it appears in the operator's table automatically.
### **Dual-Mode Shipping — Operator Carrier Labels or Vendor Tracking**
A single tenant-level setting governs shipping. In the default vendor-managed mode, vendors enter tracking numbers. In operator-managed mode, vendors generate labels in Step 2 on the operator's carrier accounts (manual tracking retained as fallback), inheriting carriers, packages, and units from the Location Group. Carrier/service pre-select from the order's shipping method; predefined packages lock dimensions; weight is manual; tracking is captured automatically; one label per packing slip with reprint/edit support.
*Example — Apparel retailer:* the operator enables operator-managed shipping tenant-wide so every dropship parcel ships on negotiated FedEx/UPS rates with operator branding and hands-off tracking; smaller vendors ship at enterprise rates without their own carrier accounts.
## **5. Supported Capabilities & Current Behavior**
**How to read this section.** This guide enumerates the fulfillment capabilities supported by Dropship in the current release. Dropship runs on the same Kibo OMS as owned-inventory fulfillment but intentionally exposes a focused, deterministic subset of it. **Any Kibo OMS fulfillment capability not described in this guide is not part of the current Dropship release.** Where Dropship's behavior differs from the standard OMS workflow, that difference is called out under *Current Behavior Notes*.
**What Dropship supports today**
* **Ship to Home (STH) fulfillment** — Dropship supports Ship to Home (STH) fulfillment: the vendor ships the ordered items directly to the customer's delivery address. BOPIS (customer pickup at vendor location), Delivery, and Transfer fulfillment types are not part of the Dropship vendor workflow.
* **Unified order routing** across owned and vendor locations.
* **Two-step vendor fulfillment** (Order Acknowledgement → Prepare Shipments / ASN).
* **Partial fulfillment** (fulfilled units proceed; see *Current Behavior Notes* for the shortfall).
* **Multi-package shipments** with per-package tracking (manual or label-captured).
* **Operator-managed location mapping** with bidirectional sync.
* **Dual-mode shipping** (operator-managed labels or vendor-managed tracking).
* **SLA visibility** (On Time / At Risk / Overdue), **contracted-price invoicing** (incl. EDI 810), and a **full audit trail**.
**Current Behavior Notes** — intentional design boundaries that differ from the standard OMS workflow:
| Behavior | How Dropship works today | What this means for operators |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cancellation is terminal** | A vendor cancellation or quantity reduction places the affected units in a Canceled order with a reason and closes them permanently — no reassignment to another vendor/owned location, and no Customer Care queue. | Plan around a single-pass model; a cancelled unit is final for that line. Use captured reasons and per-vendor reporting to manage vendor reliability. |
| **Forward fulfillment only** | Dropship supports the forward flow (acknowledge → ship). | Returns and reverse logistics are handled operator-side, outside the vendor portal. The vendor portal does not process returns, RMAs, or refunds. |
| **Stock shortfalls cancel** | Insufficient stock results in reduce-and-cancel of the shortfall. | No product substitution or backorder; the fulfilled quantity ships and the remainder is cancelled per terminal cancellation. |
## **6. Platform Integration Map**
**Upstream Dependencies**
1. **DropShipEnabled tenant attribute** — without it, the vendor module does not appear in Kibo Admin.
2. **Dedicated dropship location group with workflow assignment (BPM)** — without it, vendor shipments do not enter the Acknowledgement → ASN sequence.
3. **Operator catalog with UPCs** — required for item mapping.
4. **Location Group carrier configuration** — in operator-managed shipping, label generation reads carriers, predefined packages, and unit type from the Location Group tagged to each vendor location.
**Downstream Impacts**
1. **Order routing** — vendor hours, cut-offs, override hours, capacity, and routing attributes feed node selection; mapped locations become eligible nodes.
2. **Order lifecycle** — dropship orders flow through the two-step workflow, generating activity-log entries at every transition.
**Synergistic Features**
* **Dropship + Order Routing** — vendor attributes, time-zone hours, cut-offs, and overrides give the engine a rich data set; the same strategies apply to owned and vendor nodes.
* **Dropship + Fulfillment SLAs** — order-level On Time / At Risk / Overdue indicators draw on the platform SLA framework.
* **Dropship + Item Mapping & Contracted Pricing** — produces accurate vendor invoices automatically, eliminating manual reconciliation.
* **Dropship + EDI (850/855/856/810/846)** — for high-volume vendors, fully automated PO, acknowledgement, ASN, invoicing, and inventory exchange on the same lifecycle and audit log.
## **7. Related Conceptual Guides**
* **Locations & Location Groups** — the dropship location group, workflow assignment, and carrier configuration are platform prerequisites.
* **Catalog & Product Attributes** — item mapping requires an operator catalog with UPCs.
* **Order Routing** — vendor location data feeds the routing engine that selects the fulfillment node.
* **Order Fulfillment** — how the two-step workflow expresses itself on the operator-side order record.
* **Inventory** and **EDI & API Integrations** — complementary controls and integration framework for vendor partnerships.
Dropship is delivered as a native, pre-integrated module on the Kibo platform. It adds dedicated vendor management capabilities to the existing Operator Portal (Kibo Admin) — invitation, document review, item mapping, contract pricing, location mapping, and shipping configuration — and introduces a Vendor Portal where third-party suppliers self-onboard, configure fulfillment locations, and process the orders routed to them.
1. **Catalog expansion without inventory risk:** Operators widen their assortment with vendor-sourced SKUs shipped directly to the customer, with zero upfront inventory investment, while preserving fulfillment quality through the same Kibo OMS that handles owned-inventory orders.
2. **Native, pre-integrated capability:** Dropship runs on the same data model, routing engine, inventory service, and pricing services as the rest of the platform — removing the lag, reconciliation errors, and integration overhead of a separate dropship system, and lowering total cost of ownership.
3. **Predictable, auditable vendor operations:** A configurable onboarding journey, document review, item mapping with contract pricing, and a deterministic two-step fulfillment workflow combine with SLA indicators, capacity limits, and an immutable activity log to deliver consistent execution across a heterogeneous vendor network.
* **In Scope:** Platform prerequisites; the two-portal model; the vendor lifecycle and onboarding stepper; document verification; item mapping with contracted pricing; operator-side location mapping; vendor roles; the Locations module (operating hours, cut-off times, override hours, capacity, attributes); the vendor shipping mode and in-portal label generation; the Order Module; the two-step Fulfillment Workflow; the Order Details page; and the EDI message set used in Dropship integrations.
* **Explicitly Excluded:** API endpoint specifications, JSON payloads, UI walkthroughs, screenshots, Kibo Admin routing-engine internals, EDI Orderful platform configuration, payment/refund processing, and theme-level customization.
Dropship operates across two surfaces. The **Operator Portal** (Kibo Admin) gains vendor management, document review, item mapping, contract pricing, location mapping, and the vendor shipping-mode setting. The **Vendor Portal** is a separate, vendor-facing interface where each vendor self-onboards, configures fulfillment locations, and processes routed orders.
An order travels through the system as follows. A customer places an order on the operator's storefront. The Kibo order routing engine evaluates eligible locations — owned and dropship-vendor — against the routing strategy, operating hours, cut-offs, attributes, and capacity limits, and creates a shipment per fulfillment node. A shipment assigned to a vendor location appears in that vendor's Order Module as an incoming order; the vendor-facing PO Number and order id equals the operator's Kibo Admin shipment number, so the record is trackable from both sides. The vendor then runs the order through the two-step Dropship workflow — Order Acknowledgement (Step 1) and Prepare Shipments / ASN (Step 2) — and the operator sees real-time progress on the corresponding shipment in Kibo Admin.
1. **Operational:** A configurable document set and in-app review let vendors go live without out-of-band email. Vendor locations participate in the same routing engine, inventory service, and SLA framework as owned locations — no parallel system to operate or reconcile.
2. **Financial:** Contracted pricing on every item mapping makes vendor invoices reflect negotiated cost, not storefront price. Capacity limits guard against overcommitment, and SLA indicators expose late-fulfillment risk at the order-list level.
3. **Customer experience:** A unified routing engine over owned and third-party inventory gives consistent availability and delivery promises. A deterministic two-step workflow, partial-fulfillment branching, multi-package shipments with per-slip tracking, and a full audit log deliver traceable fulfillment across a heterogeneous vendor network.
4. **Catalog expansion add-on:** A merchant already on Kibo wants incremental revenue without growing inventory exposure; Dropship is added on the existing platform.
5. **System consolidation:** A merchant replacing operational systems adopts Dropship alongside an OMS/commerce replacement, eliminating a separate dropship platform.
6. **Invitation** — operator creates a vendor record (Vendor Name, invitation email, vendor type). Duplicate names/emails error before the invite is sent.
7. **Onboarding In Progress** — the invited user registers and works through the four-step stepper; operators review documents and map items in parallel.
8. **Active** — operator flips status to Active once requirements are met; orders begin to flow.
9. **Inactive** — operator can deactivate at any time; inactive vendors stop receiving routed orders.
### **Prerequisites**
Before Dropship can be used, three platform prerequisites must be in place: the DropShipEnabled tenant attribute is enabled by Kibo support; the operator creates a dropship location group with the dropship fulfillment workflow assigned; and the catalog must include the UPCs that vendors will be mapped to. Once these are configured, a vendor reaches **Active** status as soon as at least one item mapping exists and a primary-contact phone number is on record.
1. **Platform Foundation** — the DropShipEnabled tenant attribute and a dedicated dropship location group with the dropship fulfillment workflow assigned. These activate the module and route vendor-destined shipments into the two-step sequence.
2. **Operator Portal — Vendor Module** — the vendor listing, Invite New Vendor flow, and per-vendor record with three tabs: Overview (vendor information, status control, and the **Mapped Locations** section), Documents, and Item Mapping. The operator also sets the **vendor shipping mode** at Settings → Vendor.
3. **Vendor Portal** — three modules: Onboarding (four-step stepper), Locations (Location, Hours, Cut-Off Times, Attributes), and Orders (summary cards, list, fulfillment workflow, order details).
4. **Fulfillment Workflow** — a deterministic two-step sequence on every order: Step 1 (Order Acknowledgement and stock validation, with partial-fulfillment branching) and Step 2 (Prepare Shipments / ASN, packing slips, tracking, invoice). In Step 2 the shipping experience branches on the vendor shipping mode — label generation on the operator's carrier accounts, or manual tracking entry.
### **Configuration-Level Deep Dive**
#### **Vendor Invitation Fields (Operator Portal)**
| **Attribute** | **Business Purpose** | **Impact and Trade-offs** | **Concrete Example** |
| :------------------- | :--------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------- |
| Vendor Name | Identifies the vendor across both portals; search key in the vendor listing. | A duplicate name throws an error before the invitation is sent. | ”Portlynk Solution” is set as the Vendor Name. |
| Vendor Type | Classifies the vendor for routing and reporting. | All vendors route through the dropship fulfillment workflow. | The Vendor Type dropdown shows only “Dropship”. |
| User Email to Invite | Destination for the invitation email containing the registration link. | A duplicate throws an error. Becomes the vendor’s primary admin login. | The operator enters the vendor’s onboarding contact email. |
#### **Onboarding Step 1 — Basic Corporate Information**
#### **Item Mapping & Contracted Pricing (Operator Portal)**
Maps the operator's UPC to the Vendor SKU and stores the Contracted Price (the cost the operator pays — not the storefront price). At least one mapping is required before activation; the contract price drives vendor-facing order items and invoices.
#### **Mapped Locations (Operator Portal).**
On the Overview tab, lists every location a vendor can fulfill from, with a running count. Operators **Add Location** from a searchable, multi-select modal (effective immediately, no approval) and **Remove** via a confirmation. The relationship is **bidirectional**: operator-added locations appear in the Vendor Portal automatically, and vendor-created locations appear here automatically.
#### **Locations & Fulfillment Settings (Vendor Portal).**
Each location captures basic information, address (with latitude/longitude for routing), and contact. Fulfillment settings include **Processing Times** (feed EDD and the SLA timer) and **Capacity Limits** (max orders/day; once reached the location is skipped in routing). **Operating Hours** and **Cut-Off Times** are time-zone-scoped and feed routing and EDD; Cut-Off Times also support holiday/maintenance overrides.
| Attribute | Business Purpose | Impact / Trade-off | Example |
| :--------------- | :-------------------------------- | :--------------------------------------------- | :----------------------- |
| Processing Times | Hours to process before shipping. | Feeds EDD and SLA timer. | 24h standard processing. |
| Capacity Limits | Max orders/day per location. | At cap, the location is not routed new orders. | Capped at 250/day. |
#### **Vendor Shipping Mode & Label Generation (Operator Portal setting + Vendor Portal Step 2)**
A single tenant-level setting (Settings → Vendor) selects how vendors ship; it defaults to **vendor-managed** (manual tracking). In **operator-managed** mode, vendors generate shipping labels in the portal using the operator's carrier accounts, with manual tracking as a fallback. Carriers, predefined packages, and unit type are read from the **Location Group** tagged to the vendor location.
| Attribute | Business Purpose | Impact / Trade-off | Example |
| :------------------------------ | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| Vendor Shipping Mode | Tenant setting ("Allow vendors to use operator carrier accounts"). | Defaults OFF (vendor-managed): vendors enter tracking only. ON (operator-managed): Print Shipping Label with tracking fallback. Stored once per tenant. | Operator turns ON tenant-wide to ship on negotiated FedEx/UPS rates. |
| Carrier & Package Inheritance | Resolves carriers, predefined packages, and unit type from the tagged Location Group. | Keeps operator-branded shipping (FROM = operator location) and confines vendors to approved carriers. | Dallas group exposes FedEx/UPS + Small/Medium/Large boxes. |
| Package / Weight / Units | Vendor selects a package or enters dimensions; weight manual; units from the group. | Predefined package locks L×W×H; no predefined packages → manual editable dimensions; weight always manual; vendor cannot change units. | Vendor picks "Medium Box"; dimensions auto-fill and lock. |
| Carrier & Service Pre-Selection | Honors the order's checkout shipping method. | Carrier/service pre-selected from shipping method; vendor can override within configured options; service filtered by carrier. | "2-Day" pre-selects FedEx 2Day. |
| Label & Tracking Capture | Generates the label and records tracking. | Carrier API called with operator account; PDF label produced; tracking captured automatically (no manual entry). One label per packing slip; reprint returns the same label; edit creates a new label + new tracking. | Two-box order has Shipping Label 1 and 2, each with its own tracking. |
**Order Page.**
The canonical record of an order. Header shows Order ID, placement timestamp, and actions (Cancel Order, Download Invoice, Start Fulfillment). Tabs: **Order Items** (contract price, qty, discount, adjustment, total + price breakdown); **Canceled Items** (conditional; product, qty canceled, reason); **Shipping** (carrier, delivery-status badge, tracking, Track Package per packing slip — auto-captured from the label in operator-managed mode, or the manually entered number in vendor-managed mode); **Activity** (reverse-chronological timeline); **Invoice** (preview + download).
**Activation Mechanics.** To flip a vendor to Active: at least one Item Mapping must exist, and a Primary Contact phone number must be on record. The dropship location group with its workflow assignment must also exist, or vendor fulfillment will not route.
## **4. Key Capabilities and Business Applications**
### **Self-Service Vendor Onboarding via a Configurable Stepper**
A newly invited vendor is guided through Basic Corporate Information, Add Users, Business Verification, and Integration Setup, with a right rail showing completion progress. The document set is operator-configurable (title, Required/Optional); rejected documents carry a comment back with the upload re-enabled. Vendors can build locations and platform while document review is in progress, removing the usual onboarding bottleneck.
### **Item Mapping with Contracted Pricing**
Performed operator-side, it bridges the operator UPC to the vendor SKU and captures the contract cost. It gates activation (≥1 mapping required) and drives vendor-facing prices and invoices, distinct from the storefront selling price.
*Example — Electronics retailer:* a smart-lock retails at \$199 but is mapped at a \$90 contracted cost; a two-unit order shows the vendor \$90/unit and a \$180 invoice total, with no markup exposed.
### **Unified Routing Across Owned and Third-Party Inventory**
Vendor locations are exposed to the same routing engine as owned locations and evaluated on proximity, hours, cut-offs, capacity, and routing attributes — no distinction between owned and vendor nodes, so the same scenarios, sort strategies, and assignment preferences apply.
*Example — B2B distributor:* 6 owned warehouses + 25 vendors are evaluated together; a vendor 80 miles away with stock and capacity wins over a distant owned warehouse, preserving owned capacity and avoiding a parallel routing system.
### **Two-Step Fulfillment with Partial-Fulfillment Branching**
Every order flows through Order Acknowledgement (Step 1) and Prepare Shipments / ASN (Step 2). In Step 1 the vendor validates stock; if any quantity is reduced, the row highlights, a banner shows the partial count, and on confirmation the system creates a separate **Canceled order** with the unfulfilled units and reasons while the original proceeds with fulfilled quantities. Reason capture supports apply-to-all, per-product overrides, a defined catalog, and a free-text "Other".
*Example — DTC brand:* a vendor finds 1 of 4 units damaged, reduces to 3, selects "Damaged Or Defective Item"; a one-unit Canceled order is created, the three-unit order ships, and reporting can later quantify damage-driven cancellations.
### **Operator-Managed Location Mapping with Bidirectional Sync**
The Mapped Locations section makes the Vendor Profile the single source of truth for a vendor's fulfillment footprint. Operators map existing Kibo Admin locations via a searchable, multi-select modal and remove them via a guarded confirmation that flags active orders. Mapping/unmapping is immediate with no approval. Vendor-created locations surface to the operator automatically and vice versa, eliminating context-switching between Vendor Management and Location Management.
*Example — Dropship operator:* an operator pre-maps a vendor's two DCs before activation; when the vendor later opens a third warehouse in the portal, it appears in the operator's table automatically.
### **Dual-Mode Shipping — Operator Carrier Labels or Vendor Tracking**
A single tenant-level setting governs shipping. In the default vendor-managed mode, vendors enter tracking numbers. In operator-managed mode, vendors generate labels in Step 2 on the operator's carrier accounts (manual tracking retained as fallback), inheriting carriers, packages, and units from the Location Group. Carrier/service pre-select from the order's shipping method; predefined packages lock dimensions; weight is manual; tracking is captured automatically; one label per packing slip with reprint/edit support.
*Example — Apparel retailer:* the operator enables operator-managed shipping tenant-wide so every dropship parcel ships on negotiated FedEx/UPS rates with operator branding and hands-off tracking; smaller vendors ship at enterprise rates without their own carrier accounts.
## **5. Supported Capabilities & Current Behavior**
**How to read this section.** This guide enumerates the fulfillment capabilities supported by Dropship in the current release. Dropship runs on the same Kibo OMS as owned-inventory fulfillment but intentionally exposes a focused, deterministic subset of it. **Any Kibo OMS fulfillment capability not described in this guide is not part of the current Dropship release.** Where Dropship's behavior differs from the standard OMS workflow, that difference is called out under *Current Behavior Notes*.
**What Dropship supports today**
* **Ship to Home (STH) fulfillment** — Dropship supports Ship to Home (STH) fulfillment: the vendor ships the ordered items directly to the customer's delivery address. BOPIS (customer pickup at vendor location), Delivery, and Transfer fulfillment types are not part of the Dropship vendor workflow.
* **Unified order routing** across owned and vendor locations.
* **Two-step vendor fulfillment** (Order Acknowledgement → Prepare Shipments / ASN).
* **Partial fulfillment** (fulfilled units proceed; see *Current Behavior Notes* for the shortfall).
* **Multi-package shipments** with per-package tracking (manual or label-captured).
* **Operator-managed location mapping** with bidirectional sync.
* **Dual-mode shipping** (operator-managed labels or vendor-managed tracking).
* **SLA visibility** (On Time / At Risk / Overdue), **contracted-price invoicing** (incl. EDI 810), and a **full audit trail**.
**Current Behavior Notes** — intentional design boundaries that differ from the standard OMS workflow:
| Behavior | How Dropship works today | What this means for operators |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cancellation is terminal** | A vendor cancellation or quantity reduction places the affected units in a Canceled order with a reason and closes them permanently — no reassignment to another vendor/owned location, and no Customer Care queue. | Plan around a single-pass model; a cancelled unit is final for that line. Use captured reasons and per-vendor reporting to manage vendor reliability. |
| **Forward fulfillment only** | Dropship supports the forward flow (acknowledge → ship). | Returns and reverse logistics are handled operator-side, outside the vendor portal. The vendor portal does not process returns, RMAs, or refunds. |
| **Stock shortfalls cancel** | Insufficient stock results in reduce-and-cancel of the shortfall. | No product substitution or backorder; the fulfilled quantity ships and the remainder is cancelled per terminal cancellation. |
## **6. Platform Integration Map**
**Upstream Dependencies**
1. **DropShipEnabled tenant attribute** — without it, the vendor module does not appear in Kibo Admin.
2. **Dedicated dropship location group with workflow assignment (BPM)** — without it, vendor shipments do not enter the Acknowledgement → ASN sequence.
3. **Operator catalog with UPCs** — required for item mapping.
4. **Location Group carrier configuration** — in operator-managed shipping, label generation reads carriers, predefined packages, and unit type from the Location Group tagged to each vendor location.
**Downstream Impacts**
1. **Order routing** — vendor hours, cut-offs, override hours, capacity, and routing attributes feed node selection; mapped locations become eligible nodes.
2. **Order lifecycle** — dropship orders flow through the two-step workflow, generating activity-log entries at every transition.
**Synergistic Features**
* **Dropship + Order Routing** — vendor attributes, time-zone hours, cut-offs, and overrides give the engine a rich data set; the same strategies apply to owned and vendor nodes.
* **Dropship + Fulfillment SLAs** — order-level On Time / At Risk / Overdue indicators draw on the platform SLA framework.
* **Dropship + Item Mapping & Contracted Pricing** — produces accurate vendor invoices automatically, eliminating manual reconciliation.
* **Dropship + EDI (850/855/856/810/846)** — for high-volume vendors, fully automated PO, acknowledgement, ASN, invoicing, and inventory exchange on the same lifecycle and audit log.
## **7. Related Conceptual Guides**
* **Locations & Location Groups** — the dropship location group, workflow assignment, and carrier configuration are platform prerequisites.
* **Catalog & Product Attributes** — item mapping requires an operator catalog with UPCs.
* **Order Routing** — vendor location data feeds the routing engine that selects the fulfillment node.
* **Order Fulfillment** — how the two-step workflow expresses itself on the operator-side order record.
* **Inventory** and **EDI & API Integrations** — complementary controls and integration framework for vendor partnerships.
Dropship is delivered as a native, pre-integrated module on the Kibo platform. It adds dedicated vendor management capabilities to the existing Operator Portal (Kibo Admin) — invitation, document review, item mapping, contract pricing, location mapping, and shipping configuration — and introduces a Vendor Portal where third-party suppliers self-onboard, configure fulfillment locations, and process the orders routed to them.
1. **Catalog expansion without inventory risk:** Operators widen their assortment with vendor-sourced SKUs shipped directly to the customer, with zero upfront inventory investment, while preserving fulfillment quality through the same Kibo OMS that handles owned-inventory orders.
2. **Native, pre-integrated capability:** Dropship runs on the same data model, routing engine, inventory service, and pricing services as the rest of the platform — removing the lag, reconciliation errors, and integration overhead of a separate dropship system, and lowering total cost of ownership.
3. **Predictable, auditable vendor operations:** A configurable onboarding journey, document review, item mapping with contract pricing, and a deterministic two-step fulfillment workflow combine with SLA indicators, capacity limits, and an immutable activity log to deliver consistent execution across a heterogeneous vendor network.
* **In Scope:** Platform prerequisites; the two-portal model; the vendor lifecycle and onboarding stepper; document verification; item mapping with contracted pricing; operator-side location mapping; vendor roles; the Locations module (operating hours, cut-off times, override hours, capacity, attributes); the vendor shipping mode and in-portal label generation; the Order Module; the two-step Fulfillment Workflow; the Order Details page; and the EDI message set used in Dropship integrations.
* **Explicitly Excluded:** API endpoint specifications, JSON payloads, UI walkthroughs, screenshots, Kibo Admin routing-engine internals, EDI Orderful platform configuration, payment/refund processing, and theme-level customization.
Dropship operates across two surfaces. The **Operator Portal** (Kibo Admin) gains vendor management, document review, item mapping, contract pricing, location mapping, and the vendor shipping-mode setting. The **Vendor Portal** is a separate, vendor-facing interface where each vendor self-onboards, configures fulfillment locations, and processes routed orders.
An order travels through the system as follows. A customer places an order on the operator's storefront. The Kibo order routing engine evaluates eligible locations — owned and dropship-vendor — against the routing strategy, operating hours, cut-offs, attributes, and capacity limits, and creates a shipment per fulfillment node. A shipment assigned to a vendor location appears in that vendor's Order Module as an incoming order; the vendor-facing PO Number and order id equals the operator's Kibo Admin shipment number, so the record is trackable from both sides. The vendor then runs the order through the two-step Dropship workflow — Order Acknowledgement (Step 1) and Prepare Shipments / ASN (Step 2) — and the operator sees real-time progress on the corresponding shipment in Kibo Admin.
1. **Operational:** A configurable document set and in-app review let vendors go live without out-of-band email. Vendor locations participate in the same routing engine, inventory service, and SLA framework as owned locations — no parallel system to operate or reconcile.
2. **Financial:** Contracted pricing on every item mapping makes vendor invoices reflect negotiated cost, not storefront price. Capacity limits guard against overcommitment, and SLA indicators expose late-fulfillment risk at the order-list level.
3. **Customer experience:** A unified routing engine over owned and third-party inventory gives consistent availability and delivery promises. A deterministic two-step workflow, partial-fulfillment branching, multi-package shipments with per-slip tracking, and a full audit log deliver traceable fulfillment across a heterogeneous vendor network.
4. **Catalog expansion add-on:** A merchant already on Kibo wants incremental revenue without growing inventory exposure; Dropship is added on the existing platform.
5. **System consolidation:** A merchant replacing operational systems adopts Dropship alongside an OMS/commerce replacement, eliminating a separate dropship platform.
6. **Invitation** — operator creates a vendor record (Vendor Name, invitation email, vendor type). Duplicate names/emails error before the invite is sent.
7. **Onboarding In Progress** — the invited user registers and works through the four-step stepper; operators review documents and map items in parallel.
8. **Active** — operator flips status to Active once requirements are met; orders begin to flow.
9. **Inactive** — operator can deactivate at any time; inactive vendors stop receiving routed orders.
### **Prerequisites**
Before Dropship can be used, three platform prerequisites must be in place: the DropShipEnabled tenant attribute is enabled by Kibo support; the operator creates a dropship location group with the dropship fulfillment workflow assigned; and the catalog must include the UPCs that vendors will be mapped to. Once these are configured, a vendor reaches **Active** status as soon as at least one item mapping exists and a primary-contact phone number is on record.
1. **Platform Foundation** — the DropShipEnabled tenant attribute and a dedicated dropship location group with the dropship fulfillment workflow assigned. These activate the module and route vendor-destined shipments into the two-step sequence.
2. **Operator Portal — Vendor Module** — the vendor listing, Invite New Vendor flow, and per-vendor record with three tabs: Overview (vendor information, status control, and the **Mapped Locations** section), Documents, and Item Mapping. The operator also sets the **vendor shipping mode** at Settings → Vendor.
3. **Vendor Portal** — three modules: Onboarding (four-step stepper), Locations (Location, Hours, Cut-Off Times, Attributes), and Orders (summary cards, list, fulfillment workflow, order details).
4. **Fulfillment Workflow** — a deterministic two-step sequence on every order: Step 1 (Order Acknowledgement and stock validation, with partial-fulfillment branching) and Step 2 (Prepare Shipments / ASN, packing slips, tracking, invoice). In Step 2 the shipping experience branches on the vendor shipping mode — label generation on the operator's carrier accounts, or manual tracking entry.
### **Configuration-Level Deep Dive**
#### **Vendor Invitation Fields (Operator Portal)**
| **Attribute** | **Business Purpose** | **Impact and Trade-offs** | **Concrete Example** |
| :------------------- | :--------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------- |
| Vendor Name | Identifies the vendor across both portals; search key in the vendor listing. | A duplicate name throws an error before the invitation is sent. | ”Portlynk Solution” is set as the Vendor Name. |
| Vendor Type | Classifies the vendor for routing and reporting. | All vendors route through the dropship fulfillment workflow. | The Vendor Type dropdown shows only “Dropship”. |
| User Email to Invite | Destination for the invitation email containing the registration link. | A duplicate throws an error. Becomes the vendor’s primary admin login. | The operator enters the vendor’s onboarding contact email. |
#### **Onboarding Step 1 — Basic Corporate Information**
#### **Item Mapping & Contracted Pricing (Operator Portal)**
Maps the operator's UPC to the Vendor SKU and stores the Contracted Price (the cost the operator pays — not the storefront price). At least one mapping is required before activation; the contract price drives vendor-facing order items and invoices.
#### **Mapped Locations (Operator Portal).**
On the Overview tab, lists every location a vendor can fulfill from, with a running count. Operators **Add Location** from a searchable, multi-select modal (effective immediately, no approval) and **Remove** via a confirmation. The relationship is **bidirectional**: operator-added locations appear in the Vendor Portal automatically, and vendor-created locations appear here automatically.
#### **Locations & Fulfillment Settings (Vendor Portal).**
Each location captures basic information, address (with latitude/longitude for routing), and contact. Fulfillment settings include **Processing Times** (feed EDD and the SLA timer) and **Capacity Limits** (max orders/day; once reached the location is skipped in routing). **Operating Hours** and **Cut-Off Times** are time-zone-scoped and feed routing and EDD; Cut-Off Times also support holiday/maintenance overrides.
| Attribute | Business Purpose | Impact / Trade-off | Example |
| :--------------- | :-------------------------------- | :--------------------------------------------- | :----------------------- |
| Processing Times | Hours to process before shipping. | Feeds EDD and SLA timer. | 24h standard processing. |
| Capacity Limits | Max orders/day per location. | At cap, the location is not routed new orders. | Capped at 250/day. |
#### **Vendor Shipping Mode & Label Generation (Operator Portal setting + Vendor Portal Step 2)**
A single tenant-level setting (Settings → Vendor) selects how vendors ship; it defaults to **vendor-managed** (manual tracking). In **operator-managed** mode, vendors generate shipping labels in the portal using the operator's carrier accounts, with manual tracking as a fallback. Carriers, predefined packages, and unit type are read from the **Location Group** tagged to the vendor location.
| Attribute | Business Purpose | Impact / Trade-off | Example |
| :------------------------------ | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| Vendor Shipping Mode | Tenant setting ("Allow vendors to use operator carrier accounts"). | Defaults OFF (vendor-managed): vendors enter tracking only. ON (operator-managed): Print Shipping Label with tracking fallback. Stored once per tenant. | Operator turns ON tenant-wide to ship on negotiated FedEx/UPS rates. |
| Carrier & Package Inheritance | Resolves carriers, predefined packages, and unit type from the tagged Location Group. | Keeps operator-branded shipping (FROM = operator location) and confines vendors to approved carriers. | Dallas group exposes FedEx/UPS + Small/Medium/Large boxes. |
| Package / Weight / Units | Vendor selects a package or enters dimensions; weight manual; units from the group. | Predefined package locks L×W×H; no predefined packages → manual editable dimensions; weight always manual; vendor cannot change units. | Vendor picks "Medium Box"; dimensions auto-fill and lock. |
| Carrier & Service Pre-Selection | Honors the order's checkout shipping method. | Carrier/service pre-selected from shipping method; vendor can override within configured options; service filtered by carrier. | "2-Day" pre-selects FedEx 2Day. |
| Label & Tracking Capture | Generates the label and records tracking. | Carrier API called with operator account; PDF label produced; tracking captured automatically (no manual entry). One label per packing slip; reprint returns the same label; edit creates a new label + new tracking. | Two-box order has Shipping Label 1 and 2, each with its own tracking. |
**Order Page.**
The canonical record of an order. Header shows Order ID, placement timestamp, and actions (Cancel Order, Download Invoice, Start Fulfillment). Tabs: **Order Items** (contract price, qty, discount, adjustment, total + price breakdown); **Canceled Items** (conditional; product, qty canceled, reason); **Shipping** (carrier, delivery-status badge, tracking, Track Package per packing slip — auto-captured from the label in operator-managed mode, or the manually entered number in vendor-managed mode); **Activity** (reverse-chronological timeline); **Invoice** (preview + download).
**Activation Mechanics.** To flip a vendor to Active: at least one Item Mapping must exist, and a Primary Contact phone number must be on record. The dropship location group with its workflow assignment must also exist, or vendor fulfillment will not route.
## **4. Key Capabilities and Business Applications**
### **Self-Service Vendor Onboarding via a Configurable Stepper**
A newly invited vendor is guided through Basic Corporate Information, Add Users, Business Verification, and Integration Setup, with a right rail showing completion progress. The document set is operator-configurable (title, Required/Optional); rejected documents carry a comment back with the upload re-enabled. Vendors can build locations and platform while document review is in progress, removing the usual onboarding bottleneck.
### **Item Mapping with Contracted Pricing**
Performed operator-side, it bridges the operator UPC to the vendor SKU and captures the contract cost. It gates activation (≥1 mapping required) and drives vendor-facing prices and invoices, distinct from the storefront selling price.
*Example — Electronics retailer:* a smart-lock retails at \$199 but is mapped at a \$90 contracted cost; a two-unit order shows the vendor \$90/unit and a \$180 invoice total, with no markup exposed.
### **Unified Routing Across Owned and Third-Party Inventory**
Vendor locations are exposed to the same routing engine as owned locations and evaluated on proximity, hours, cut-offs, capacity, and routing attributes — no distinction between owned and vendor nodes, so the same scenarios, sort strategies, and assignment preferences apply.
*Example — B2B distributor:* 6 owned warehouses + 25 vendors are evaluated together; a vendor 80 miles away with stock and capacity wins over a distant owned warehouse, preserving owned capacity and avoiding a parallel routing system.
### **Two-Step Fulfillment with Partial-Fulfillment Branching**
Every order flows through Order Acknowledgement (Step 1) and Prepare Shipments / ASN (Step 2). In Step 1 the vendor validates stock; if any quantity is reduced, the row highlights, a banner shows the partial count, and on confirmation the system creates a separate **Canceled order** with the unfulfilled units and reasons while the original proceeds with fulfilled quantities. Reason capture supports apply-to-all, per-product overrides, a defined catalog, and a free-text "Other".
*Example — DTC brand:* a vendor finds 1 of 4 units damaged, reduces to 3, selects "Damaged Or Defective Item"; a one-unit Canceled order is created, the three-unit order ships, and reporting can later quantify damage-driven cancellations.
### **Operator-Managed Location Mapping with Bidirectional Sync**
The Mapped Locations section makes the Vendor Profile the single source of truth for a vendor's fulfillment footprint. Operators map existing Kibo Admin locations via a searchable, multi-select modal and remove them via a guarded confirmation that flags active orders. Mapping/unmapping is immediate with no approval. Vendor-created locations surface to the operator automatically and vice versa, eliminating context-switching between Vendor Management and Location Management.
*Example — Dropship operator:* an operator pre-maps a vendor's two DCs before activation; when the vendor later opens a third warehouse in the portal, it appears in the operator's table automatically.
### **Dual-Mode Shipping — Operator Carrier Labels or Vendor Tracking**
A single tenant-level setting governs shipping. In the default vendor-managed mode, vendors enter tracking numbers. In operator-managed mode, vendors generate labels in Step 2 on the operator's carrier accounts (manual tracking retained as fallback), inheriting carriers, packages, and units from the Location Group. Carrier/service pre-select from the order's shipping method; predefined packages lock dimensions; weight is manual; tracking is captured automatically; one label per packing slip with reprint/edit support.
*Example — Apparel retailer:* the operator enables operator-managed shipping tenant-wide so every dropship parcel ships on negotiated FedEx/UPS rates with operator branding and hands-off tracking; smaller vendors ship at enterprise rates without their own carrier accounts.
## **5. Supported Capabilities & Current Behavior**
**How to read this section.** This guide enumerates the fulfillment capabilities supported by Dropship in the current release. Dropship runs on the same Kibo OMS as owned-inventory fulfillment but intentionally exposes a focused, deterministic subset of it. **Any Kibo OMS fulfillment capability not described in this guide is not part of the current Dropship release.** Where Dropship's behavior differs from the standard OMS workflow, that difference is called out under *Current Behavior Notes*.
**What Dropship supports today**
* **Ship to Home (STH) fulfillment** — Dropship supports Ship to Home (STH) fulfillment: the vendor ships the ordered items directly to the customer's delivery address. BOPIS (customer pickup at vendor location), Delivery, and Transfer fulfillment types are not part of the Dropship vendor workflow.
* **Unified order routing** across owned and vendor locations.
* **Two-step vendor fulfillment** (Order Acknowledgement → Prepare Shipments / ASN).
* **Partial fulfillment** (fulfilled units proceed; see *Current Behavior Notes* for the shortfall).
* **Multi-package shipments** with per-package tracking (manual or label-captured).
* **Operator-managed location mapping** with bidirectional sync.
* **Dual-mode shipping** (operator-managed labels or vendor-managed tracking).
* **SLA visibility** (On Time / At Risk / Overdue), **contracted-price invoicing** (incl. EDI 810), and a **full audit trail**.
**Current Behavior Notes** — intentional design boundaries that differ from the standard OMS workflow:
| Behavior | How Dropship works today | What this means for operators |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cancellation is terminal** | A vendor cancellation or quantity reduction places the affected units in a Canceled order with a reason and closes them permanently — no reassignment to another vendor/owned location, and no Customer Care queue. | Plan around a single-pass model; a cancelled unit is final for that line. Use captured reasons and per-vendor reporting to manage vendor reliability. |
| **Forward fulfillment only** | Dropship supports the forward flow (acknowledge → ship). | Returns and reverse logistics are handled operator-side, outside the vendor portal. The vendor portal does not process returns, RMAs, or refunds. |
| **Stock shortfalls cancel** | Insufficient stock results in reduce-and-cancel of the shortfall. | No product substitution or backorder; the fulfilled quantity ships and the remainder is cancelled per terminal cancellation. |
## **6. Platform Integration Map**
**Upstream Dependencies**
1. **DropShipEnabled tenant attribute** — without it, the vendor module does not appear in Kibo Admin.
2. **Dedicated dropship location group with workflow assignment (BPM)** — without it, vendor shipments do not enter the Acknowledgement → ASN sequence.
3. **Operator catalog with UPCs** — required for item mapping.
4. **Location Group carrier configuration** — in operator-managed shipping, label generation reads carriers, predefined packages, and unit type from the Location Group tagged to each vendor location.
**Downstream Impacts**
1. **Order routing** — vendor hours, cut-offs, override hours, capacity, and routing attributes feed node selection; mapped locations become eligible nodes.
2. **Order lifecycle** — dropship orders flow through the two-step workflow, generating activity-log entries at every transition.
**Synergistic Features**
* **Dropship + Order Routing** — vendor attributes, time-zone hours, cut-offs, and overrides give the engine a rich data set; the same strategies apply to owned and vendor nodes.
* **Dropship + Fulfillment SLAs** — order-level On Time / At Risk / Overdue indicators draw on the platform SLA framework.
* **Dropship + Item Mapping & Contracted Pricing** — produces accurate vendor invoices automatically, eliminating manual reconciliation.
* **Dropship + EDI (850/855/856/810/846)** — for high-volume vendors, fully automated PO, acknowledgement, ASN, invoicing, and inventory exchange on the same lifecycle and audit log.
## **7. Related Conceptual Guides**
* **Locations & Location Groups** — the dropship location group, workflow assignment, and carrier configuration are platform prerequisites.
* **Catalog & Product Attributes** — item mapping requires an operator catalog with UPCs.
* **Order Routing** — vendor location data feeds the routing engine that selects the fulfillment node.
* **Order Fulfillment** — how the two-step workflow expresses itself on the operator-side order record.
* **Inventory** and **EDI & API Integrations** — complementary controls and integration framework for vendor partnerships.
# Retrieve EDI 850 Purchase Order (After)
Source: https://docs.kibocommerce.com/pages/dropship-purchase-order-after
**Related API:** This extension modifies the [Retrieve EDI 850 Purchase Order](/api-reference/dropship/retrieve-edi-850-purchase-order) operation.
This action manipulates the HTTP request or response after the Retrieve EDI 850 Purchase Order operation occurs in Kibo. The Retrieve EDI 850 Purchase Order operation is read-only, so use this action to inspect the request or to transform the response before it is returned.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.dropship.purchaseOrder.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Retrieve EDI 850 Purchase Order](/api-reference/dropship/retrieve-edi-850-purchase-order) operation.
**HTTP Request**
GET `api/commerce/dropship/purchaseorder/{shipmentNumber}`
**Request Body**\
No request body content.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Retrieve EDI 850 Purchase Order (Before)
Source: https://docs.kibocommerce.com/pages/dropship-purchase-order-before
**Related API:** This extension modifies the [Retrieve EDI 850 Purchase Order](/api-reference/dropship/retrieve-edi-850-purchase-order) operation.
This action manipulates the HTTP request or response before the Retrieve EDI 850 Purchase Order operation occurs in Kibo. The Retrieve EDI 850 Purchase Order operation is read-only, so use this action to inspect the request or to transform the response before it is returned.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.dropship.purchaseOrder.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Retrieve EDI 850 Purchase Order](/api-reference/dropship/retrieve-edi-850-purchase-order) operation.
**HTTP Request**
GET `api/commerce/dropship/purchaseorder/{shipmentNumber}`
**Request Body**\
No request body content.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Translate Shipment (After)
Source: https://docs.kibocommerce.com/pages/dropship-translate-after
**Related API:** This extension modifies the [Translate Shipment](/api-reference/dropship/translate-shipment) operation.
This action manipulates the HTTP request or response after the Translate Shipment operation occurs in Kibo. The Translate Shipment operation is read-only, so use this action to inspect the request or to transform the response before it is returned.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.dropship.translate.after |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Translate Shipment](/api-reference/dropship/translate-shipment) operation.
**HTTP Request**
GET `api/commerce/dropship/translate/{shipmentNumber}`
**Request Body**\
No request body content.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Translate Shipment (Before)
Source: https://docs.kibocommerce.com/pages/dropship-translate-before
**Related API:** This extension modifies the [Translate Shipment](/api-reference/dropship/translate-shipment) operation.
This action manipulates the HTTP request or response before the Translate Shipment operation occurs in Kibo. The Translate Shipment operation is read-only, so use this action to inspect the request or to transform the response before it is returned.
| Action Type | [HTTP](/pages/types-of-actions) |
|---|
| Full Action ID | http.commerce.dropship.translate.before |
|---|
| Runs multiple custom functions? | Yes |
|---|
## JavaScript File Structure
Action files share the following basic structure:
```
module.exports = function(context, callback) {
// Your custom code here
callback();
};
```
When you code the custom function for an action, you have access to two arguments:
`callback`—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).
`context`—This argument provides the function access to relevant objects and methods that interface with Kibo.
## Context: HTTP
The methods and objects documented here are available to this action through the use of the `context` argument.
**REST API Operation**\
This action corresponds to the [Translate Shipment](/api-reference/dropship/translate-shipment) operation.
**HTTP Request**
GET `api/commerce/dropship/translate/{shipmentNumber}`
**Request Body**\
No request body content.
**Response Body**\
Use `context.response.body` to write the HTTP response body using this action.
## Context Objects Available to All HTTP Actions
### request
Accesses the current HTTP request. In the case of Before actions, updates can be made to the request before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------ |
| params | object | The input parameters to the service or webpage. |
| headers | object | The request headers. |
| method | string | The request method. |
| url | string | The request URL. |
| path | string | The request path. |
| cookies | object | The request cookies. \*Available only for Storefront HTTP actions. |
| query | object | The request query. |
| href | string | The request href. |
| secure | Boolean | Indicates whether the request uses HTTPS. |
| ip | string | The request IP address. |
| ips | string | The request secure IP address. |
| body | object | The request body of the API operation associated with this action. |
Example:
```
context.request.url;
```
### response
Accesses the current HTTP response. For both Before and After actions, updates can be made to the response before Kibo eCommerce processes it.
| Property | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| header | object | The response header collection. |
| viewData | object | The viewData collection used by the storefront rendering engine. \*Available only for Storefront HTTP actions. |
| viewName | string | The response viewName value. \*Available only for Storefront HTTP actions. |
| body | object | The response body of the API operation associated with this action. |
| status | integer | The response status code. |
| message | string | The response message. |
| length | integer | The response length. |
| type | string | The response type. |
Example:
```
context.response.header;
```
## Context Methods Available to All HTTP Actions
### request.get
Returns an HTTP header value for the specified header key.
| Parameter | Type | Description |
| --------- | ------ | --------------- |
| key | string | The header key. |
Example:
```
context.request.get(field);
```
Response:
```
"object"
```
### response.get
Gets a field from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| key | object | The field to obtain. |
Example:
```
context.response.get(field);
```
Response:
```
"string"
```
### response.set
Sets the HTTP headers for the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| values | object | The values for the HTTP headers. |
Example:
```
context.response.set({ myCustomHeader: "howdy" });
```
Response: N/A
### response.set2
Updates a field in the response.
| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| key | string | The key of the field. |
| value | string | The value of the field. |
Example:
```
context.response.set("name", "stuff");
```
Response: N/A
### response.remove
Removes an HTTP header from the response.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| key | string | The HTTP header to remove. |
Example:
```
context.response.remove(header);
```
Response: N/A
### response.redirect
Redirects the incoming URL.
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| url | string | The destination URL. |
Example:
```
context.response.redirect("http://someOtherSite/foo");
```
Response: N/A;
### response.end
Ends the response so that other actions or Kibo eCommerce logic can run. Also, signals the callback to complete.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.response.end();
```
Response: N/A
### get.resource
Returns the currently persisted value of the requested resource. \*\*Not available for all calls.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resource();
```
Response: N/A
### get.resourceStatus
Gets the HTTP resource status.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| N/A | N/A | N/A |
Example:
```
context.get.resourceStatus();
```
Response: N/A
### items.urlHelper.getUrl
Gets the current URL.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| type | | |
| object | | |
| config | | |
Example:
```
context.items.urlHelper.getUrl(type, object, config);
```
## Context Objects Available to All Actions
### apiContext
Accesses Kibo eCommerce tenant information.
| Property | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | string | The base URL for the site. |
| basePciUrl | string | The base PCI URL for the site. |
| tenantPod | string | The name of the tenant pod in which the tenant resides. |
| appClaims | string | The application claims token. |
| appKey | string | The application key. |
| tenantId | integer | Unique identifier for the tenant. |
| siteId | integer | Unique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site. |
| masterCatalogId | integer | Unique identifier for the master catalog. |
| catalogId | integer | The unique identifier for the product catalog. Catalogs are part of a master catalog. |
| currencyCode | string | The default three-letter ISO currency code for monetary amounts. |
| previewDate | date/time | The date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future. |
| localeCode | string | The locale code per the country code provided. This code determines the localized content to use and display. |
| correlationId | string | The unique identifier of the API request associated with the event action, which might contain multiple actions. |
| isAuthorizedAsAdmin | Boolean | Indicates whether the Dev Account user is authorized as an admin. |
| userClaims | string | The user claims token. |
Example:
```
context.apiContext.baseUrl;
```
### configuration
Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------- |
| Varies | object | Custom fields and values that you can set in the Action Management JSON Editor. |
Example:
```
context.configuration.customData;
```
# Dynamic Categories
Source: https://docs.kibocommerce.com/pages/dynamic-categories
Dynamic categories allow you to specify dynamic [expressions](/pages/dynamic-category-expressions) that control the products that belong to them.
Learn how to create and manage dynamic categories
For example, you want to create a category that contains all products that have been in your catalog for 30 days or less. You can create a dynamic category that specifies to include all products that have been in your catalog for 30 days or less.
## Dynamic Category Types
There are two types of dynamic categories:
* [Dynamic precomputed](#precomputed_categories): The product membership is calculated when products are indexed in the catalog.
* [Dynamic realtime](#realtime_categories): The product membership is calculated in realtime and on demand when a shopper navigates to the realtime category page.
Refer to the following table for more information about the differences between the two types of dynamic categories:
| Feature | Dynamic Precomputed | Dynamic Realtime |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------- |
| Can have products statically assigned | No | No |
| Can have child categories | No | No |
| Can have products assigned via a membership expression | Yes | Yes |
| Can evaluate a product's Sale Price and Sale Price Type (price after discount applied) as part of membership expression | No | Yes |
| Can evaluate catalog list prices as part of the membership expression | Yes | Yes |
| Can evaluate product properties as part of the membership expression | Yes | Yes |
| Can be created using variant properties | No | No |
| Navigating to a parent category displays products included in the child category | Yes | No |
| Can be used as target criteria for a discount | Yes | No |
| Becomes a complex search filter at runtime | No | Yes |
### Precomputed Categories
The product membership of precomputed categories is calculated when products are indexed in the catalog, such as when products are added, updated, or deleted from the catalog, and also when the categories themselves are updated, such as when their expressions change.
For example, you have a precomputed category that includes all products that have a property of red, and you currently have a red dress in your catalog. This red dress is included in your precomputed category; however, if you removed the property of red from the dress and saved the change, this dress would be removed from the precomputed category when you save the change. Note that precomputed categories can reference other precomputed categories; however, Kibo eCommerce recommends limiting the amount of precomputed categories the parent precomputed category references.
### Realtime Categories
The product membership of realtime categories is calculated in realtime and on demand when a shopper navigates to the realtime category. When the shopper navigates to the realtime category, Kibo eCommerce performs a query for products in the catalog that should be included in the category. This allows Kibo eCommerce to evaluate dynamic product fields such as product pricing after discounts have been applied.
For example, you have a realtime category that includes all products that have a discounted sale price, and you currently have a discount on all dresses. When a shopper navigates to this realtime category, Kibo eCommerce performs a query to identify the products that have a discounted sale price, and it finds the dresses that are discounted. These dresses then appear on the realtime category page. Note that you cannot target realtime categories for discounts.
## Specify Dynamic Category Type
The **Product Membership** field controls whether the dynamic category is precomputed or realtime.
To specify a precomputed dynamic category, set the **Product Membership** field to **Precomputed**.
To specify a realtime dynamic category, set the **Product Membership** field to **Realtime**.
## Create Dynamic Categories
To create a new dynamic category:
1. Go to **Main** > **Sell** > **Categories**.
2. Select **Create New Category** > **Dynamic Category**.
3. Enter a **Category Name**. This name will display on your storefront, and is the only required field.
4. Complete the **Description** field. The description field is not visible to your shoppers initially; however, you can make it visible depending on your theme. Use these fields to help a user understand what products they’ll find in this category.
5. Set a **Category Code** if desired. If left blank, a code will be generated for you.
6. Select a **Status** for the category: Active, Disabled, or Scheduled. If you select Scheduled, then the options to select an **Active Start Date** and **Active End Date** will appear.
7. If you are creating a new sub-category, select the **Parent Categor\*\*\*\*y.**
8. Determine whether the dynamic category is precomputed or realtime using the **Product Membership** drop-down menu. The **Product Membership** drop-down menu controls the dynamic category type and its behaviors. Refer to [Dynamic Category Types](#dynamic_category_types) for more information about the two types of dynamic categories.
9. Determine whether to hide the category on your storefront with the **Hide category on store front** checkbox. This is useful if you have a seasonal category that should only display at certain times of the year.
10. Create an expression to define the product membership of the category.
You can either manually create the expression, or use the visual expression builder to create the expression. Refer to [Dynamic Category Expressions](/pages/dynamic-category-expressions) for more information about manually or visually creating dynamic category expressions.
11. Select a **Category Image**.
12. Use the available fields to enter SEO information:
| Field Name | SEO Effect | | | | | |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ | - | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SEO Friendly URL | The default URL structure for products is `yourSite.com/{slug}/p/{productCode}` and for categories is `yourSite.com/{slug}/c/{categoryId}`. The slug (or SEO-friendly URL) gives you the ability to add a meaningful component to the URL structure in order to boost search results. | | | | | |
| Page Title | By default, this value is not used by Kibo eCommerce. However, your theme developer has access to this value through a Hypr variable, so with minor theme changes, you can expose a different page title on your storefront than the title you supply for the meta title. | | | | | |
| Meta Title | Maps to the HTML meta title tag. While most search engines place little value on this tag, most Kibo eCommerce themes inject the value of the meta title tag into the HTML title tag. | | | | | |
| The HTML title tag is used by search engines and browsers to display the title of the page, and is critical to SEO. Search engines place very high importance on the correlation between a page's title tag and its content. | | Meta Description | Maps to the HTML meta description tag, which is used by search engines to summarize the content of the page. | | Keywords | Maps to the HTML meta keywords tag, which is used to tell search engines what the page is about. From an SEO-perspective, search engines place little value on this tag, but the Kibo eCommerce search implementation uses these keywords to help construct search results for pages on your storefront. |
13. If desired, click **Create New Merchandizing Rules** to open another tab and create a [merchandizing rule](/pages/merchandizing-rules) to control your product ranking in this category. Any merchandizing rules that are added to this category will be displayed in a table, where you can edit or delete them by expanding its action menu on the right.
14. If you have enabled [multiple locales for this catalog](/pages/multi-locale-catalogs "Multi-Locale Catalogs"), you can switch locales using the dropdown menu in the top right. This allows you to localize the category name, description, meta information, and SEO for that language. The category code, merchandizing rules, category attributes, and other settings will not be displayed or editable, as those are only configurable on the default locale for the catalog.
15. Click **Save**.
If you view the dynamic category on your Staged site, the default sort order may be different than the default sort order on your Live site. This is because the Staged site may be using a different default sort by value than your Live site. Your Live site's default sort by value is determined by your theme. You can confirm the products that are included in both the Staged and Live versions of the dynamic category by clicking **Preview** under the **Expression** section. Refer to [Preview the Expression Results](/pages/dynamic-category-expressions#preview-the-expression-results) for more information about previewing the dynamic category expression results.
## Duplicate Dynamic Categories
You can duplicate categories to quickly create new categories that are based on existing ones.
To duplicate a category:
1. Go to **Main** > **Sell** > **Categories**.
2. Expand the actions menu next to a category.
3. Select **Duplicate**.
You can then edit the duplicated category to meet your needs.
## Disable Dynamic Categories
You can temporarily or permanently disable categories so that they can't be used in various contexts and are filtered out of default views within Admin.
To disable a category:
1. Go to **Main** > **Sell** > **Categories**.
2. Select the applicable category you want to disable.
3. In the **Status** drop-down menu, select **Disabled**.
Keep the following in mind when you disable a category:
* The category disappears from the default view in the Category grid in Admin.
* **Subcategories**—Subcategories of the disabled category are also disabled. When creating child categories, if you select a disabled category as the child category's parent, then the child category is disabled and is read-only until you either set the parent category as active or remove the parent category from the child category.
* **Storefront**—If the disabled category was previously shown on the storefront, the category is automatically removed from storefront navigation. Navigating directly to the category URL is subject to your existing URL routes and/or URL redirects. If you don't have any routes or redirects defined, then navigating to the category URL either in your live storefront or staging preview returns a 404 error code.
* **Discounts**—If the disabled category was previously targeted by a discount, the products in it are no longer eligible for the discount.
* **Admin Category Pickers**—Disabled categories are displayed in category pickers in Admin, but are marked as *Disabled*.
* **Dynamic Categories**—If you disable a dynamic category, the previewing the dynamic expression results still displays associated products correctly. If you reference a disabled category in a dynamic expression, the expression evaluates as if the disabled category does not exist.
## Schedule Categories
You can schedule child categories by specifying a time period in which they will be displayed on the storefront, rather than manually setting a category as active or disabled.
For instance, you may want a "Halloween Decor" category to be displayed only in the weeks leading up to Halloween. You would set the appropriate start and end date in the category settings, and Halloween Decor would then be automatically activated and deactivated on the storefront at those dates.
### Schedule Settings
Whether you are creating a new category or editing an existing one, the **Status** dropdown in the category configurations will display a “Scheduled” option. Selecting this status will then allow you set a **Start Date** and **End Date** (including a time) as shown below.
If no end date is scheduled, then the category will still be displayed on the required start date. The end date will be considered “indefinite” and so the category will remain visible until either an end date is set or it is manually disabled.
When scheduling categories, be aware of the following behaviors:
* If products in the category are also scheduled but their dates do not align with the category’s dates, then the product will not be displayed.
* If there are no products in the category, then the empty category will still be displayed on the storefront during that scheduled period.
* If you are scheduling a parent category that contains sub-categories, then the sub-categories will only be displayed on the storefront when the scheduled parent category is also displayed.
### Viewing Scheduled Categories
Once configured, the category will be displayed in the table with the Scheduled status.
You can show or hide the additional Start Date and End Date columns, which are hidden by default. Expand the menu in the top right of the table to select the column display options.
You can also use the search bar's Advanced Filter option to search for categories in the Scheduled status (as well as filter by start or end date), or directly input a query for scheduled categories. For example:
* To retrieve any scheduled categories, use *?filter=activeStartDate ne null OR activeEndDate ne null*
* To retrieve categories scheduled for a specific period, in this case from June 24 to June 30, use *?filter=activeStartDate gt 2021-06-24T18:01:00-0500 AND activeEndDate lt 2021-06-30T18:01:00-0500*
### API Integration
The [Category API](/api-overviews/openapi_catalog_admin_overview) contains fields for `status`, `activeDateStart`, and `activeDateEnd`. This allows you to add, update, and retrieve scheduled category information via API instead of UI.
A [category.updated event](/pages/event-subscription) will fire when any configured start or end date is reached, triggering the activation or deactivation of the category on the storefront.
## Preview Dynamic Categories
You can preview category pages on the storefront, though this is only supported for Active categories (not Disabled or Scheduled). Previewing a category page is handy if you want to view how the category displays your site and how the products assigned to the category, whether statically or dynamically, appear on the category page.
Even though there is no "publish" setting for categories and they cannot be added to publish sets, the ability to preview that category for a future date in staging does allow for elements (such as products that may have a set Publish Date) to be previewed. For example, a user may want to see what a category called Dresses looks like between December 1 and December 31, in the future where a lot of products that are party dresses will be set to go live.
You can only preview category pages (which determine the look and feel of categories), not the categories themselves. When you create or edit a category, the changes take effect immediately, meaning that you can't stage category data or edit categories and preview them before the product data is updated.
To preview a category page:
1. Go to **Main** > **Catalog** > **Categories**.
2. Expand the actions menu next to a category.
3. Select **View Staged** > **Site**.
# Dynamic Category Expressions
Source: https://docs.kibocommerce.com/pages/dynamic-category-expressions
The dynamic category expression controls the product membership of the dynamic category. You can find the expression of a dynamic category in the **Expression** section on a dynamic category page.
Learn how to create and manage dynamic categories
You can create and edit the dynamic category expression either using the visual expression builder or the advanced expression editor. If you choose to use the visual expression builder, you'll need to create containers and filters using dialog boxes in Admin. If you choose to use the advanced expression editor to create and edit the expression you'll need to write either a JSON styled tree, or write a plain text string.
Refer to following sections for more information about either manually writing the dynamic category expressions, or using the visual expression builder.
## Visual Expression Builder
The visual expression builder allows you to visually create groups and conditions that specify the details of your expression. A group specifies whether any or all of the conditions within it need to evaluate as True in order for products to be added to the dynamic category. A condition contains an expression field, an operator, and a value, for example *Product code is equal to BLUE-SHIRT*.
### Add a Group
To add a group:
1. Under the **Expression** section, expand the actions menu and select **Add Group**.
2. Specify whether **Any** or **All** of the conditions in the container must be True by clicking **Edit**. **Any** acts like an or, and **All** acts like an and. For example, you have a condition that includes the categories Prada and Women's. If you specify **Any**, any products that belong to the Prada or the Women's category will be included in the dynamic category. However, if you specify **All**, only products that belong to both the Prada and Women's categories will be included in the dynamic category.
For example, you add a group that includes four conditions and allow any of the conditions to be True.
### Add a Condition
To add a condition:
1. Under the **Expression** section, expand the actions for the applicable group and select **Add Condition**.
2. Select a condition **Field**.
3. Select an **Operator**.
4. Specify a **Value**.
For example, you want the dynamic category to include any product with a list price of \$50. To accomplish this, you create a condition that states *List price is equal to \$50*. Some fields allow for null, or no values. The asterisk on the **Value** drop-down menu determines whether the selected field requires a value. For example, you can create a condition that states *Sale price has no value*.
### Add an Existing Condition to a Group
To add an already existing condition to a group, click and drag the condition into the desired group.
## Advanced Expression Editor
The advanced expression editor allows you to manually write either JSON equivalent text or plain text to create the expression.
To create or edit an expression manually:
1. In the **Expression** section, click **Advanced**.
2. In the Advanced Edit Expression window, select either the **JSON** view or the **Text** view to write your expression.
## Preview the Expression Results
Before saving the dynamic category, you can preview the results of the expression. This gives you the opportunity to view the products that will be included in the dynamic category before saving the category. When previewing the results of the expression, you can specify the site and either the Live or Staged version of the site.
If your product publishing settings are set to **Live** for a catalog, you can only preview the live matching results. To view both the live and staged matching results, you need to set your product publishing settings to **Staged**. Refer to [Publishing Settings](/pages/publishing-settings) for more information about setting your product publishing settings.
Only products that appear on your storefront are returned in the preview expression results. If, for whatever reason, including out of stock, a product does not appear on your storefront either currently or on the staged preview date then it will not appear in either the live or staged preview expression results.
To preview the results of an expression:
1. Under the **Expression** section, click **Preview**.
2. In the **Preview Expression** modal, the results of the expression are shown in the **Preview** grid on the right.
3. Select the **Site** you wish to preview products for as well as the site's **State**. **Tip:** If you select **Staged** as the site's state, you can specify the date you wish to preview. This allows you to preview the products that will be included in the dynamic category on the specified date.
4. If the product results do not match your desired results, you can edit the expression using the **Expression** frame on the left.
5. If you edit the expression in the **Preview Expression** modal and you wish to save your changes, click **Done**. Otherwise, click **Cancel** to disregard any changes and close the **Preview Expression** modal.
The total matched results are shown in the bottom-right corner of the **Preview** grid. You can use this total to quickly determine whether your expression meets your desired criteria.
## Expression Fields
When you write a dynamic category expression, you define values for the supported fields in order to build out the expression.
Refer to the following table for the supported expression fields and their operators:
### Precomputed and Realtime Categories
| Field | Supported Operators | Data Type | Allow Null Values? |
| ---------------------------- | ------------------- | --------- | ------------------ |
| **Visual Expression Editor** | | | |
| Product code | | | |
**Manual Editor**\
ProductCode | EQ (is equal to)\
NE (does not equal)\
IN (is one of the following) | String | No |
\| **Visual Expression Editor**\
Product name
**Manual Editor**\
ProductName | EQ (is equal to)\
CONT (contains)\
NE (does not equal) | String | No |
\| **Visual Expression Editor**\
Category code
**Manual Editor**\
Categories.CategoryCode (Precomputed categories can reference other precomputed categories; however, Kibo eCommerce recommends limiting the amount of precomputed categories the parent precomputed category references.) | EQ (is equal to)\
REQ (is equal to and includes child categories)\
NE (does not equal)\
IN (is one of the following, does not recursively include selected child categories). | String | No |
\| **Visual Expression Editor**\
Product Type
**Manual Editor**\
ProductTypeId | EQ (is equal to)\
NE (does not equal)\
IN (is one of the following) | Integer | No |
\| **Visual Expression Editor**\
List price
**Manual Editor**\
Price.CatalogListPrice | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | No |
\| **Visual Expression Editor**\
Sale price
**Manual Editor**\
Price.CatalogSalePrice (This field refers to the sale price of a product entered on the product page in Admin.) | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | Yes |
\| **Visual Expression Editor**\
Days available in catalog
**Manual Editor**\
DaysAvailableInCatalog
This field is calculated using the **First Available Date** field in the product properties. | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Integer | No |
\| **Visual Expression Editor**\
Fulfillment types supported
**Manual Editor**\
FulfillmentTypes\
Supported | EQ (is equal to)\
NE (does not equal)\
IN (is one of the following) |
String\
Valid values: "DirectShip", "InStorePickup", "Digital"
\| No |
\| **Visual Expression Editor**\
Weight
**Manual Editor**\
Measurements.Package\
Weight.Value | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | Yes |
\| **Visual Expression Editor**\
Height
**Manual Editor**\
Measurements.Package\
Height.Value | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | Yes |
\| **Visual Expression Editor**\
Width
**Manual Editor**\
Measurements.Package\
Width.Value | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | Yes |
\| **Visual Expression Editor**\
Length
**Manual Editor**\
Measurements.Package\
Length.Value | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | Yes |
\| **Visual Expression Editor**\
Attribute Property
**Manual Editor**\
properties.
This field is based on the available product properties and uses the fully-qualified name (FQN) of the property. | The supported operators of this field are dependent on the selected property. | The value of this field is dependent on the selected property's value. | Yes |
### Realtime Categories Only
| Field | Supported Operators | Data Type | Allow Null Values? |
| ---------------------------- | ------------------- | --------- | ------------------ |
| **Visual Expression Editor** | | | |
| Post-Discount Price | | | |
**Manual Editor**\
Price.SalePrice (this field refers to the post discount price of a product.) | EQ (is equal to)\
NE (does not equal)\
LT (is less than)\
LE (is less than or\
equal to)\
GT (is greater than)\
GE (is greater than or\
equal to)\
IN (is one of the following) | Decimal | Yes |
\| **Visual Expression Editor**\
Sale Type
**Manual Editor**\
Price.SaleType | EQ (is equal to)\
NE (does not equal)\
IN (is one of the following) |
String\
Valid values:\
Catalog Sale Price\
Discounted List Price\
Discounted Catalog Sale Price
Refer to [Sale Type Values](#sale-type-values) for more information about these values.
\| Yes |
#### Sale Type Values
The realtime sale type field has three different values that each apply to a product's various sale types: Catalog Sale Price, Discounted List Price, and Discounted Catalog Sale Price. Refer to the following table for more information about each of these values and their relationship to a product's various sale prices.
| Value | Description |
| ---------------------------- | ----------- |
| **Visual Expression Editor** | |
| Catalog Sale Price | |
**Manual Editor**\
CatalogSalePrice | The price specified in a product's **Sale Price** field. |
\| **Visual Expression Editor**\
Discounted List Price
**Manual Editor**\
DiscountedList | The product's list price after applicable discounts are applied. |
\| **Visual Expression Editor**\
Discounted Catalog Sale Price
**Manual Editor**\
DiscountedCatalogSalePrice | The price specified in a product's **Sale Price** field after applicable discounts are applied. |
## Expression Examples
These four examples provide visual builder and advanced editor samples for different expressions.
### Example 1
The following example shows a precomputed dynamic category expression that includes all products that have been in the catalog for 30 days or less:
#### Visual Expression Builder
#### Advanced Editor: Tree View
```
{
"type": "container",
"logicalOperator": "or",
"nodes": [
{
"type": "predicate",
"left": "daysavailableincatalog",
"right": 30,
"operator": "le"
}
]
}
```
#### Advanced Editor: Text View
```
daysavailableincatalog le 30
```
### Example 2
The following example shows a precomputed dynamic category expression that includes all products with the property color set to red:
#### Visual Expression Builder
#### Advanced Editor: Tree View
```
{
"type": "container",
"logicalOperator": "or",
"nodes": [
{
"type": "predicate",
"left": "properties.tenant~color",
"operator": "eq",
"right": "Red"
}
]
}
```
#### Advanced Editor: Text View
```
properties.color eq "Red"
```
### Example 3
The following example shows a precomputed dynamic category expression that includes all products with the property color set to red and are in the apparel category.
#### Visual Expression Builder
#### Advanced Editor: Tree View
```
{
"type": "container",
"logicalOperator": "and",
"nodes": [
{
"type": "predicate",
"left": "Categories.CategoryCode",
"operator": "eq",
"right": "apparel"
},
{
"type": "predicate",
"left": "properties.color",
"operator": "eq",
"right": "Red"
}
]
}
```
#### Advanced Editor: Text View
```
Categories.CategoryCode eq "apparel" and properties.color eq "red"
```
### Example 4
The following example shows a realtime dynamic category expression that includes all products with a discounted sale price and are in the apparel category. You must set the **Product Membership** drop-down menu to **Realtime** in order to access the dynamic realtime fields.
#### Visual Expression Builder
#### Advanced Editor: Tree View
```
{
"type": "container",
"logicalOperator": "and",
"nodes": [
{
"type": "container",
"logicalOperator": "and",
"nodes": [
{
"type": "predicate",
"left": "Price.SaleType",
"operator": "eq",
"right": "DiscountedList"
},
{
"type": "predicate",
"left": "Categories.CategoryCode",
"operator": "eq",
"right": "apparel"
}
]
}
]
}
```
#### Advanced Editor: Text View
```
(Price.SaleType eq "DiscountedList" and Categories.CategoryCode eq "apparel")
```
# Dynamic Imaging
Source: https://docs.kibocommerce.com/pages/dynamic-imaging
The Dynamic Imaging feature allows flexibility in configuring which images are displayed for product variants, both on the storefront product page and in the search results. In the standard image management process, you can add images to the File Manager through admin and then upload them to a product when editing the product's settings or upload them from your computer. However, the order in which the images are added determines the order in which they are displayed on the product detail page and you cannot customize which images were associated with certain product variants without developer theme work.
On the other hand, Dynamic Imaging associates an image with an option value of the product, allowing it to appear in specific search results and be displayed on the product page for the customer. Multiple images can be grouped together and associated with the same option value as part of an image group, allowing you to customize which images the customer sees as they click through the different variants of your product. For example, products with multiple color variations can have a particular set of images associated with each option. When a customer selects an option, such as "black," then the appropriate black variant image will be displayed. While the customer is viewing the product's page, selecting between "black" and "blue" options will update the displayed images to match the chosen variant.
This efficient image management tool supports:
* Adding image groups to a product and having multiple sets of images
* Selecting specific options (such as color) to have specific image groups
* Easily viewing the option images assigned to a product
* Assigning default images to display on the base product when a variant has not been specified
Enabling this feature requires the core theme updates found at this [GitHub link](https://github.com/Mozu/core-theme/commit/885a87dbad3fee2994a8d54eb055858236316d15).
## How to Use Dynamic Imaging
### Enable Dynamic Imaging for a Product
Dynamic Imaging is enabled on the individual product level, allowing you to use this flexible image management for more complex products while using the basic image tool for others.
1. Go to **Catalog** > **Products** and click the product you wish to upload images for.
2. For configurable products, scroll down to the Images section or click the quick link on the Product page. When Dynamic Imaging is not in effect, this section appears as shown below:
3. Select the **Assign images to Options** checkbox to begin using Dynamic Imaging for that particular product. When selected, all existing product images will now be part of the default group. For more information, see the following section titled [Default Groups](#default-groups).
### Create an Image Group
Once enabled, you can start creating image groups associated with the available product variants. Images can belong to more than one image group, and will display when the conditions for the option values are selected on the storefront.
All image organization is done through these groups. If only one image needs to be associated with a variant, then you should create a group that consists of just that one image.
1. Select a product option from the dropdown next to the enabled checkbox. Only one option can be selected at a time. If switched all image groups will be removed and need to be recreated.
2. Click **Create Image Group**.
3. Give the group a unique code. For example, if you are creating a group for a certain color variant then you may want to name the group after that color.
4. Select the option values that these images will be associated with from the dropdown.
A group can be associated with multiple option values, which means that the uploaded images will be displayed for each of those variants. These option values come from the inherited product, so if you want to add new options then you need to [create and apply them in the catalog](/pages/option-attributes "Option Attributes").
5. Upload images from either the Computer or File Manager.
6. Click **Update** to finish creating the group.
### Edit an Existing Image Group
Image groups that have already been created will appear in a table when a product option is selected in the Images section.
1. Select an option from the dropdown list next to the checkbox. In the below example, there are various image groups for the "Color" product option. Each corresponds with a different color variant.
2. Click on a group's row in the table or select **Edit** from the drop-down menu on the right.
3. A menu similar to that of creating a new image group appears. Change the group code, remove images, or add images as needed.
The group cannot be associated under a new option value through Edit. If you wish to change the option value of a group or add another value to it, you will have to create a new group.
## Default Groups
There is one default group that is automatically created for each product by eCommerce and cannot be deleted – this contains all images that an existing product had before the implementation of Dynamic Imagery. More images can be added to this group and will display when the product does not have option-specific images or when they are base product images that should display when an option value is not selected.
The below example is of a product that just had Dynamic Imaging enabled for the first time. Although no image groups have been created by the user yet, the default group was generated and visible once a product option is selected.
## Images in Overridden Catalogs
If images are overridden in specific sub-catalogs, image groups can have a set of images that only display in those sub-catalogs. To enable:
1. Go to **Catalog** > **Products** and click on a product to edit it.
2. Click the sub-catalog name in the header.
3. Select the override flag that now appears in the edit view.
If the override flag is later deselected, then all changes from the override will be lost and images will need to be added back to image groups when it is re-enabled.
# EDI Reference
Source: https://docs.kibocommerce.com/pages/edi-reference
Vendors who choose EDI Integration during onboarding exchange data with the Kibo platform via the EDI Orderful trading-partner platform. Dropship uses the following standard EDI message types:
See the Dropship API documentation for EDI 850 generation and shipment translation
| **Message** | **Type** | **Direction** | **Purpose** |
| :---------- | :----------------------------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 850 | Purchase Order | Operator to Vendor | Communicates a new purchase order (a customer order routed to the vendor). |
| 855 | Purchase Order Acknowledgement | Vendor to Operator | Confirms receipt of the purchase order and signals the vendor's intent to fulfill. |
| 856 | Advance Shipping Notice (ASN) | Vendor to Operator | Notifies the operator that the shipment has been packed and is ready to ship, including tracking and packaging information. |
| 846 | Inventory Inquiry / Advice | Vendor to Operator | Communicates current inventory levels at the vendor's location(s) so the operator's order routing engine has up-to-date availability |
| 810 | Invoice | Vendor to Operator | Communicates the vendor's bill for the items shipped. Creates a Payment Invoice record in Kibo for reconciliation against the shipment. Does not complete the shipment or advance the fulfillment workflow. |
Specific message field mappings, scheduling, and Orderful trading-partner configuration are handled outside this guide as part of the EDI integration setup with Orderful and Kibo Support.
# Edit Order Items
Source: https://docs.kibocommerce.com/pages/edit-order-items
Once shipments are created, order items can only be edited from the **Shipments** tab. By default, shipments are created automatically upon order submission which means you will always be editing orders at the shipment level. But if you have [configured shipments to be created](/pages/configure-shipment-creation "Configure Shipment Creation") at a certain point after order submission, then you can edit the items directly as long as the order is in the Pending Shipments state.
This guide explains how to edit order items on both shipments and orders.
If the `restrictEdit` flag is set to true on the order [via API](/pages/orders-api-overview "Orders API Overview"), then a user without the Override Order Update Restriction [behavior](/pages/user-roles "User Roles") will not be able to edit the order.
This includes changing the address, email, contact, attributes, or other details as well as performing any actions such as creating a new shipment, reassigning or updating existing shipments, editing shipment items or notes or custom data, canceling shipment line items, and adding a payment. However, the user will still be able to initiate and process returns.
## Edit Order Line Item Attributes
Order line item attributes apply independently to each line item within an order. They appear against each individual item line on the order. Each line item can carry its own separate value for the same attribute — for example, one line item might have a gift message while another does not. To provide value to an attribute for a line , select the attribute icon in the edit order modal or on the Order details page. Similar to order attributes section displays all custom line item order attributes that you have configured to apply to entity "Order". If this is an initial order that includes [subscription or trial products](/concept-guides/subscriptions "Product Subscriptions Overview"), then any line item attribute with entity as "Subscription" will be included as well. However, they will not be displayed for any continuity orders created by an existing subscription.
## Shipment Item Edits
Once shipments exist on an order, you can only edit order items at the shipment level.
1. While viewing an order, click the **Shipments** tab.
2. Expand the drop-down menu to the right of a line item to access item actions.
To reduce item quantity, use the Cancel Item action. To increase a quantity, a new [order](/pages/create-offline-orders "Create Offline Orders") or [shipment](/pages/edit-order-shipments#create-new-shipment "Edit Order Shipments") must be created for the additional amount and will be fulfilled separately. Make changes to the item-level tax, discounts, or fees via the [shipment adjustment options](/pages/edit-order-shipments#edit-shipment-subtotals "Edit Order Shipments").
### Reassign Item
**Manual Reassign** will allow you to select a new fulfillment location for this line item, similar to manual reassignment at the shipment level.
**Auto Reassign** will use Order Routing logic to assign the line item to a new fulfillment location.
### Transfer Item
If applicable for the shipment type and fulfillment configurations, **Request Transfer** will be available and will allow a new transfer shipment to be created to supply missing inventory for the assigned fulfillment location instead.
### Edit Unit Price
After editing an item's unit price, the tax will be automatically recalculated.
1. Click **Edit Unit Price** from the item actions menu.
2. Enter the new **Unit Price**.
3. Select the **Reason For Change** from the drop-down menu. If you select Other, then you will be prompted to specify the reason.
4. Click **Save**.
### Cancel Item
You can cancel all or partial quantity of an item. Crediting a payment is not necessary if editing or canceling a single item from a shipment.
1. You can cancel either partial quantity or the full quantity of an item.
2. Click **Cancel Item** from the item actions menu.
3. Enter the quantity of the item that you want to cancel. For example, if an item has a starting quantity of 7 then cancelling 3 will change the shipment quantity to 4. Cancelling all 7 will remove the line item from the shipment entirely.
4. Select a **Cancel Reason** from the drop-down.
5. Click **Cancel Items** to confirm.
After canceling the item, it will be moved to a new **Canceled Items** tab in the shipment details. This allows you to view a record of items that were previously included in the shipment.
You can have your tenant configured to retain an item's handling fee when it is cancelled. In Order Management-Only implementations, the line item's handling fee will be redistributed onto other items in the shipment. In eCommerce + Order Management implementations that do not distinguish between order-level and item-level handling fees, the total handling fee will be retained. Contact [Kibo Support](https://help.kibocommerce.com/) to enable this behavior.
### View Custom Data
Custom order data is passed to the shipments upon initial order creation, but any edits to the item-level custom data made after creation must be done on a per-shipment basis. This means that you should update any custom item data on every shipment within the order where needed because a change at the order level will not be applied across the board.
1. Click **View Custom Data** from the item actions menu. This opens a modal displaying the item-level custom data that was applied to the shipment during order creation.
2. Click **Edit** to change a custom data key. Note that these values are always treated as strings. Click **Save** after entering the new value.
3. Click **Delete** to remove a data key from this item.
If you want to edit shipment-level custom data instead, rather than the custom data of individual items, you can do this from the Custom Data tab [of the shipment details](/pages/edit-order-shipments).
### Gift Card Items
If an item is a digital product, such as a gift card, then it will be displayed as a "Digital" shipment type. The shipment information in the Order Admin will have an additional tab for Gift Card Details where the gift card number, PIN, recipient and sender names and emails, and gift message are displayed.
You can edit the recipient's name or email as well as the gift message and resend the gift card email to the recipient:
1. Click into a text box to make changes. As with customer accounts, the maximum allowed length for an email address is 254 characters.
2. Click **Resend Gift Card Email** to save changes and send the customer a new email with their gift card information.
## Order Item Edits
If an order is in the Pending Shipment status (which must be enabled by [configuring how long after order submission the shipments are created](/pages/configure-shipment-creation "Configure Shipment Creation")), then you can edit individual items and make adjustments before the shipment is created.
### Repricing Behavior
Whether or not an edit reprices the order (updates its tax, discounts, shipping, and/or handling) depends on the type of edit being done. While implementations with eCommerce follow the same repricing behavior as when creating offline orders, Order Management implementations vary depending on whether or not you have a product catalog.
* **Order Management-Only**: All totals will be proportionally redistributed across the remaining item quantities when a quantity is decreased or an item is canceled. When editing an item's unit price or making adjustments to the order, shipping, and handling totals, then only the tax amount is refreshed (which requires tax to be configured in your tenant). This means that any discounts that were present when the order was placed will remain after editing a unit price or making adjustments.
* **Order Management with Catalog**: When the [Refresh Pricing on Order site setting](/pages/configure-shipment-creation#enable-shipment-release "Configure Shipment Creation") is enabled, repricing will follow the same behavior as when creating offline orders. This requires you to have payment gateways, tax, shipping carriers, and discounts configured. When this setting is disabled (which is the default), it will follow the same behavior as Order Management-Only.
If a new payment needs to be collected (such as after adding an item or changing the shipping that incurs extra shipping costs) then the payment will not be automatically collected. You must add a new payment to the order manually, which will immediately be Authorized.
### Perform Edits
Which actions are available may depend on your implementation type and configurations. For instance, Order Management with Catalog implementations must have the Refresh Pricing on Order site setting enabled in order to change shipping methods or fulfillment types.
1. Click **Edit Details** while viewing the order details.
2. This will open a modal similar to that of creating an offline order. Here you can make edits to existing items such as changing their unit price, decreasing their quantity, or removing them from the order.
3. When editing an order, you can manage shipping methods at either the item or order level, but not both simultaneously. If individual items have their own methods, a Shipping Method column appears, allowing you to update each item directly. In this case, the order-level shipping option is not visible. Alternatively, if a single shipping method applies to the entire order, the Shipping Method column is not displayed, and you will manage shipping using the order-level menu. With [delivery,](/pages/delivery) a specific location selection is not available, as the system will derive it. The system enforces consistency by preventing conflicts: for example, you cannot add a Ship-to-Home (STH) item to an order that has a single order level method for delivery items, or vice versa.
4. Add a new item using the **Product Search** bar and enter its fulfillment method, unit price, and quantity. You can also choose whether to subscribe to the item (and if so, change its frequency) if [subscriptions](/pages/manage-product-subscriptions "Manage Subscriptions") are enabled.
5. Expand the Order Adjustments, Shipping, Handling, and/or Tax & Duty sections of the order details to make adjustments by adding or subtracting from the subtotal.\\
The [Disable Tax and Duty Adjustments site setting](/pages/general-settings "General Settings") must be enabled to make edits to any of the tax or duty totals through the Admin UI.
6. Make other miscellaneous edits such as changing the pickup contact, changing the price list, and adding customer notes or a gift message as needed.
7. Click **Save** in the bottom right once all edits have been completed.
# Edit Order Shipments
Source: https://docs.kibocommerce.com/pages/edit-order-shipments
Although fulfillers can view and manage shipments through the Fulfiller UI, you can also perform edits and actions on existing shipments from the Order Admin.
If the `restrictEdit` flag is set to true on the order [via API](/pages/orders-api-overview "Orders API Overview"), then a user without the Override Order Update Restriction [behavior](/pages/user-roles "User Roles") will not be able to edit the order.
This includes creating a new shipment, reassigning or updating existing shipments, editing shipment items or notes or custom data, canceling shipment line items, and adding a payment. However, the user will still be able to initiate and process returns.
## View Shipment Details
When viewing an order's details at **Main** > **Demand** > **Orders**, the Shipments tab displays all shipments that belong to the order. If a shipment consists of multiple packages, then each package will have its own module with a table of its line items. The general shipment details include:
* General overview information of the Shipment Number, Last Updated date, Total, and current Status (which indicates whether the shipment is Ready, Backorder, Fulfilled, Customer Care, Canceled, or [Future](/pages/inventory-quantity-types#future-available-to-promise-inventory)).
* The shipment **Type** and **Fulfillment Step**, corresponding to the customer's selected [fulfillment method](/pages/fulfillment-method-types) for the order and its current status in the workflow.
* Any shipment custom data (if applicable) in the **Custom Data** tab. Custom data is configured in key:value string format, and you can add new shipment-level custom data by clicking the **Add** button in this tab.
* Internal notes in the **Shipment Notes** tab. These are separate from order notes and not copied onto any child shipments or order-level logs. When a shipment is rejected (including when it is split, reassigned, or transferred), the location that rejected it is tracked in shipment notes. This helps prevent shipments from being manually reassigned to a location that previously rejected it.
* A record of all events and changes made to each shipment in the **Shipment History** tab, including shipment custom data. This matches the shipment log from the Fulfiller UI that tracks a shipment's progress through fulfillment, edits to shipping or item details, and other updates.
* A list of all items canceled from the shipment in the **Canceled Items** tab (not shown below). This allows you to view a record of all items previously included on the order. If no canceled items exist for the shipment, this tab will not be displayed.
Use the dropdown menus in the top right to reassign the entire shipment or change its shipment status. Pricing subtotals are listed underneath the items table and [can be adjusted as shown later in this guide](#edit-shipment-subtotals).
To change the columns that are displayed in the above table, expand the dropdown menu in the far right of the header. This will allow you to toggle columns on and off. For example, there is a column for Duty that is not displayed by default but can be turned on to display duty fees for internationally-traded products.
## Reassign a Shipment
An entire shipment or select line items in a shipment can be reassigned to another location from the Shipments view. In the latter case, the selected line items will be split into a new shipment object while the old shipment will retain the unselected items.
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to reassign a shipment of.
3. Click the **Shipments** tab.
4. Expand the **Update Shipment** drop-down.
5. Click either **Manual** or **Auto Reassign**. This corresponds to the [Reassign Shipment API call](/api-reference/shipment/reassign-shipments).
In auto reassignment, the shipment will be sent back through the order routing process. But in manual reassignment (detailed below), a pop-up will prompt you to select the location that the new shipment should be fulfilled from.
### Manual Reassignment
The manual reassignment pop-up has two tabs, Inventory and All Locations. The Inventory tab displays each location's inventory status for the shipment if that information is available, while the All Locations tab displays only the location names and codes. Each tab has a search box that you can use to perform an exact search for a location code or location name. This is not case-sensitive and results will persist if you switch between the tabs.
In either tab of this pop-up:
1. Select the location you want to reassign the shipment to.
2. Click **Save**.
## Create New Shipment
You can create a new shipment to add items to an order without refreshing the order pricing or discounts. This is supported by all implementations that include eCommerce, but requires a catalog if your implementation is Order Management-only.
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to add a shipment to.
3. Click the **Shipments** tab.
4. Click **New** **Shipment**. This will open the Shipment Creation Request modal.
5. Use the product search field under **Name** to add an item.
6. Select the item's **Fulfillment** method. There is a "Direct Ship" option for Ship to Home (STH) , "Delivery" option for [delivery](/pages/delivery) and individual location options for Buy Online Pickup in Store (BOPIS)
* If STH or [Delivery,](/pages/delivery) you should also select the **Shipping Method** from the dropdown below the table of line items.
* Inventory totals are displayed in the fulfillment options. The Direct Ship option will display an aggregate total, while the BOPIS options will display the total at that specific location. If the total includes [future inventory](/pages/future-inventory "Future Inventory"), the value will be underlined and hovering over it will then reveal a breakdown of future and current inventory.
* [Delivery](/pages/delivery) fulfillment displays aggregated inventory across all locations without user-selectable location options, similar to existing Ship-to-Home (STH) functionality.
7. Click **Add** to confirm the item.
8. Repeat for any other items you want to add.
9. Once all items have been added, click **Request Shipment Creation** to confirm. The new shipment will be routed or assigned to the specified pickup location.
You cannot edit duty fees for internationally-traded products here. Duty fees must be set in your catalog via the [Catalog Storefront Tax API Extension](/pages/tax-settings "Catalog Storefront Tax").
## Edit Shipment Subtotals
When viewing a shipment, you can make adjustments to the subtotals.
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to edit a shipment of.
3. Click the **Shipments** tab.
4. The pricing breakdown of the items within that shipment are displayed below the line items.
5. Click **Edit** to change these values.
6. Expand the **Item Total**, **Shipping**, **Handling**, and/or **Duty Total** sections to reveal the subtotal and tax value breakdown for each pricing element. Note that if the [Disable Tax and Duty Adjustments site setting](/pages/general-settings "General Settings") is enabled, then you will not be able to make edits to any of the tax or duty amounts through the Admin UI.
7. Use the dropdown to select whether you want to **Subtract from...** or **Add to...** the current value.
8. Use the radio buttons to indicate whether you want to make the adjustment based on an exact dollar value (**\$**) or a percentage of the current value (**%**).
9. Enter the value or percentage by in the text field. The new value will be calculated and previewed on the right. The below example would remove \$12.00 from this shipment's item subtotal, bringing it to a new value of \$8.00:
10. Click **Save**.
11. Select a reason for the change in the modal that appears.
12. Click **Save** again to finalize the edits.
## Handling Fee Retention
KIBO Commerce allows merchants to enable retention to ensure handling fees are accurately preserved when individual items are cancelled or when a complete shipment is cancelled. To understand how these handling fees are initially applied and grouped, refer to [Shipping Method and Fees](https://docs.kibocommerce.com/pages/shipping-methods-and-fees).
#### Order-Level Handling Fee Retention:
Order level Handling fee is preserved as follows:
1. **Shipping (STH)**: Retained until all shipments with the same shipping method are cancelled.
2. **BOPIS**: Retained until all shipments at the same location are cancelled.
3. **Delivery**: Retained until all shipments with the same delivery method and location are cancelled.
When a shipment is fully cancelled but other shipments exist with the same fulfillment group, the order-level fee is automatically moved to the next applicable shipment.
#### Item-Level Cancellation:
1. **Partial Cancellation**: If the quantity of an item is reduced, the associated product-level handling fee is reduced proportionally.
2. **Item Cancellation**: Product-level fees are removed entirely once the individual item is fully cancelled.
Example: Consider an order where a customer is picking up a Toaster and a Mixer at Store Austin (belonging to the same shipment with a \$50.00 group fee) and a Blender at Store Texas (belonging to a separate shipment with a \$3.00 group fee).If the customer cancels the Toaster at Store Austin:
1. **Retention**: The \$50.00 order handling fee is retained because the shipment and group still contain the other item, the Mixer.
2. **Cancellation**: If the customer then cancels the Mixer, the shipment for Store Austin is now fully cancelled. Because there is no other target shipment for the Store Austin group, the \$50.00 handling fee is removed. The \$3.00 fee for the Store Texas shipment remains unaffected as it belongs to an entirely different group and shipment.
Contact [**KIBO Support**](https://help.kibocommerce.com/) to enable **order-level handling fee retention** for your tenant.
**Note:** Handling fee grouping and retention logic are currently not supported if multiship is enabled.
## Mark as Shipped
To force fulfillment on a shipment and mark it as complete regardless of its current status in the Fulfiller UI:
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to fulfill a shipment of.
3. Click the **Shipments** tab.
4. Expand the **Update Shipment** drop-down.
5. Click **Mark as shipped**.
## Edit Fulfilled Shipments
When a shipment has been fulfilled, its entry in the order’s shipments view will provide a reference of its fulfillment information. Information about the items in the shipment and the location it was shipped or picked up from can all be viewed from the tabs within the module.
The only edits that can be made to a fulfilled shipment is [editing an item's unit price](/pages/edit-order-items#edit-unit-price) or changing the shipment address. This allows the address to be updated in cases such as where the shopper gave the wrong address and the carrier returned the shipment, so the shipment address can be fixed and the shipment re-sent.
The tax will not be refreshed after a shipment item is edited if the shipment is Fulfilled or Cancelled, or if the order is Completed. Pricing and tax (including duty fees) for shipments in Customer Care or Backorder will be recalculated using the updated Ship To location.
# Edit Orders
Source: https://docs.kibocommerce.com/pages/edit-orders
Once shipments have been created for an order, most actions for editing orders and line items must be made at the shipment level. However, you can always edit custom order data, customer addresses, and pickup contacts at the order level. This guide covers how to perform each of these edits.
If you have [configured shipments to be created](/pages/configure-shipment-creation "Configure Shipment Creation") at a certain time after order submission instead of immediately, then you will be able to edit line items directly at the order level. See the [Edit Order Items guide](/pages/edit-order-items "Edit Order Items") for more information about how to do this. For payment actions, see the [Order Payments documentation](/pages/payment-actions).
If the `restrictEdit` flag is set to true on the order [via API](/pages/orders-api-overview "Orders API Overview"), then a user without the Override Order Update Restriction [behavior](/pages/user-roles "User Roles") will not be able to edit the order.
This includes changing the address, email, contact, attributes, or other details as well as performing any actions such as creating a new shipment, reassigning or updating existing shipments, editing shipment items or notes or custom data, canceling shipment line items, and adding a payment. However, the user will still be able to initiate and process returns.
## Change Order Address
You can change the customer address that is associated with an order.
1. Go to **Main** > **Demand** > **Orders**.
2. Click the order you want to cancel to open its order details.
3. Click **Change Address** in the customer information to edit the customer's billing or shipping address on all shipments in this order.
4. Pricing and tax for shipments in Customer Care or Backorder will be recalculated using the updated address. The tax will not be refreshed on a shipment in the Fulfilled or Cancelled state, or if the order is Completed.
5. If desired, click **Edit Email Address** to change the email address. This will not change the email for the customer's account and all orders, only this particular order. The maximum allowed length is 254 characters.
## Edit Order Attributes
The Order Attributes section displays all custom order attributes that you have configured to apply to entity "Order".
If this is an initial order that includes [subscription or trial products](/concept-guides/subscriptions "Product Subscriptions Overview"), then any "Subscription Only" attributes will be included as well. However, they will not be displayed for any continuity orders created by an existing subscription.
To edit these values, click **Edit** in the top right. This will open a modal that displays all attributes, so you can update multiple at once. Click **Save** once you have updated all of the values you want to change.
## Edit Pickup Contacts
If you are viewing a Buy Online Pickup In Store (BOPIS) order, then you will also have the ability to edit alternate pickup information in the Order Details.
There will be a primary pickup contact (generally the customer who placed the order) with an Edit icon where you can add the additional contact and enter their first/last name, email address, and optionally their phone number. You can also edit the details of any contacts already assigned. This information will be displayed in the shipment details of the Fulfiller UI (though it is only editable here in the Admin) and the alternate contact will receive [fulfillment notification emails](/pages/email-settings#email-settings) about the order.
For the API fields associated with this contact, see the [Order API payload](/api-reference/order/create-order) and the endpoints to [update](/api-reference/order/addupdate-alternate-contact) and [remove](/api-reference/order/remove-alternate-contact) the alternate contact.
# Email Templating Reference
Source: https://docs.kibocommerce.com/pages/email-customization-theme-reference
The Kibo eCommerce Core theme is the foundation upon which you can build your own Kibo eCommerce theme. You can view the latest Core theme files on [Github](https://github.com/Mozu/core-theme/).
## Hypr and HyprLive Syntax
Hypr and HyprLive share many syntax features, but differ in a few areas. Also, not all [tags](#hypr-tags) or [filters](#hypr-filters) are supported on both Hypr and HyprLive.
### Syntax Commonalities Between Hypr and HyprLive
| Syntax Feature | Example |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Tag delimiters | `{% %}` |
| Expression (variable, object lookup, literal, with any number of filters) delimiters | `{{ }}` |
| Pipe separator for filters | `{{ value\|filter\|filter2 }}` |
| Filter arguments enclosed in parentheses, separated by commas | `{{ value\|filter(argument1, argument2) }}` |
| Tag arguments are key-value pairs, where the key is a simple string and the value (if needed) is any expression that could be placed within `{{ }}` delimiters (but without those delimiters) | `{% tag "key" expression %}` |
| Single-line comment delimiters | `{# #}` |
| Multi-line comment delimeters | `{% comment %} ... {% endcomment %}` |
| String literals (double-quotes) | `" "` |
| Local variables (simple barestrings) | `varname` |
| Object property dot lookup | `object.property` |
### Syntax Differences Between Hypr and HyprLive
Hypr and HyprLive support unique syntax for a small number of operations. Because existing themes might use these syntax features, Kibo eCommerce continues to support them, but whenever possible you should use a syntax that both rendering engines support.
* [Index lookup](#index-lookup)
* [Filter arguments](#filter-arguments)
### Index Lookup
Look up values within an indexed array.
| Syntax Feature Recommended | first and last filters |
|---|
| Supported On | Hypr and HyprLive |
|---|
\{\{ model.items|first }} \{# Access the first item in model.items #}To cache the result for further use, use a with tag. \{% with model.items|first as firstitem %}
\{\{ firstitem.text }} \{# Access the "text" property of the first item #}
\{% endwith %}To look up a value at a specific index, use a for tag. \{% for item in model.items}
\{% if forloop.index == index %}
\{\{ item.text }}
\{% endif %}
\{% endfor %} |
| Syntax Feature | Dot notation |
|---|
| Supported On | Hypr |
|---|
\{\{ model.items.0 }} \{# Access the first item in model.items #} |
| Syntax Feature | Brackets |
|---|
| Supported On | HyprLive |
|---|
\{\{ model.items\[0] }} \{# Access the first item in model.items #} |
### Filter Arguments
Specify a filter argument.
| Syntax Feature Recommended | Parentheses |
|---|
| Supported On | Hypr and HyprLive |
|---|
\{\{ bigList|find(777) }} |
| Syntax Feature | Colon |
|---|
| Supported On | Hypr |
|---|
\{\{ bigList|find:"777" }} |
### Supported Tags and Filters
Some tags and filters are supported on both Hypr and HyprLive, only on Hypr, or only on HyprLive.
* View the [list of supported tags](#hypr-tags).
* View the [list of supported filters](#hypr-filters).
## Hypr Tags
The following is the complete list of Hypr tags.
- [all\_scripts](#all-scripts)
- [autoescape](#autoescape)
- [block](#block)
- [cms\_resources](#cms-resources)
- [comment](#comment)
- [dropzone](#dropzone)
- [dump](#dump)
- [extends](#extends)
- [filter](#filter)
- [for](#for)
| - [header\_content](#header-content)
- [if](#if)
- [include](#include)
- [include\_documents](#include-documents)
- [include\_entities](#include-entities)
- [include\_products](#include-products)
- [inline\_style](#inline-style)
- [json\_attribute](#json-attribute)
- [make\_url](#make-url)
| - [now](#now)
- [parent](#parent)
- [partial\_cache](#partial-cache)
- [preload\_json](#preload_-son)
- [require\_script](#require-script)
- [set\_header](#set-header)
- [set\_var](#set-var)
- [spaceless](#spaceless)
- [templatetag](#templatetag)
- [visitor\_tracking\_pixel](#visitor-tracking-pixel)
- [with](#with)
|
### all-scripts
Returns an array of scripts marked as required by the `require_script` tag.
The output of this tag is a quote-delimited, comma-separated array of strings that you pass to the `require` function at or near the end of a top-level Hypr template's rendered HTML content. Through the combination of the `all_scripts` and `require_script` tags, the RequireJS module loader loads all the scripts that a template and its subtemplates need. For example, the `trailing-scripts.hypr` template, included near the end of `page.hypr` (the base Hypr template that most pages on your site extend from), passes the list of all required scripts to RequireJS by calling the `all_scripts` tag in the `require` function:
```
require(['jquery'], function() { require(['modules/common'], function() { require([{% all_scripts %}]); }); });
```
### autoescape
Useful for preventing cross-site scripting attacks, this tag converts special characters in every piece of content between the opening and closing tags into HTML entities, including the content of any subtemplates placed within the tags.
| Supported On | Hypr, HyprLive |
|---|
This is a tag that you must open, `{% autoescape on %}` or `{% autoescape off %}`, and close, `{% endautoescape %`}.
```
{% autoescape on %}
Header
{% block article %}
{% include "modules/article" %}
{% endblock article %}
{% endautoescape %}
```
To prevent a subset of the enclosed content from being autoescaped, use the `safe` filter.
### block
Encloses content that overrides content in parent templates or defines content that child templates can override.
| Supported On | Hypr, HyprLive |
|---|
This is a tag that you must open, `{% block _name_ %}`, and close, `{% endblock _name_ %`}. This tag takes one argument, a name, as a string without quotation marks.
If the name you provide this tag does not match any name for a block in a parent template, you create a section of content that templates extending the current template can override.
If the name you provide this tag matches the name of a block present in a parent template, the current block overrides the content from the parent template. However, you can use the tag `{% parent %}` to output content from the parent block within the current block.
```
{% block product-code %}
{% if themeSettings.listProductCode %}
{{model.productCode}}
{% endif %}
{% endblock product-code %}
```
### cms-resources
Enables widget and dropzone functionality in the Content Editor.
Place this tag between HTML `` tags.
```
...
{% cms_resources %}
...
```
### comment
Ignores every line of code between `{% comment %}` and `{% endcomment %}`.
| Supported On | Hypr, HyprLive |
|---|
```
{% comment %}
{% block breadcrumbs %}
{% if themeSettings.showBreadcrumbs %}{% include "modules/breadcrumbs" %}
{% endif %}
{% endblock breadcrumbs %}
{% endcomment %}
```
To include a comment within a single line of code, use `{#` and `#}`.
```
{# load a specific page #}{% include "modules/brenda" %}
```
### dropzone
Renders an area (dropzone) in the Content Editor where Admin users can drag and drop widgets on a page.
| Supported On | Hypr, HyprLive |
|---|
On your live site, dropzones render `` tags that contain live widget content. You must declare dropzones in areas wider than 320 pixels, which is generally the smallest breakpoint in responsive designs. This tag takes two arguments, `zoneId` and `scope`.
The `zoneId` is required and must be unique across all templates on the site. It is a best practice to name the `zoneId` according to the location of the dropzone, such as *footer-bottom-right.*
The `scope` specifies the context for the dropzone:
* Use "page" scope to target a widget only to the page where the widget is added. If you omit the `scope` parameter, "page" scope is the default value.
* Use "template" scope to target a widget to every page that uses the template to which the widget is added. This may not work on all sites, and it is recommended to use the page scope instead when possible.
* Use "site" scope to target a widget to all pages on the site.
```
{% dropzone zoneId="bodybottom" scope="page" %}
```
### dump
Displays a formatted view useful for debugging of all the properties belonging to the argument you specify in the tag.
| Supported On | Hypr, HyprLive |
|---|
Remember to remove `dump` tags from a theme before releasing to a production environment.
```
{% dump product %}
```
### extends
Specifies that the current template extends a parent template. Extended (or child) templates can access, display, and modify any content placed within `block` tags in the parent template.
| Supported On | Hypr, HyprLive |
|---|
You can use the `extends` tag in two ways:
`{% extends "page" %}` (with quotation marks) uses the literal value "page" as the filename of the parent template to extend. The tag applies the `.hypr` extension to the filename you provide and assumes the `templates` directory is the root folder for the path.
`{% extends variable %}` uses the value of `variable` as either the name of the parent template to extend (if it evaluates to a string) or as the parent template itself (if it evaluates to a template object).
Place the `extends` tag in the first line of a child template, and place all ensuing content in the child template inside `block` tags. Within the blocks you create in the child template, you can inherit or modify content from the parent template.
```
{% extends "page" %}
{% block body-content %}
...
{% endblock body-content %}
```
### filter
Applies a Hypr filter(s) to the contents of the tag.
| Supported On | Hypr, HyprLive |
|---|
This is a tag that you must open, `{% filter _filter1_|_filter2_|_filter3_ ... %}`, and close, `{% endfilter %}`. You provide the name of the filters you want to apply as arguments to the opening tag, separated by the pipe symbol ( `|` ) but without any spaces. Use this tag if you want to run a Hypr filter(s) on the outputs of a Hypr tag, which you can't do using the standard filter syntax.
```
{% filter escape|lower %}
"This text will be HTML-escaped and appear in lowercase characters"
{% endfilter %}
```
### for
Loops over each item in an array.
| Supported On | Hypr, HyprLive |
|---|
This is a tag that you must open, `{% for _item_ in _list_ %}`, and close, `{% endfor %}`. The tag takes two arguments: an array to iterate through and a variable name for the items in the array. For example, to access the `name` property for each athlete in the array `athlete_list:`
```
{% for athlete in athlete_list %}
{{ athlete.name }}
{% endfor %}
```
You can loop over a list in reverse by using `{% for _item_ in _list_ reversed %}`.
The following variables are available within the scope of the`for` tag to assist with operations related to the current iteration of the loop.
| Variable | Description |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| `{{ forloop.counter }}` | The current iteration of the loop (1-indexed). |
| `{{ forloop.counter0 }}` | The current iteration of the loop (0-indexed). |
| `{{ forloop.revcounter }}` | The number of iterations from the end of the loop (1-indexed). |
| `{{ forloop.revcounter0 }}` | The number of iterations from the end of the loop (0-indexed). |
| `{{ forloop.first }}` | TRUE if the current iteration is the first time through the loop. |
| `{{ forloop.last }}` | TRUE if the current iteration is the last time through the loop. |
### header\_content
Outputs the contents from the *Additional Header Tags* section of the Page Settings found in the Content Editor, without processing or escaping the content (so HTML tags are expressed as HTML tags).
In `page.hypr`, which is the base template that most other templates inherit from, the `header_content` tag is located at the end of the `` section.
```
...
{% header_content %}
```
### if
Evaluates the contents in the tag if the argument is true.
| Supported On | Hypr, HyprLive |
|---|
This is a tag you must open, `{% if _something_ %}` and close, `{% endif %}`. You can complement the `if` tag with the `else` tag to provide logic to handle times when the argument is false.
```
{% if fruit_basket %}
The fruit basket has fruit.
{% else %}
The fruit basket is empty.
{% endif %}
```
You can also use equality and Boolean operators within `if` tags.
```
{% if fruit == "lucuma" or fruit == "kumquat" %}
"That's an exotic fruit!"
{% endif %}
```
The operators you can use include:
| Operator | Description | Precedence | |
| -------- | --------------------- | ------------------ | -- |
| `.` | dot operator | 1 | |
| `==` | equal to | 2 | |
| `!=` | not equal to | 3 | |
| `<` | less than | 4 | |
| `>` | greater than | 5 | |
| `>=` | greater than or equal | 6 | |
| `<=` | less than or equal | 7 | |
| `not` | not operator | 8 | |
| `and` | Boolean AND | 9 | |
| `or` | Boolean OR | 10 | |
| \` | \` | pipe (for filters) | 11 |
The operator precedence indicates which operations take place first. For example, for the statement `{% if items.length > 3 and flag == false or items.price >= 50 %}`, Hypr evaluates the components of the `if` tag in the following order. By the time Hypr evaluates the `or` operator, it has already evaluated the other components needed to determine if the statement is true or false.
1. `{% if items.length` > 3 and flag == false or items.price >= 50 %}
2. `{% if items.length` > 3 and flag == false or items.price >= 50 %}
3. `{% if items.length` > 3 and flag == false or items.price >= 50 %}
4. `{% if items.length > 3` and flag == false or items.price >= 50 %}
5. `{% if items.length > 3` and flag == false or items.price >= 50 %}
6. `{% if items.length > 3 and flag == false` or items.price >= 50 %}
### include
Loads and renders an external template within the current template.
| Supported On | Hypr, HyprLive |
|---|
The `include` tag enables you to split your code into manageable pieces organized across separate templates.
`{% include "modules/web-fonts-loader" %}` (with quotation marks) uses the literal value `"modules/web-fonts-loader"` as the filename of the template to include. The tag applies the `.hypr` extension to the filename you provide and assumes the `templates` directory is the root folder for the path.
`{% include variable %}` uses the value of `variable` as either the name of the template to include (if it evaluates to a string) or as the template itself (if it evaluates to a template object).
This tag evaluates included templates with the same variables available to the parent template. However, you can pass additional variables to the included template scope manually by using name-value pairs within the tag. You can assign these variables any value of your choosing. For example:
```
{% include "modules/common/address-form" with model=model.billingAddress showAddressType=false %}
```
In this case, for use within the included template's scope, the `model` variable is assigned the value of the `billingAddress` variable available from the current model and the `showAddressType` variable is assigned the value `false`.
### include\_documents
Retrieves a document(s) from the CMS using inline API calls and adds the returned document(s) to the page model of the specified template.
This tag is similar to the `include` tag but instead of setting the model manually or using the same model available to the parent template, the `include_documents` tag adds a collection of documents to the model of the specified template based on the document list, view, and any additional query arguments you specify.
As its first argument, this tag takes the name of a template (or alternatively, the template object itself) to whose model the document(s) should be added. As its second argument, this tag requires the fully qualified name of the document list that contains the document(s) to be returned. As its third argument, this tag requires the name of the view to apply to the document list. The full syntax looks like:
`{% include_documents "_templateName_" listFQN="_name_@_namespace_" view="_viewName_" %}`
You can use the following arguments with this tag.
| Argument | Description |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `_templateName_` | |
| The template in which to include the document(s). You can specify the template name (in quotes) or the template object itself (without quotes, such as `model.config.template`). | |
If specifying the template name, the tag applies the proper extension to the filename and assumes the template is located in the `templates/pages` directory; if the template is located in a folder other than `pages`, specify the path starting after `templates` (for example, if the template is in the `templates/modules` directory, specify `modules/templateName` as the argument for the template name).
**This argument is required and must be in the first position.**
|
\| `listFQN` |
The fully qualified name of the document list.
**This argument is required and must be in the second position.**
|
\| `view` |
The name of the document list view that determines which document properties can be accessed.
**This argument is required. If you don't specify a view, Kibo eCommerce assumes the name of the view is *default*. Many document lists do not contain a view named *default*, so it is recommended you always specify a view for this tag; otherwise, the API call may not return any data.**
|
\| `pageWithUrl` |
Default: false.
Specifies whether to use URL parameters for paging results.
When false, you must specify the `startIndex` and `pageSize` parameters as arguments in the tag.
If you set this argument to true, you specify the tag to use the existing values for `startIndex` and `pageSize` available from the URL parameters.
|
\| `sortWithUrl` |
Default: false.
Specifies whether to use URL parameters for sorting results.
If you set this argument to true, you specify the tag to sort using the existing value of the `sortBy` URL parameter (either `asc` or `desc`).
|
\| `startIndex` |
Default: 0
The item on which to begin listing items in the collection. Kibo eCommerce collections are zero-indexed, so `startIndex=0` starts at the first item in the collection.
|
\| `pageSize` |
Default: 15
The maximum number of items to return in the model.
**Note:** Setting this number too high may result in poor performance and a cumbersome UI experience. |
\| `filter` |
A filter expression for Kibo eCommerce collections. You can [filter](/pages/sorting-and-filtering-apis) documents based on their properties by writing a string expression as your argument. For example: `firstname eq "Brenda"`.
|
\| `query` | A deprecated alias for `filter`. If both the `filter` and `query` arguments are present, `query` takes overrides `filter`. |
\| `sort` |
Default: null
A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
|
\| `ids` |
Default: null
A comma-separated list of individual document IDs. If you include this argument, Kibo eCommerce ignores the `filter` argument and the result set consists only of the documents whose IDs you provide.
|
\| `useActiveDateRange` |
Default: false.
If you set this argument to true, you specify the tag to use the existing active date range information present in the URL.
|
```
{% comment %}
"Include the last five sales updates added by a CMS business user in the model of the sale-updates template."
{% endcomment %}
{% include_documents "modules/sale-updates" listFQN="saleUpdates@company" view="admin" pageSize=5 sort="createDate asc" %}
```
### include\_entities
Retrieves an entity(s) using inline API calls and adds the returned entity(s) to the page model of the specified template.
This tag is similar to the `include` tag but instead of setting the model manually or using the same model available to the parent template, the `include_entities` tag adds a collection of entities to the model of the specified template based on the entity list, view, and any additional query arguments you specify.
As its first argument, this tag takes the name of a template (or alternatively, the template object itself) to whose model the entity(s) should be added. As its second argument, this tag requires the fully qualified name of the entity list that contains the entity(s) to be returned. As its third argument, this tag requires the name of the view to apply to the entity list. The full syntax looks like:
`{% include_entities "_templateName_" listFQN="_name_@_namespace_" view="_viewName_" %}`
You can use the following arguments with this tag.
| Argument | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `_templateName_` | |
| The template in which to include the entity(s). You can specify the template name (in quotes) or the template object itself (without quotes, such as `model.config.template`). | |
If specifying the template name, the tag applies the proper extension to the filename and assumes the template is located in the `templates/pages` directory; if the template is located in a folder other than `pages`, specify the path starting after `templates` (for example, if the template is in the `templates/modules` directory, specify `modules/templateName` as the argument for the template name).
**This argument is required and must be in the first position.**
|
\| `listFQN` |
The fully qualified name of the entity list.
**This argument is required and must be in the second position.**
|
\| `view` |
The name of the entity list view that determines which document properties can be accessed.
**This argument is required. If you don't specify a view, Kibo eCommerce assumes the name of the view is *default*. Many entity lists do not contain a view named *default*, so it is recommended you always specify a view for this tag; otherwise, the API call may not return any data.**
|
\| `pageWithUrl` |
Default: false.
Specifies whether to use URL parameters for paging results.
When false, you must specify the `startIndex` and `pageSize` parameters as arguments in the tag.
If you set this argument to true, you specify the tag to use the existing values for `startIndex` and `pageSize` available from the URL parameters.
|
\| `sortWithUrl` |
Default: false.
Specifies whether to use URL parameters for sorting results.
If you set this argument to true, you specify the tag to sort using the existing value of the `sortBy` URL parameter (either `asc` or `desc`).
|
\| `startIndex` |
Default: 0
The item on which to begin listing items in the collection. Kibo eCommerce collections are zero-indexed, so `startIndex=0` starts at the first item in the collection.
|
\| `pageSize` |
Default: 15
The maximum number of items to return in the model.
**Note:** Setting this number too high may result in poor performance and a cumbersome UI experience. |
\| `filter` |
A filter expression for Kibo eCommerce collections. You can [filter](/pages/sorting-and-filtering-apis) entities based on their properties by writing a string expression as your argument. For example: `firstname eq "Brenda"`.
|
\| `query` | A deprecated alias for `filter`. If both the `filter` and `query` arguments are present, `query` takes overrides `filter`. |
\| `sort` |
Default: null
A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or entity name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
|
\| `ids` |
Default: null
A comma-separated list of individual entity IDs. If you include this argument, Kibo eCommerce ignores the `filter` argument and the result set consists only of the entities whose IDs you provide.
|
```
{% comment %}
"Include the last five sales quotas added by a business user in the model of the sales-quotas template."
{% endcomment %}
{% include_entities "modules/sales-quotas" listFQN="salesQuotas@company" view="admin" pageSize=5 sort="createDate asc" %}
```
### include\_products
Retrieves a product(s) using inline API calls and adds the returned product(s) to the page model of the specified template.
This tag is similar to the `include` tag but instead of setting the model manually or using the same model available to the parent template, the `include_products` tag adds a collection of products to the model of the specified template based on the arguments you specify in the tag.
As its first argument, this tag takes the name of a template (or alternatively, the template object itself) to whose model the product(s) should be added, based on the results of the other tag arguments.
`{% include_products "_templateName_ with argument1=value1 and argument2=value2 as_parameter %}`
You can use the following arguments with this tag.
| Argument | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `_templateName_` | |
| The template in which to include the product(s). You can specify the template name (in quotes) or the template object itself (without quotes, such as `model.config.template`). | |
If specifying the template name, the tag applies the proper extension to the filename and assumes the template is located in the `templates/pages` directory; if the template is located in a folder other than `pages`, specify the path starting after `templates` (for example, if the template is in the `templates/modules` directory, specify `modules/templateName` as the argument for the template name).
**This argument is required and must be in the first position.**
|
\| `filter` |
Default: "categoryId req *category ID of the current category page, if it exists*"
A filter expression for Kibo eCommerce collections. You can [filter](/pages/sorting-and-filtering-apis#filtering) products based on their properties by writing a string expression as your argument. For example: `firstname eq "Brenda"`.
If you place the`include_products` tag on a Kibo eCommerce category template, then the default filter will be `categoryId req [_current category id_].` For example, if the current category ID is 33, then the default filter will be `categoryId req 33`. This filter will automatically limit the displayed products to those belonging to the current category or any of its subcategories. You can override this behavior by supplying your own `filter` argument. If you place the `include_products` tag on a template other than a category template, then there is no default `filter` argument. If there is no `filter` argument then the first page of results from all products in the site will be displayed.
|
\| `query` | A deprecated alias for `filter`. If both the `filter` and `query` arguments are present, `query` takes overrides `filter`. |
\| `pageWithUrl` |
Default: false
Specifies whether to use URL parameters for paging results.
When false, you must specify the `startIndex` and `pageSize` parameters as arguments in the tag.
If you set this argument to true, you specify the tag to use the existing values for `startIndex` and `pageSize` available from the URL parameters.
|
\| `sortWithUrl` |
Default: false
Specifies whether to use URL parameters for sorting results.
If you set this argument to true, you specify the tag to sort using the existing value of the `sortBy` URL parameter (either `asc` or `desc`).
|
\| `startIndex` |
Default: 0
The item on which to begin listing items in the collection. Kibo eCommerce collections are zero-indexed, so `startIndex=0` starts at the first item in the collection.
|
\| `suppressErrors` |
Default: false
Prior to September 2016, the `include_products` tag suppressed errors related to product search, but this behavior changed in September 2016. In general, you should not have to enable this parameter, but if you want to make absolutely sure that errors on supplemental calls to the `include_products` tag do not obscure primary page content, you can set this parameter to true. For example, you can set the parameter to true when you display related products on a product details page to ensure that intermittent search errors on the related products call do not prevent the entire product details page from loading.
**Note:** If you use enable this parameter and the `include_products` tag is located inside a `partial_cache` tag, then any error that occurs causes the page to cache as a blank page. The page will continue to display to shoppers as a blank page until the cache clears. |
\| `pageSize` |
Default: 15
The maximum number of items to return in the model.
**Note:** Setting this number too high may result in poor performance and a cumbersome UI experience. |
\| `searchQuery` | A search term to search on for the product results. |
\| `sort` |
Default: null
A string representing how to sort the collection. You can sort on any property, date (such as `createDate`), or document name. After specifying the name of the property you are sorting on, include a space followed by "`asc`" or "`desc`" to specify sorting in ascending or descending order.
|
\| `includeFacets` |
Default: false
Specifies whether facets should be returned with the products.
|
\| `productCodes` |
Default: null
Provides a shortcut for building the `filter` argument with multiple products. This argument accepts a string that specifies a comma-separated list of product codes . For example, `productCodes=“Product01,Product02,Product03”` is an equivalent shorthand syntax to `filter=“ProductCode eq Product01 or ProductCode eq Product02 or ProductCode eq Product03”`.
If present, this argument overrides the `filter` argument.
|
\| `facetHierDepth` |
Default: 2
If filtering using category facets in a hierarchy, the number of category hierarchy levels to return for the facet. This option is only available for category facets.
|
\| `responseFields` |
Default: null
A list or array of fields returned for a call. These fields may be customized and may be used for various types of data calls in Kibo eCommerce. For example, responseFields are returned for retrieving or updating specific attributes, carts, and messages in Kibo eCommerce rather than the whole object.
To learn more about this field, refer to the [Response Fields](/pages/response-fields) topic.
|
\| `facet` |
Default: null
Individually list the facet fields you want to display in a web storefront product search.
|
\| `searchTuningRuleCode` |
Default: null
The unique identifier of the search tuning rule.
|
\| `enableSearchTuningRules` |
Default: null
Enables search tuning rules.
|
\| `searchTuningRuleContext` |
Default: null
The category ID that the search tuning rule applies to.
|
\| `facetTemplateExclude` |
Default: null
A comma-separated list of the facets you want to exclude.
|
\| `facetCategoryId` |
Default: null
The unique identifier of a category for use in faceting.
|
\| `categoryId` |
Default: pageContext.CategoryId
This parameter is used as the default value for the `facetTemplate`, `facetHierValue`, and `searchTuningRuleContext` parameters.
If the `productCodes` or `filter` parameters are not set, this parameter sets the `filter` parameter to "`categoryId req [value]`"
|
\| `categoryCode` |
Default: null
An alternative to `categoryId`. You can use this parameter to specify a category code instead of a category ID.
|
\| `facetCategoryCode` |
Default: null
Overrides the use of `categoryId` for the `facetTemplate` and `facetHierValue` parameters.
|
\| `facetPrefix` |
Default: null
Filters facet values by a prefix. The syntax is `facetPrefix="_facetName_:_prefix_"`, and you must also specify either `facet` or `includeFacets` as a separate parameter.
For example, to filter a brand entry facet by facet values that start with "2016", specify the following in the `include_products` parameter list:
`facet="tenant~brandentry" and facetPrefix="tenant~brandentry:2016"`
To set a prefix for more than one facet, separate the values with commas. For example:
`includeFacets=themeSettings.showCategoryFacets and facetPrefix="tenant~color:b, tenant~size:s"`
|
```
{% comment %}
"Include products in the model of the template specified in the model.config object (or in the product-list-tiled template if the model.config object does not contain a template), based on the product codes listed in the model.config object, and sort the results based on the additional parameters."
{% endcomment %}
{% include_products model.config.template|default:"modules/product/product-list-tiled" with productCodes=model.config.productCodes and includeFacets=themeSettings.showCategoryFacets and pageWithUrl=true and sortWithUrl=true as_parameter %}
```
### inline\_style
Outputs the contents of a stylesheet as raw CSS.
Always enclose this tag within HTML `
```
### json\_attribute
Encodes an object using HTML attribute encoding.
### make\_url
Generates a string that helps construct URLs for different Hypr objects, such as images or category models.
| Supported On | Hypr, HyprLive |
|---|
This tag is the recommended method for creating consistent URLs across your site. The syntax for the tag is:
`{% make_url "_mode_" _objectModel_ %}`
The mode is how you specify what type of URL you are constructing. Depending on which mode you select, you pass in different objects and optional parameters. The modes for this tag are:
* [image](#image-27)
* [product](#product-29)
* [category](#category-30)
* [sorting](#sorting-31)
* [facet](#facet-32)
* [cdn](#cdn-33)
* [paging](#paging-34)
* [cart](#cart-35)
* [document](#document-36)
* [stylesheet](#stylesheet-37)
The result of the tag is a string that helps construct the URL in question. Depending on the mode, the URL may be *scheme-relative* (a relative URL that uses the current protocol, such as `https:` or `http:`, as its base) or *domain-relative* (a relative URL that uses the domain, such as `http://www.yourSite.com/`, as its base). For some modes, such as `"image"`, the resulting string appends a *cache key value*, which is a random number that is updated every time someone busts the cache through the Admin General Settings.
[Delete](#)
If you set up custom routes for your site, the results of the make\_url tag as listed in the examples of this topic likely won't match your custom URLs. However, the make\_url tag accounts for custom route changes and outputs a modified string according to the code you set up in the Custom Routing JSON Editor, so there is no need for further action on your part.
|
### image
|
\| --- |
|
The `"image"` mode generates a path to the CDN location for the specified image model. You can add image fields to the URL, such as size and quality fields, by including the parameters between the keywords `with` and `as_parameter` at the end of the tag.
Cache key appended to result? **Yes**
Type of URL: **Scheme-relative**
|
**Example:**
```

{# Result: This code specifies the image location at "//cdn.mozu.com/tenantID-siteID/cms/files/sweetImage.jpg?max=150&quality=75&crop=10,10,10,10&_mzCb=90239082348020" #}
```
When you use the `make_url` tag on an image hosted on the Kibo eCommerce CDN, you can include the following additional fields at the end of the tag, between `with` and `as_parameter`:
To avoid incorrect image rendering, do not apply the image manipulation fields to images that contain a dimension greater than 30,000 pixels in length.
| Field | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `max` | Specifies a pixel limitation for the largest side of an image. |
| `maxWidth` | Specifies a pixel limitation for the width of the image, preserving the aspect ratio if the image needs resizing. |
| `maxHeight` | Specifies a pixel limitation for the height of the image, preserving the aspect ratio if the image needs resizing. |
| `width` | Specifies an exact width dimension for the image, in pixels. |
| `size` | Same as `width`. Provides backwards-compatibility for an earlier syntax. |
| `height` | Specifies an exact height dimension for the image, in pixels. |
| `crop` | |
| Usage: `crop="x1,y1,x2,y2"` | |
Crops the image based on the specified coordinates. The reference point has positive coordinates only.
You can use this field to easily crop an equal amount of pixels from every edge of the image. For example, `crop="10,10,10,10"` removes 10 pixels from all edges of the image (`crop="0,0,0,0"` leaves the image uncropped).
You can also use this field to specify a subset of the image. For example, `crop="150,300,150,300"`. The only thing to remember is that you must always specify `x2` to the right of `x1` and `y2` to the bottom of `y1`, otherwise no cropping takes effect.
|
\| `quality` | Adjusts the image compression for JPEG files (other image types do not support this field). Accepts values from 0-100, where 100 = highest quality, least compression. |
|
### product
|
\| --- |
|
The `"product"` mode generates a path to a product page based on a product model, product code, or product ID. You can also specify a variant for a configurable product using the `variant` parameter.
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{# "uses the product model available in the Hypr template" #}
{% make_url "product" model %}
{# Result: "/p/my-product-code ...unless you have configured a canonical custom route, in which case the result mirrors the custom route" #}
{# "uses a product code" #}
{% make_url "product" "my-product-code" %}
{# Result: "/p/my-product-code" #}
{# "uses a product ID" #}
{% make_url "product" 1234 %}
{# Result: "/p/1234" #}
{# "uses a product code and a variant code" #}
{% make_url "product" "my-product-code" with variant="small-green" as_parameter %}
{# Result: "/p/my-product-code?vpc=small-green" #}
```
|
### category
|
\| --- |
|
The `"category"` mode generates a path to a category page based on a category model, category code, or category ID.
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{# uses the category model available in the Hypr template #}
{% make_url "category" categoryModel %}
{# Result: "/c/my-category-code ...unless you have configured a canonical custom route, in which case the result mirrors the custom route" #}
{# uses a category code #}
{% make_url "category" "my-category-code" %}
{# Result: "/c/my-category-code" #}
{# uses a category ID #}
{% make_url "category" 1234 %}
{# Result: "/c/1234" #}
```
|
### sorting
|
\| --- |
|
The `"sorting"` mode generates a path to a sort query with URL-encoded sort parameters.
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{% make_url "sorting" "price:desc,rating:asc" %}
{# Result: "?sortBy=price%3Adesc%2Crating%3Aasc" #}
```
|
### facet
|
\| --- |
|
The `"facet"` mode generates a path to a faceting query based on a facet value.
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{% for facet in productSearch.facets %}
{{facet.label}}
{% for facetValue in facet.values %}
[{{facetValue.label}}](/pages/{% make_url )
{% endfor %}
{% endfor %}
{# Result (of tag): "This code creates a link that a shopper can use to apply a facet. For example, the facet label might be 'Small' and the result of the make_url tag might be '?facetValueFilter=size%3ASmall'" #
```
|
### cdn
|
\| --- |
|
The `"cdn"` mode generates a URL on the CDN domain for your tenant, based on a full path to a filename, relative to root.
Cache key appended to result? **Yes**
Type of URL: **Scheme-relative**
|
**Example:**
```
{% make_url "cdn" "/cms/files/video.mp4" %}
{# Result: "//cdn.mozu.com/tenantID-siteID/cms/files/video.mp4?_mzCb=54654986689" #}
```
|
### paging
|
\| --- |
|
The `"paging"` mode generates a path to a specific page within a product search model. You can specify to create a path to the previous page, next page, first page, last page, or a specific page with the following fields or page number, which you use at the end of the tag preceded by the `with page=` phrase:
* `"previous"`
* `"next"`
* `"first"`
* `"last"`
* zero-indexed page number
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{% make_url "paging" productSearch with page="previous" %}
{% make_url "paging" productSearch with page=3 %}
```
|
### cart
|
\| --- |
|
The `"cart"` mode generates a path to your cart page. This mode does not require you to pass it a Hypr object representing the cart.
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{% make_url "cart" %}
{# Result: "/cart" #}
```
|
### document
|
\| --- |
|
The `"document"` mode generates a path to a document in the CMS based on a fully-qualified list name and a document name.
Cache key appended to result? **No**
Type of URL: **Domain-relative**
|
**Example:**
```
{% make_url "document" listFQN="banners@namespace" name="banner007" %}
{# Result: "/cms/banners@namespace/banner007" #}
```
|
### s