**Note:** File headers are basically the column headers or titles of the exported document.
# Getting Started with Exports
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Exports** API supports exporting data of different modules such as Orders, Locations, Allocations, Inventory, Invoices, Networks, Shipping\_Methods, and Aggregated\_Networks. fabric's Exports API lets you export module-specific data (saved in JSON format in the database) to a zip file. These zip files contain different CSV files where:
* Each field of a single JSON schema is a file header (also called column title) in the CSV file
* Each item of the JSON schema is a row in the CSV file
The data, in the database, are arranged as nested objects and arrays which are complex to use. fabric's Exports API simplifies the data of a single object by segregating them into multiple CSV files (by specific identifiers) for ease of use.
The following are the module (fabric service) names and its generated CSV files:
1\. Orders: order (exported by item), discount, logs, notes, payments, shipInfo\
2\. Allocations: allocation, logs\
3\. Shipments: shipment\
4\. Shipping\_Methods: shipping\_methods\
5\. Locations: location\
6\. Invoices: invoice, appeasements, discounts, payments\
7\. Inventory: inventory.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersExports.json)
# Cancel fraud order by order ID
orders.openapi post /orders/{orderId}/actions/fraud-cancel
If an order is suspected to be fraudulent, it is immediately placed on hold for verification. After verification, if it is confirmed as fraudulent, this endpoint is used to cancel the order. **Note**: If you do not have order ID, use the corresponding order number-based endpoint - `POST - /orders/order-number/{orderNumber}/actions/fraud-cancel`
# Cancel fraud order by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/fraud-cancel
If an order is suspected to be fraudulent, it is immediately placed on hold for verification. After verification, if it's confirmed as fraudulent, this endpoint is used to cancel the order by order number. **Note**: If you don't have order number, use the corresponding order ID-based endpoint - `POST /orders/{orderId}/actions/fraud-cancel`.
# Getting Started with Frauds
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Frauds** API endpoints deal with potential fraud orders.
# Release fraud order
orders.openapi post /orders/order-number/{orderNumber}/actions/fraud-release
If an order is suspected to be fraudulent, it is immediately placed on hold for verification. After verification, if it is confirmed as non-fraudulent, this endpoint is used to release the order from hold, by order number so that it can be processed. **Note**: When you don't have order number, use the corresponding order ID-based endpoint - `POST /orders/{orderId}/actions/fraud-release`.
# Release fraud order by order ID
orders.openapi post /orders/{orderId}/actions/fraud-release
If an order is suspected to be fraudulent, it is immediately placed on hold for verification. After verification, if it is confirmed as non-fraudulent, this endpoint is used to release the order from hold, by order ID, so that it can be processed. **Note**: When you don't have order ID, use the corresponding order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/fraud-release`.
# Get uploaded file status and details
imports.openapi get /oms-imports/{importId}
Get uploaded file status and details by specifying `importId`.
# Get uploaded files that match specified criteria
imports.openapi post /oms-imports/search
Get uploaded files that match specified criteria. Returned as paginated records.
# Getting Started with Imports
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL:
`` | License:
[fabric API License](https://fabric.inc/api-license)
fabric **Imports** API supports importing data of different modules such as
Orders, Invoices, and Shipments.
fabric's **Imports** API lets you import module-specific bulk JSON in text file
format in order to save these documents in fabric's databases. Each row in an
uploaded text file represents a single JSON schema.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersImports.json)
# Upload bulk file to import data
imports.openapi post /oms-imports
Upload bulk file by specifying file name. Successfully uploading the file triggers the import process, which is an event-driven extraction of the file's data to update the respective resource's system.
# Getting Started with Notifications
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Notifications** API enables you (Storefronts) to resend notifications to customers for specific order-related events, such as confirmation, status updates, cancellations, and more. it's also used to get notification acknowledgements from external services.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersNotifications.json)
# Orders (3.0.0)
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric Orders enable you to receive, track, and fulfill customer orders across sales channels, allow customers to track their orders, route orders through warehouses based on the customer’s location, and more.
Orders is designed to streamline and simplify order management and fulfillment processes during and after an order is created.
## Role-Based Access Control (RBAC)
fabric Copilot provides the ability to restrict the access of different users to information and actions available to them through roles. For more information and instructions on how to set up these controls, see the [RBAC](/v3/guides/settings/rbac/role-based-access-control-orders-roles) documentation.
## Integration Examples
**Allocation with fabric Orders:** After creating an order using fabric Orders service, the orders service sends a request to fabric’s Allocation module for order allocation. Allocation calls Order Fulfillment Logic (OFL) and OFL rules to get the location number where the inventory is available based on the currently defined OFL rule system. After completion, OFL provides the necessary information to the Allocation service, and Allocation calls the inventory service to reserve items as needed, adjusting your inventory counters in real-time.
The Order fulfillment process is set up by integrating your existing fulfillment systems, such as a Warehouse Management System (WMS), with fabric's Allocation APIs. This integration enables allocation-related events to start fulfillments in external systems, and allows external systems to make callbacks to the fabric Allocation APIs.
**Shipments & Tracking with fabric Orders:** fabric's Shipment APIs ensure that shipments are created for allocations. These APIs enable the warehouse or any external fulfillment system to generate shipments associated with the allocated orders.
Additionally, you can set up shipment tracking updates for orders by integrating your carrier tracking service with the Shipment Tracking APIs. These APIs enable the external carrier tracking service, such as ParcelLab, to post shipment events. With the order created, shipped, and tracking enabled, you can manage the order. This includes Cancellations, Appeasements, Exchanges, Credits, Returns, and more using the [Orders APIs](/v3/api-reference/orders/orders--3-0-0) or [Manage Orders](/v3/guides/orders/order-managment/overview) UI as needed.
**Notifications with fabric Orders:** Optionally, you can configure email updates for order transactions by integrating your preferred email service with the Notification APIs. This integration enables fabric Orders to deliver real-time email notifications for specific order update events.
**Fraud with fabric Orders:** To establish fraud prevention, you can integrate your preferred fraud service with the Fraud APIs. These APIs primarily allow for hold and release actions on the order, providing an effective means of preventing fraudulent activities.
## Benefits
* **Customer Lifetime Value (CLTV)**: Manage the customer lifetime vale through omnichannel orders. With all your data in one place, improve customer service by reducing call volume, average handle time, and increase support satisfaction. Improve order orchestration by reducing split shipments, OOS cancellations, and increasing on time delivery rate. As a multi-brand and multi-channel retailer, improve order processing time, reduce inventory cancellations, and subsequently increase support satisfaction.
* **Sell-through Rate (STR)**: You can increase sell-through rate by unifying and improving the Buy Online and Pickup in Store (BOPIS) experience, ship from store experience, and improved store inventory management.
* **Storefront Conversion Rate (CVR)**: Using real-time inventory coupled with backorder and preorder capabilities, you can increase sell-through rate, website conversion, and site merchandiser operational efficiency. Additionally, you can optimize your inventory and fulfillment by reducing split shipments, OOS cancellations, and increasing on time delivery rate.
## Example Use Cases
* **Exporting Sales and Reports Data**: Using fabric Orders export API, you can export data to be utilized for business intelligence or store the data externally as needed. The exports service flattens the JSON structure into columns, so that an external columnar database, such as an SQL database, can easily ingest the data. Exports can also be generated in fabric Copilot for ad-hoc analysis.
* **Fulfilling Backorders & Preorders**: During the order creation process within fabric Orders service, backorders and preorders are identified and flagged accordingly. This enables the backorder and preorder service to store these orders in a dedicated backorder queue. Fulfillment of these orders follows a *first in, first out* approach as inventory becomes available for the backorders.
Additionally, consent to delay operations are implemented based on your configuration of backorder settings. Orders that exceed the specified backorder service level require customer consent to proceed with the delay. fabric triggers the consent to delay notification based on your configuration, and updates regarding consent to delay are managed through the consent to delay API endpoint.
* **Omnichannel Store Fulfillment**: You can maximize return on existing investments in physical locations, such as brick and mortar stores, by connecting ecommerce sales to store inventories that are eligible for direct-to-consumer shipments. By bringing store inventory into the fulfillment network, you can expand capacity for ecommerce sales and increase the available assortment for online shoppers.
* **Optimized Order Fulfillment Logic**: Using fabric's Order Fulfillment Logic (OFL) you can configure how orders are handled for different items, locations, sales, shipping types, and more. For example, multi-location fulfillment allows you to allocate orders to specific fulfillment locations based on factors, such as shipping type, geographic distance, and inventory availability. This flexibility enables efficient order processing and reduces shipping times. For same-day delivery optimization, fabric's geolocation feature can be utilized. It considers the customer's location and searches for inventory networks within a set distance that can fulfill the order the fastest. This feature can be configured with specific boundaries and inventory balancing options to ensure the fastest possible delivery. Split shipment management is another key feature, allowing orders to be fulfilled from multiple locations when necessary. This can be set up at both the order and item level, with options to allow partial fulfillment. This functionality is particularly useful when dealing with complex inventory situations or when aiming to optimize delivery times for multi-item orders.
## Related topics
* [Product Catalog](/v3/guides/product-catalog/overview)
* [Inventory](/v3/guides/inventory/overview)
* [Orders API reference](/v3/api-reference/orders/orders--3-0-0)
* [Inventory API reference](/v3/api-reference/inventory/inventory--3-0-0)
* [Orders API developer guides](/v3/api-reference/orders/developer-guide/order-and-inventory-import)
# Orders FAQ
#### How can I insert fees, discounts, and taxes at the order level and item level?
* To insert fees, discounts, and taxes at item level, include the details in the `_items_ array` while creating an order.
* To insert fees, discounts, and taxes at order level, include the details outside the *items* array while creating an order. For details, see the request payload of [Order Create](/v3/api-reference/orders/orders/create-new-order).
#### How does the fabric Orders module manage customer data security and privacy?
fabric’s REST APIs are protected with OpenID Connect (OIDC) along with the identity introspector mechanism. In OIDC, identity information is communicated using JSON Web Tokens (JWTs). The data in fabric is stored in both MongoDB and S3. The MongoDB data is isolated per tenant in fabric Orders (also called OMS). You must create an [AWS configuration rule](https://aws.amazon.com/blogs/security/how-to-use-aws-config-to-monitor-for-and-respond-to-amazon-s3-buckets-allowing-public-access/) to ensure that the AWS S3 Bucket doesn't have public access. For example, one shouldn't be able to run:\
curl [https://inventory-oms-refresher-prod01.s3.amazonaws.com/chicosprod/export/store/FabricStoreInventorySync\_CHO\_2023-06-15T08-31-00-827090592Z.csv](https://inventory-oms-refresher-prod01.s3.amazonaws.com/chicosprod/export/store/FabricStoreInventorySync%5FCHO%5F2023-06-15T08-31-00-827090592Z.csv)\
Whenever data is requested, fabric will generate a S3 presigned URL to ensure secure access.
#### What's the primary use case of the fabric Orders service?
The fabric Order service is designed to streamline and simplify order management and fulfillment processes during and after an order is created either by using a checkout service or at the Point of Sale (POS). It contains features to simplify advanced configurations in addition to the standard post order operations and fulfillment workflow rules engine capabilities common to the functionalities and jobs supported by most Enterprise Order Management and Distributed Order Management Systems.
#### What are the key features of the fabric Orders module?
Backorder and Preorder, simplified configuration interfaces for setting post order validation and customer service policies, Customer Service and Returns Management operational interfaces, Digital Security and Role based access, Dropship integration and fulfillment, Incident Management, Fulfillment Rule Setting.
#### How can I get started with the fabric Orders module?
If you are using fabric Orders with fabric Store Fulfillment and fabric Inventory, you can start creating orders using the [order create endpoint](/v3/api-reference/orders/orders/create-new-order) after inventory is set up. Alternatively, you can disable inventory reservation for order fulfillment by contacting [fabric support](https://support.fabric.inc/hc/en-us/requests/new).
#### How does fabric Orders (also called OMS) handle the order fulfillment process?
Once order is created using fabric Orders service, it sends request to fabric’s Allocation module for order allocation, then Allocation calls Order Fulfillment Logic (OFL), OFL rules get the location number where the inventory is available, and responds back to Allocation, and Allocation calls inventory to reserved items for the location number received from OFL.
Order fulfillment process is set up by integrating your existing fulfillment systems, such as the Warehouse Management System (WMS), with the Allocation APIs of the fabric Orders module. This integration enables allocation-related events to start fulfillments in external systems, and it allows external systems to make callbacks to the fabric Allocation APIs.
Shipment APIs ensure that shipments are created for allocations. These APIs enable the warehouse or any external fulfillment system to generate shipments associated with the allocated orders.
You can establish the configuration for transactional email updates regarding orders by integrating your preferred email service with the Notification APIs of the fabric Orders module. This integration enables fabric Orders to start real-time email notifications for specific order update events.
To establish fraud prevention of orders, you can integrate your preferred fraud service with the Fraud APIs of fabric’s Order module. These APIs primarily allow for hold and release actions on the order, providing an effective means of preventing fraudulent activities.
You can set up shipment tracking updates for orders by integrating your carrier tracking service with the Shipment Tracking APIs of fabric’s Orders module. These APIs enable the external carrier tracking service, such as ParcelLab, to post shipment events.
#### Can fabric Orders handle orders from multiple channels?
Yes, the order create API can be integrated with systems such as web storefront, POS, and other sales channels. This integration enables the posting of orders to a centralized application database, ensuring a single source of truth for all orders.
When dealing with multi-brand orders that require separation of customer service and operational workflows, the `channel` field in the `order.channel` and `order.items.channel` JSON objects allows creating orders with separate groupings.
#### How does fabric’s Orders service manage returns and exchanges?
When processing returns using fabric’s Orders module, the result can be either a pending return for tracking purposes or an immediate completion of the return process for the order.
An order or items of an order are eligible for return if:
1. It has been fulfilled
2. The items to be returned haven't been previously returned
3. The item's eligible property isn't set to false in the check order return eligibility API response, which is configured via the Return Policies interface.
Return requests can be initiated using either the order ID or the order number as identification. The response object specifies refund amount, return fees to subtract from the refund, and reason codes for the return. If a refund for a returned item is successful, the response for the order return endpoint will display `refundStatus` as SUCCESSFUL. If the refund fails for any reason, the response for the order return endpoint will display `refundStatus` as REFUND\_FAILED. Order details can be accessed by calling the [return endpoints](/v3/api-reference/orders/returns/overview).
Exchange requests within fabric are initiated using the same [return endpoints](/v3/api-reference/orders/returns/overview) provided that the `isExchange` flag must be set to `true`.
#### How does fabric’s Orders module handle payment processing?
fabric Orders module can either be used to orchestrate payment operations, or payments can be disabled for the system. This is currently only configured by fabric Support during the onboarding process.
#### How does fabric’s Orders module manage tax calculations for different regions?
fabric Orders doesn't manage tax calculation. Taxes must be calculated by the client by using tax calculation services external to fabric, during update operations to the order.
#### Can I customize the interface and workflows within fabric’s Orders module to fit my business needs?
Yes, fabric provides the flexibility to customize the interface and workflows to support your business needs. An use case is creation of an order after shoppers complete the checkout process involves minimal data validation.
* You can configure data validation settings in the [attributes interface](/v3/guides/orders/settings/order-attributes), so that orders with invalid attributes or values can be flagged immediately after order placement.
* You can also configure the validation process for post-order updates, such as returns, exchanges, cancellations, appeasements, and pickups, using Policies in Copilot. This enables you to obtain eligibility information for these operations on a per-order basis and customize the workflow associated with these operations.\
**Note:** To know about the process of returning and canceling orders, refer to the guide that explains [canceling SKUs](/v3/guides/orders/order-management/cancel-skus) and the Orders [Cancellation API](/v3/api-reference/orders/cancellations/overview).
* You can manage backorder fulfillment settings such as the consent to delay workflow using the [backorder settings API](/v3/api-reference/orders/backorders=preorders/overview).
* Setting up integrations using the webhooks and integration-related APIs enables the notification of various order updates to shoppers, efficient allocation of orders to the most suitable warehouse or facility for inventory confirmation and product shipping, as well as the provision of shipment tracking updates.
#### How does fabric’s Orders module support my customer service team?
fabric’s customer service operations can be used either in the Copilot interface or within your existing customer service and relationship management application. fabric Orders doesn't currently offer native support for case management. However, retailers using a customer service application can choose to use fabric Copilot in addition to their existing customer service application or embed fabric Orders APIs for handling cancellations, returns, exchanges, appeasements, and other supported order updates directly within their CSR application.
#### Does fabric’s Orders module help generate sales and performance reports?
Yes, you can perform export operations using the export API, which can be utilized via integration for business intelligence and storing the data in external data warehouses. The exports service flattens the JSON structure into columns such that an external columnar database such as an SQL database can easily ingest the data effectively. Exports can also be generated via Copilot for ad-hoc analysis.
#### How does fabric’s Orders module handle international orders and shipping?
fabric Orders module includes the Crossborder API with basic hold and release functions for your external applications to manage the crossborder fulfillment process. The fabric databases also support all UTF-8 languages and support ISO 4217 currency codes during order create and update operations. These currencies and languages will reflect in any read operation via API or Copilot. There are no additional international order functions than these.
#### How's customer information stored and managed in the fabric Orders module?
Customer information is stored within the order JSON, and any bulk updates to customer data must be performed using the standard order update functions. The fabric Orders module doesn't maintain customer data in a separate collection. Additionally, a customer [edit API](/v3/api-reference/customers/customer-self/overview) is available for client web applications, simplifying the process of updating customer data within orders.
#### Does fabric’s Orders module support order migration from my existing platform?
Yes, fabric Orders provides a set of [import APIs](/v3/api-reference/developer-guide/order-and-inventory-import) to manage the order import process, primarily to support post-order operations on orders that may be required after transition from your current order services to fabric Orders.
#### How does fabric’s Orders module manage backorders and preorders?
During the order creation process within fabric Orders, backorders and preorders are identified and flagged accordingly. This enables the Backorder and Preorder service to store these orders in a dedicated backorder queue. Fulfillment of these orders follows a "first in, first out" approach as inventory becomes available for the backorders.
Additionally, consent to delay operations are implemented based on the configuration of backorder settings. Orders that exceed the specified backorder service level require customer consent to proceed with the delay. fabric triggers the consent to delay notification based on the merchant's configuration, and updates regarding consent to delay are managed through the consent to delay endpoint.
#### How does the fabric Orders module integrate with fabric Inventory?
By default, fabric Orders is designed to seamlessly integrate with fabric Inventory module for new users. Users of both modules get the advantage of real time updates ensuring that inventory availability is automatically updated as orders are fulfilled.
fabric provides the flexibility to its customers to disable fabric Orders and use fabric Inventory as a standalone module, as well as disable fabric Inventory and use fabric Orders as a standalone module. To disable or re-enable a module, please contact [fabric Support](https://support.fabric.inc/hc/en-us/requests/new).
The benefits of using modules independently are primarily for the purpose of implementing the strangler pattern, where the transition process occurs gradually on a service-by-service basis.
# Check appeasement eligibility by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/check-appeasement-eligibility
This endpoint checks for the appeasement eligibility of an order by order number.
# Check appeasement eligibility by order ID
orders.openapi post /orders/{orderId}/actions/check-appeasement-eligibility
This endpoint checks for the appeasement eligibility of an order by orderId.
# Check credits eligibility by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/check-credits-eligibility
When processing refunds, credits such as a gift card may be offered to customers for various reasons such as damaged products, later deliveries, or other qualifying factors as per your policy. This endpoint checks the credits eligibility by order number, allowing you to manage credits effectively and provide appropriate compensation to eligible customers.
# Get order exchange eligibility by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/check-exchange-eligibility
Customers may want exchange an item because of size, fit, color, or style preferences. Before processing exchange, it's crucial to verify whether the item is eligible for exchange as per your policy. This endpoint gets the exchange eligibility by order number. You can additionally specify `lineItemId` to get eligibility for a specific item.
**Note**: If you do not have the order number, but have the order ID, use the order ID-based endpoint - `POST /orders/{orderId}/actions/check-exchange-eligibility`.
# Create new order
orders.openapi post /orders
This endpoint creates a new order in the fabric Orders (OMS) system, regardless of whether it originates from fabric CnC service or an external system. The response includes an order ID, which is required for subsequent calls such as updating pickup information, getting order details, verifying eligibility for order cancellations, returns, exchanges, as well as creating appeasements, and processing order returns, cancellations, and exchanges.
# Find orders
orders.openapi post /orders/search
Customers may want to review their past orders or, as merchants, you may have to answer queries related to past orders, and analyze sales. To support the previously-mentioned use cases, this endpoint searches for orders based on filter conditions specified in the request body. By using `offset` and `limit` you can refine the search results. When they are not specified, you will get up to 10 results.
# Get order by order ID
orders.openapi get /orders/{orderId}
As a merchant, you may need to review or monitor an order to answer customer inquiries, resolve a complaint, or for analytics and reporting. With this endpoint, you can get order details by order ID. **Note**: If you do not have the order ID, use the corresponding order number-based endpoint - `GET /orders/order-number/{orderNumber}`.
# Get order by order number
orders.openapi get /orders/order-number/{orderNumber}
As a merchant, you may need to review or monitor an order to answer customer inquiries, resolve a complaint or for analytics and reporting. With this endpoint, you can get order details by order number. **Note**: If you do not have the order number, use the corresponding order ID-based endpoint - `GET /orders/{orderId}`.
# Getting Started with Orders
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Orders** API is a scalable multi-tenant service designed to streamline your order management process. Orders API is a REST and JSON driven interface enabling retailers to create orders directly from online Storefronts and Point-of-Sale systems, and serve as records of purchase transactions to permit retailers to operate against a standard schema with varied purchase channels.
fabric Orders API creates orders real time in the orders database, unifying the order data for users to streamline order lifecycle orchestration and customer service operations. It offers a range of features including the ability to create orders, get orders, update pickup details, and track orders, as well as search for existing orders. Also, the Orders API makes it easy to check eligibility of return, cancel, and exchange requests as well process them, if eligible. In addition, you can flag fraudulent orders based on due diligence, and either release them from hold or cancel them altogether. The appeasement feature helps you resolve any issues that may arise with an order and keep your customers happy.
# Update Shipping information for an existing order by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/update-attributes
The following endpoint is used to update attributes by order number.
# Update Order Attributes
orders.openapi post /orders/{orderId}/actions/update-attributes
The update attributes endpoint is used to update order attributes using the order ID. Attributes can be updated in the integration layer to modify external system related information.
# Update customer details for given order IDs
orders.openapi post /orders/actions/update-customer
In many scenarios, customer details may change over time. For example, a customer might change their email, phone, or company affiliation. By providing the order IDs and the updated customer details, this endpoint facilitates updating customer info for the given order IDs. This ensures order-related communication reaches the customer and they get timely customer service.
# Updates order pick-up details
orders.openapi put /orders/{orderId}/ship-info/{shipToId}/pickup
Customers can choose to either have their order delivered to them or opt to pick up from a store or warehouse. In a Buy Online Pickup in Store (BOPIS) scenario, there may be situations when the primary pickup person has changed. This endpoint allows for the updating pickup person details in BOPIS, ensuring that the most up-to-date information is available.
# Add items to shipping method
shipping-methods.openapi post /shipping-methods/{shippingMethodId}/actions/add-items
You may want to offer different shipping options for items based on their weight and dimensions, or you may want to offer promotional shipping rates based on order value, customer loyalty, etc. This endpoint lets you add items to an existing shipping method so that shoppers can see the options.
# Delete items from shipping method
shipping-methods.openapi post /shipping-methods/{shippingMethodId}/actions/delete-items
Certain items may need to be removed from a shipping method when they're discontinued, new shipping restrictions are imposed on hazardous items, or when they're not eligible for current promotions. Using this endpoint, you can delete one or more items from the given shipping method.
# Get item IDs for given shipping method
shipping-methods.openapi get /shipping-methods/{shippingMethodId}/items
You may want to determine what items are in a specific shipping method, to calculate shipping costs, verify the eligibility of items for specific shipping methods, or display the list of items to shoppers during the checkout process. This endpoint is used to get item IDs for a given shipping method.
# Get shipping methods
shipping-methods.openapi post /shipping-methods/actions/filter-by-item-id
You may need to periodically review shipping methods associated with an item, either to answer related queries or to verify they're up to date. This endpoint gets shipping methods for the given item ID.
# Create shipping method
shipping-methods.openapi post /shipping-methods
On your storefront, shipping methods determine how products are delivered to your customers. Some of the common shipping methods are domestic, international, free shipping, and express delivery. This endpoint is used to create a new shipping method. In the response, you will also get a shipping method ID, which will be required for subsequent calls to get, update, and delete this shipping method.
# Delete shipping method
shipping-methods.openapi delete /shipping-methods/{shippingMethodId}
When a particular shipping service is discontinued or certain shipping methods have become redundant or non-compliant with existing regulations, you may want to remove them so they're not shown to shoppers. This endpoint deletes a shipping method by ID.
# Find shipping methods
shipping-methods.openapi post /shipping-methods/search
At checkout, customers choose their preferred shipping method based on delivery timelines and costs. Moreover, it may be necessary for you to review available shipping methods to ensure they're current and accurate. To support these scenarios, you must get the latest shipping methods. This endpoint gets shipping methods based on given filter conditions.
# Get shipping method
shipping-methods.openapi get /shipping-methods/{shippingMethodId}
When an order is placed, the selected shipping method is stored as part of order details. You may need to review them for order related queries. This endpoint gets details of a single shipping method by ID.
# Update shipping method
shipping-methods.openapi put /shipping-methods/{shippingMethodId}
To comply with legal regulations and for other purposes, it may be necessary to update shipping rates or delivery timelines. With this endpoint, you can update shipping details by ID. This completely replaced existing information.
# Add or update items in a shopping list
lists.openapi post /lists/{listId}/actions/add-or-update-list-items
Once a shopping list is created, shoppers can add new item to it or update existing ones. This endpoint is used to add and update items in a list. - If the specified `sku` is not in the list, a new item is added to the list with the given `quantity`.
- If the specified `sku` is already in the list, its current quantity is updated based on the given `incQuantity`.
**Note**: At least one item must be in the request body.
# Delete items from shopping list
lists.openapi post /lists/{listId}/actions/delete-list-items
Over time, shoppers' preferences may change, or they might have added an item to their shopping list by mistake. This endpoint lets your shopper remove one or more products from the specified shopping list.
# Get shopping list and its items
lists.openapi get /lists/{listId}/actions/get-list-details
By specifying list ID, you can get shopping list details along with its items.
# Get shopping list items by list ID
lists.openapi get /lists/{listId}/list-items
Shoppers may periodically review their shopping list to check for discounts or when they are ready to make a purchase. This endpoint gets a paginated list of items by list ID. You can refine the results by specifying `offset` and `limit`. When they are not specified, you will get up to 10 records.
# Get shopping lists of a user along with associated items
lists.openapi get /lists/users/{userId}/actions/get-list-details-with-items
Shoppers may periodically review their shopping lists and their associated items. This endpoint gets shopping lists and associated items. For each list, you can view list ID, list name, user ID, list type, notes, custom attributes, items count, times of list creation and list update, as well as item details.
# Create shopping list
lists.openapi post /lists
Shoppers often choose to save their desired products in shopping lists to purchase later when they are ready or to take advantage of discounts when they are available. This endpoint creates a new shopping list. The response includes a list ID, which is required for subsequent calls to get, update, or delete this shopping list.
**Note**: Items cannot be added when the shopping list is initially created. To add items, use the *Add items to list* endpoint - `POST /lists/{listId}/actions/add-or-update-list-items`.
# Delete a shopping list by ID
lists.openapi delete /lists/{listId}
Shoppers need to remove unwanted or irrelevant shopping lists. With this endpoint, they can delete a list by list ID.
# Get a shopping list by ID
lists.openapi get /lists/{listId}
Get details of a shopping list by ID, along with the number of items in it.
# Get shopping lists of a user
lists.openapi get /lists/users/{userId}
Shoppers may want to periodically review their shopping lists and ensure they are up to date. This endpoint gets a paginated response of shopping lists by user ID. For each list, you can view user ID, list ID, list name, type, notes, custom attributes (if any), as well as time of list creation and update.
**Note**:
1. You can refine the results by specifying `offset` and `limit`. When they are not specified, you will get up to 10 records.
2. To view items in a list, refer to *Get lists with items* endpoint - `GET /lists/users/{userId}/actions/get-list-details-with-items`.
# Getting Started with Lists
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Shopping Lists** API is a multi-tenant service that allows your shoppers to manage their shopping lists for future purchases. Shoppers can create lists, add items to lists, update lists and list items, as well as delete unwanted lists and items. Shopping lists are a popular e-commerce feature allowing shoppers to save desired products for future purchase. It not only helps to minimize shopping cart abandonment but also provides valuable insights into product popularity. In addition, shoppers who maintain shopping lists can be engaged in targeted marketing campaigns, enhancing customer engagement and satisfaction.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersLists.json)
# Update a shopping list by ID
lists.openapi put /lists/{listId}
Shoppers like to update their shopping lists and keep them relevant. By specifying list ID, this endpoint lets your shoppers update their shopping list details such as list name, list type, notes, and custom attributes.
# Create multiple collections
category.openapi post /collections/batch
Collection is an alternative way to organize products compared to the original Category system; they're created based on merchant's requirements. This endpoint is used to create a new collection **Note**: You can create up to 25 collections in a single call.
# Update collections up to 25
category.openapi put /collections
With this endpoint, you can update up to 25 collections. You can also update collection details, such as add sub-collections, exclude sub-collections, add validation rules for attributes, or reorder collections. **Note**:
1. This endpoint replaces the existing details.
2. To avoid losing all details, for minor updates, use the `partially update collection` endpoint - `PATCH /collections/{id}`.
3.
# Copy Category to Collections
category.openapi post /collections/actions/copy-category
This endpoint is used to replicate category tree hierarchy to collections.
# Create collection
category.openapi post /collections
Collection is an alternative way to organize products compared to the Category system, which is the original organization of items. Because the Category system isn't granular enough to meet all the requirements of Storefronts, collections are used to organize products as per the merchant's requirements. This endpoint is used to create a new collection within the alternative organization so that it can be adapted to support various use-cases of Storefronts.
# Delete collection
category.openapi delete /collections/{id}
If there is a change in product offerings, one or more collections may become unnecessary. This endpoint is used to delete a collection by ID.
# Find collections
category.openapi post /collections/search
This endpoint enables you to find collections by the search criteria you specify in the request body. You can also `sort` the results.
# Get a single collection
category.openapi get /collections/{id}
Collections are used to organize and categorize products on your e-commerce platform (website and app), making it easier for shoppers to browse and find products. This endpoint gets category details such as basic info (ID, name, localized name, status, etc.), attributes details, categories included, categories excluded, associated child categories, and more.
# Get navigation path for collections
category.openapi get /collections-path
On the Storefront, products are organized in hierarchical tree structure of parent and children collections. This endpoint gets the navigation path starting from the root (level 0) until the given collections.
# Get products under collection
category.openapi get /collections/{id}/products
To ensure the right set of products are organized within a collection, it's important to review products in each collection. This endpoint gets a paginated list of products in a collection. **Note**: You can refine your search by specifying `offset` and `limit`. When they're not specified, you'll get up to 10 products by default.
# Collections
As the **Categories** system may not be sufficiently granular to accommodate all Storefront use cases, **Collections** provides an alternative means of organizing products on the storefront. Collections create a representational categorization of products, and are primarily used by merchants for short-term marketing campaigns. For instance, a collection could be created for a New Year sale that highlights discounted furniture products.
# Partially update collection
category.openapi patch /collections/{id}
In contrast to the Update Collection endpoint - `PUT /collections/{id}`, which fully overwrites the collection details, this endpoint allows for selective modification of specific details such as fixing any typos present in the collection name as well as facilitating addition or removal of attributes
# Update children of collection
category.openapi put /collections/{id}/children
This endpoint is primarily used to change display order of children collection.
# Update collection
category.openapi put /collections/{id}
With this endpoint, you can update details of a single collection, such as add or remove sub-collections, add validation rules for attributes, reorder collections, and more. **Note**:
1. This endpoint replaces the existing details.
2. To avoid impacting the entire data, for minor updates, use the Partially update collection endpoint instead - `PATCH /collections/{id}`.
# Create file object and get file upload location
files-jobs.openapi post /product-files
This endpoint creates a file object by specifying the import file's `type`, `name`, and `locale` in the request body. The response will include the URL location to upload the file.
# Download a file by ID
files-jobs.openapi get /product-files/actions/download
Use this endpoint to get a download link for imported file, which you can use to review or update the file . **Note**: The link is valid only for five minutes.
# Generate the import template
files-jobs.openapi post /product-templates/actions/generate
Bulk import must be in a standardized format. Using this endpoint, you can generate the template required to bulk import attribute, category, collection, item, and/or bundle.
# Get files available for a merchant
files-jobs.openapi get /product-files
Get files available for a merchant. This endpoint can be used to search for files using file names or file IDs. **Note**: Query parameter `ids` can't be combined with any other query parameters and pagination isn't supported when `ids` query is used.
# Bulk reassign products to a different category using filter conditions
product.openapi post /products/actions/filter-change-category
To enhance product visibility or improve product organization, you may want to reassign products to a different category. With this endpoint, you can asynchronously reassign products to a different category. Instead of waiting for results through the API response, you'll gets notified via email whether the products were successfully reassigned.
# Reassign products to a different category, synchronously.
product.openapi post /products/actions/change-category
To enhance product visibility or improve product organization, you may want to reassign products to a different category. With this endpoint, you can synchronously reassign up to 25 products to a different category. The response will show a list of successful and unsuccessful reassignments
# Cancel background jobs using job IDs
files-jobs.openapi post /product-jobs/{id}/actions/cancel
Cancel any in progress or scheduled background job by providing the job ID. Currently only supports item and variant import jobs.
# Get jobs related to products
files-jobs.openapi get /product-jobs
Get a paginated list of jobs related to products by specifying the query parameters such as job `ids`, `type`. You can refine the results by specifying `offset` and `limit`. **Note**:
1. Query parameter `ids` can't be combined with the rest of the query parameters and when it's specified, pagination isn't supported.
2. Query parameter `inputFileIds` supports up to 15 comma-separated file IDs and it can be combined only with the query parameter `lastJobOnly`. Pagination isn't supported when this parameter is used.
# Initiate job to export items and variants
files-jobs.openapi post /product-jobs/actions/export
Use this endpoint to trigger a job to export items and variants, by ids.
# Initiate job to export items and variants
files-jobs.openapi post /product-jobs/actions/filter-export
Use this endpoint to trigger a job to export items and variants based on the specified filter conditions.
# Search jobs
files-jobs.openapi post /product-jobs/search
Get a paginated list of jobs related to products and collections by specifying the request body. You need to specify the criteria for the search such as job `id`, `type`, `status`, `collectionId`, `inputFileId`.
# Change product category
product.openapi post /products/{id}/actions/change-category
This endpoint lets you change a product from one category to another. When managing a large number of products, this endpoint gives you the flexibility to organize products easily.
# Publish product by ID
product.openapi post /products/{id}/actions/publish
A newly added product can be in `Published` or `Draft` status. With this endpoint, you can publish the Draft version of a product.
# Unpublish product by ID
product.openapi post /products/{id}/actions/unpublish
Due to changes in market, you may have to remove a product from being live. With this endpoint, you can unpublish product.
# Get products in a bundle by SKU
product.openapi get /products/sku/{sku}/bundles
Bundle is a collection of products that are sold together as a single package. For example, a laptop is bundled with a carrying case and a wireless mouse to be sold as a package. This endpoint gets a paginated list of products by ID. **Note**:
1. You can refine the results by specifying `offset` and `limit` values. When they're not specified, by default, you'll get up to 10 products.
2. If you don't have product SKU, use the corresponding ID-based endpoint - `GET /products/{id}/bundles`.
3. The `status` parameter is applicable to the `id` passed as path parameter and not for bundles. That is, the bundles returned in the response are the bundles attached to either the Live or Draft version of the product based on the `status` parameter.
# Publish product by SKU
product.openapi post /products/sku/{sku}/actions/publish
A newly added product can be in `Published` or `Draft` status. With this endpoint, by specifying `sku`, you can publish a product in Draft status.
# Unpublish product by SKU
product.openapi post /products/sku/{sku}/actions/unpublish
Due to changes in market, you may have to remove a product from being live. With this endpoint, you can unpublish a product by specifying `sku`.
# Product Catalog - Files and Jobs API
Product team: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | License: [fabric API License](https://fabric.inc/api-license)
fabric's **Files and Jobs** API supports bulk import and export of items, attributes, and bundles.
Generally, the first step is to download the appropriate template for import. There are separate endpoints to get templates for items (`POST /item-import-templates`), attributes (`POST /attribute-import-templates`), and bundles (`POST /bundle-import-templates`).
Once the import details are filled out in the template, you need to provide the file name and type in the request body of the `POST /files/product` endpoint. In the endpoint response, you will get the URL to upload the file to be imported. Using job exports endpoints, you can export the uploaded products and attributes based on specified criteria.
For information on the optimal methods to import data into fabric, see [Data Ingestion Best Practices](v3/api-reference/product-catalog/data-ingestion-best-practices).
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/productsFileAndJobs.json)
# Product Catalog - Published Product Catalog API
Product team: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | License: [fabric API License](https://fabric.inc/api-license)
fabric Published Product Catalog API enables displaying products (items, variants, and bundles) and their details on your e-commerce platform (website or mobile app). Published products are products that are ready to be sold. These endpoints support getting one or more product details by product ID or SKUs also support search and filter functions, making it easier for shoppers to view product details such as descriptions, specification, images, and more. This will help them make informed purchases and enjoy a better shopping experience.
[Find out more about Product](https://developer.fabric.inc/v3/guides/product-catalog/overview)
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/productsPublishedProducts.json)
# Get collections by product ID
published-product.openapi get /published-products/{id}/collections
On your Storefront products are organized or grouped in logical groups called Collections. The main purpose of Collection is distribution management by displaying products on your website based on separate browsing structures required to achieve specific merchandising objectives, such as organizational requirements, multi-regional assortments, multi-channel assortments, and collections. This endpoint gets the collection details of a published product by ID. You can refine your search results by specifying query parameters - `collectionIds` and `collectionRootName` **Note**:
1. You can narrow down the results by specifying `offset` and `limit`. When they're not specified, by default, you'll get up to 10 products.
2. If you don't have product ID, use the corresponding item ID-based or SKU-based endpoints.
# Get products by IDs
published-product.openapi get /published-products/ids
Shoppers may want to view the products they've already identified or bookmarked, or you may want to promote a particular set of products as part of promotions. This endpoint get details of published products with or without variants, categories, bundle products, and collections. You can specify multiple comma-separated product `ids`. Using this endpoint, you can show up to 25 products on your Storefront. **Note**: If you don't have product ID, use the corresponding item ID-based or SKU-based endpoints.
# Get products in a bundle by ID
published-product.openapi get /published-products/{id}/bundle-products
A bundle is a collection of products that are sold together as a single package. For example, a laptop is bundled with a carrying case and a wireless mouse to be sold as a package. This endpoint gets a paginated list of published products in a bundle by bundle ID. You can refine your search results by specifying query parameters - `excludeBundleProducts`, `excludeCollections`, `excludeCategories` and `excludeVariants` **Note**:
1. You can refine the results by specifying `offset` and `limit`. When they're not specified, by default, you'll get up to 10 products.
2. If you don't have product ID, use the corresponding item ID-based or SKU-based endpoints.
# Get published product by ID
published-product.openapi get /published-products/{id}
Your Storefront must displays all the relevant information for shoppers to make an informed purchase decision. This endpoint gets details of a published product (item, bundle, or variant) by ID, which can be used to display product details on your Storefront. **Note**: If you don't have product ID, use the corresponding SKU-based or item ID-based endpoints.
# Get variants of published product by ID
published-product.openapi get /published-products/{id}/variants
Variants are the different versions of a product with different sizes, colors, or materials. For example, there are 12 variants of a laptop that comes in three sizes (13, 15, and 17 inches) and four colors (red, blue, grey, and white). By adding variants to products, you can offer shoppers more options. This endpoint gets a paginated list of variants of a published product by ID. **Note**:
1. You can narrow down the search results by specifying `offset` and `limit`. When they're not specified, by default you'll get up to 10 records.
2. If you don't have product ID, use the corresponding SKU-based or item ID-based endpoints.
# Get bundle products by bundle SKU
published-product.openapi get /published-products/skus/{sku}/bundle-products
A bundle is a collection of products that are sold together as a single package. For example, a laptop is bundled with a carrying case and a wireless mouse to be sold as a package. This endpoint gets a paginated list of published products in a bundle by bundle SKU. **Note**:
1. You can refine the results by specifying `offset` and `limit`. When they're not specified, by default, you'll get up to 10 products.
2. If you don't have product SKU, use the corresponding item ID-based or product ID-based endpoints.
# Get collections by product SKU
published-product.openapi get /published-products/skus/{sku}/collections
On your Storefront products are organized or grouped in logical groups called Collections. The main purpose of collection is distribution management by displaying products on your website based on separate browsing structures required to achieve specific merchandising objectives, such as organizational requirements, multi-regional assortments, multi-channel assortments, and collections. This endpoint gets the collection details of a published product by ID. You can refine your search results by specifying query parameters - `collectionIds` and `collectionRootName`. **Note**: If you don't have SKU, use the corresponding item ID-based or product ID-based endpoints.
# Get published product by SKU
published-product.openapi get /published-products/skus/{sku}
Your Storefront must displays all the relevant information for shoppers to help them make an informed purchase decision. This endpoint gets details of a published product (item, bundle, or variant) by SKU, which can be used to display product details on your Storefront. **Note**: If you don't have product SKU, use the corresponding item ID-based or product ID-based endpoints.
# Get published products by SKUs
published-product.openapi get /published-products/skus
Shoppers may want to view the products they've already identified or bookmarked, or you want to promote a particular set of products as part of promotions. This endpoint gets multiple published products based on `skus` (comma-separated values) and is useful to show product list (up to 25 products) on your Storefront. **Note**:
1. Using the examples you can see separate response for items, variants, and bundles.
2. If you don't have product SKU, use the corresponding item ID-based or product ID-based endpoints.
# Get variants of published products by SKU
published-product.openapi get /published-products/skus/{sku}/variants
Variants are different versions of a product with different sizes, colors, or materials. For example, there are 12 variants of a laptop that comes in three sizes (13, 15, and 17 inches) and four colors (red, blue, grey, and white). By adding variants to products, you can offer shoppers more options. This endpoint gets a paginated response of variants of a published product by SKU. **Note**:
1. You can refine results by specifying `offset` and `limit`. When they're not specified, by default you'll get up to 10 records.
2. If you don't have product SKU, use the corresponding item ID-based or product ID-based endpoints.
# Create counter
inventory.openapi post /inventory-counters
Create counter (also known as inventory position) for better tracking of inventories.
# Get all counters
inventory.openapi get /inventory-counters
Get all configured counters.
# Get counter by code
inventory.openapi get /inventory-counters/{counterCode}
Get details of a specific counter by specified counter code.
# Getting Started with Counters
Inventory Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Counters** API refers to inventory positions such as, available, in-transit, on-hand, or other custom positions. These endpoints let you read, update, and create custom counters that suit your business use case.
# Update counter by code
inventory.openapi put /inventory-counters/{counterCode}
Update a specific counter based on specified counter code.
# Create an inventory import file configuration
inventory.openapi post /inventory-import-configs
Create inventory import file configuration containing rules for queried file prefix
# Delete inventory import file config
inventory.openapi delete /inventory-import-configs/{id}
Delete inventory import file config containing rules for queried file prefix
# Force import halt
inventory.openapi post /inventory-imports/{importId}/actions/force-trigger
Force import halted due to zeroed out Inventories more than threshold
# Get uploaded file status and details
inventory.openapi get /inventory-imports/{importId}
Get uploaded file status and details by specifying `importId`.
# Get inventory import upload file configuration
inventory.openapi get /inventory-import-configs/{id}
Get inventory import file configurations containing rules for queried file prefix
# Get all file configurations
inventory.openapi get /inventory-import-configs
Get all file configurations for matching filter criteria
# Get uploaded files that match specified criteria
inventory.openapi post /inventory-imports/search
Get uploaded files that match specified criteria. Returned as paginated records.
# Import inventory data
inventory.openapi post /inventory-imports
Import inventory data by specifying file name. Successfully uploading the file triggers the import process, which is an event-driven extraction of the file's data to update the respective resource's system.
# Update inventory import file configuration
inventory.openapi put /inventory-import-configs/{id}
Update inventory import file configuration
# Inventory (3.0.0)
Inventory Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/inventory.json)
# Inventory FAQ
#### How can I upload inventory if I have more than one POS, WMS, or other sources of truth for inventory?
1. Prepare a `.csv` file with the inventory details.
2. Create a URL by using the bulk operation endpoint `POST/api/v2/inventory/aws/upload-url`.
3. Upload the `.csv` file to the URL.
#### What are counters and how can I update them?
Counters are inventory positions, such as on-hand, allocated, shipped, and other customized positions. The types of counters are:
1. **Base Counter:** Base counters refer to `onHand`, `Allocated`, `Shipped`, and any other custom counters that are created using the counter endpoint. Allocated counters are automatically calculated during the order workflow. Merchants can update all base counters, except `Allocated`, by using the following endpoints:
* Adjustment endpoint (`POST/v3/inventories/actions/find-and-adjust-inventory-counters`): Adjusts the counter quantity. Using this endpoint, you can only adjust the counter quantity, not other inventory details. You can increase or decrease the counter quantity by specifying the required quantity in the payload. For example, if the original counter quantity is 100 and you want to increase the quantity to 110, set the counter quantity as '+10' in the payload. The counter quantity is now updated to 110.
* Update inventory endpoint(`POST/v3/inventories/action/find-and-update`): Updates counter quantity and other inventory details.
2. **Virtual Counter:**. Virtual counters refer to the counters available to purchase, `availableToPurchase`, which are calculated or updated during the order workflow. When an order is placed, the Order Management System (OMS) automatically allocates the order for shipping. After the order is allocated and shipped, the counters available to purchase is calculated based on the formula `onHand - allocated - shipped`.
#### How's data security or privacy managed for fabric’s Inventory module?
fabric’s REST APIs are protected with OpenID Connect (OIDC) and the identity introspector mechanism. In OIDC, identity information is communicated using JSON Web Tokens (JWTs). The data in fabric is stored in both MongoDB and S3. The MongoDB data is isolated per tenant in fabric Orders (also called OMS). You must create an [AWS configuration rule](https://aws.amazon.com/blogs/security/how-to-use-aws-config-to-monitor-for-and-respond-to-amazon-s3-buckets-allowing-public-access/) to ensure that the AWS S3 Bucket doesn't have public access. For example, one shouldn't be able to run the following command:
`curl
`
Whenever data is requested, fabric will generate a S3 presigned URL to ensure secure access.
#### What's the primary use case for fabric’s Inventory module?
The primary use case for fabric Inventory is to prevent *overselling* during transactions by providing real-time inventory data via REST API and event-driven integrations, for the storefront and other downstream applications to accurately display available products for sale.
#### What's the primary interface for user operations?
fabric Copilot is the Graphical User Interface where users may log in to manage their data via interactive web pages. Copilot provides an easy way for users to manage recurring operational workflows such as updating data where the solution architecture requires manual intervention. Copilot is also an easy way for implementation specialists to manage test data creation, updates, and configurations.
#### What's the primary interface for setting up integrations with Storefront and other applications?
fabric’s Inventory service provides over 30 OpenAPI 3.0 compliant REST API endpoints, documented under the API Reference at [https://developer.fabric.inc/v3/reference/about-inventory](/v3/api-reference/inventory/inventory/overview), for users to manage data. These APIs are the same ones used in Copilot and can be integrated into the retailers enterprise systems such as the storefront, inventory management systems, search, marketing platforms, and more. Not all APIs are available in Copilot, and some are required to make use of fabric Inventory in the expected utilization of getting inventory in real-time from the storefront for use cases such as Ship-to-home, Omnichannel, and 'Buy Online Pickup In-Store' order placement.
#### How can I begin using fabric's Inventory module?
fabric’s Inventory module is typically packaged with fabric Orders (also called OMS). It provides enterprise-level inventory visibility with network aggregation and enables updating of order fulfillment logic without coding.
To get started using fabric’s Inventory module, follow these steps:
1. Sign up or log in to your fabric account.
2. Get an access token from fabric Copilot or using the [fetch access token](/reference/getaccesstoken) endpoint.
3. Familiarize yourself with the core concepts such as [Location](/docs/orders-locations), [Inventory](/docs/orders-inventory), [Network](/docs/orders-networks), Counter, Virtual Counter, and other available features and options as described in the guide.
4. [Import](/docs/orders-inventory#importing-inventory) or add your initial inventory data.
5. Set up any additional configurations or preferences specific to your needs.
#### What are the differences between counters and virtual counters in fabric?
**Counters**, also called base counters, refer to inventory positions such as `onHand`, `Allocated`, `Shipped`, and any other counters that are configured using the counter endpoint. These values can be updated through the **Inventory detail** page in fabric Copilot or using the adjustment endpoint- POST/v3/inventories/actions/find-and-adjust-inventory-counters. This lets you increase or decrease the counter quantity, but it doesn't allow you to change other inventory details. Alternatively, you can use the update inventory endpoint- POST/v3/inventories/action/find-and-update, which allows you to update both the counter quantity and other inventory details.
**Virtual counters** refer to the aggregation of real-time inventory availability. The inventory virtual counters are viewable on the inventory landing page in fabric Copilot. Their calculation from counters is configured in the virtual counter calculation. Basically, these are computed from counters at runtime. For example, `availableToPurchase = onHand - allocated - shipped`.
#### What's the significance of inventory-imports in fabric’s Inventory module?
For most retailers with a warehouse, point of sale, or other inventory source of truth system, the first step to begin using fabric Inventory (after generating your access token) is importing your inventory. As a user of fabric Inventory, you should integrate your one or many inventory systems of record, such as WMS, ERP, or POS, with fabric Inventory. This allows fabric Inventory to manage a SSOT ('Single Source of Truth') for reference of inventory in your commerce applications including storefronts, search functionalities, and other areas within your ecommerce solution architecture.
#### How can retailers integrate existing inventory systems with fabric Inventory?
**Single Inventory Management System**
If retailers have a single system of record for inventory, the inventory-import process doesn't require any configuration for multiple file groups. If retailers don't have a need to manage inventory aggregation, order fulfillment, or location data in fabric OMS (also called Orders), they can start importing inventory against the default location using the Import API. To import your inventory data to fabric, you must upload a CSV file with all inventory details. You can download sample CSVs from Copilot within the inventory import modal, for your reference.
**Multiple Inventory Management Systems**
If retailers have multiple systems of record for inventory, they can use the "file groups" feature to configure their inventory feeds in fabric. This feature ensures that inventory updates are limited to the specific group of locations corresponding to the inventory system performing the upload
**Inventory updates in real-time with event-driven data streaming**
If retailers want a more real time approach than relying solely on CSV-driven bulk imports, we recommend to directly update inventory levels on a single-inventory basis using the update [inventory API](/v3/api-reference/inventory/inventory/adjust-inventory-counters). To create or update inventory, you must provide the necessary fields including SKU, item ID, location, channel ID, and counters. If you are exclusively using the fabric Inventory module without the fabric Orders (OMS) module, you must manually update the reserved, allocated, and shipped counter quantities as orders are fulfilled.
#### Why should I use fabric Inventory as a Single Source of Truth for my Inventory?
For retailers with distributed inventory, fabric Inventory is an optimal solution for effectively managing the aggregation of real-time inventory into a Single Source of Truth (SSOT). For each location you want to manage inventory for, a location with a unique location number must exist. In addition, you can configure networks of locations sharing inventory using Network APIs.
For testing purposes, fabric Inventory is pre-configured with a default location where all inventory is initially assigned. To manage inventory for each specific location, it's necessary to have a unique location number to every SKU during bulk upload. You can configure networks of locations that share inventory, by using the Networks interface.
#### How do I manage Inventory aggregation in fabric?
Inventory aggregation rules can vary from simple to very complex. This is possible through the Network service of fabric’s Inventory module, which facilitates a real-time inventory aggregation functionality.
**Simple Aggregation**
If you manage inventory aggregation in an external system and don't plan to manage it within fabric, or if you don't have complex distributed fulfillment and inventory requirements, then the Simple Aggregation approach within fabric Inventory's Network feature may be suitable for your usage.
Your default network configuration is simple and requires no additional configuration to automatically aggregate all inventory in your “Sandbox” environment instance of fabric. This is possible because the rules in your default “starter” Network contains a rule for your default Location which dictates that, as long as the location `isActive` flag is set to “TRUE,” all inventory uploaded for your default location will be included in the aggregated inventory availability.
**Complex Aggregation**
Your network configuration can also be very complex. fabric’s Inventory Networks support the ability to create groups of inventory by defining “Inventory Networks” with inclusion and exclusion rules for inventory aggregation. Inventory Networks can aggregate inventory across groups of fulfillment centers for different selling requirements such as channels, brands, or fulfillment method eligibility. For example, you may want to create “Network C,” for domestic selling which includes all stores and warehouses, and “Warehouse Network,” for International selling which only includes warehouses. This can be achieved with the following two steps:
* First, create the rules ([https://developer.fabric.inc/v3/reference/createnetwork](/v3/api-reference/inventory/networks/create-inventory-network))for how inventory is aggregated in stores and warehouses. You may want to set up a rule set for “Network A” called “Store Network” and another rule set for “Network B” called “Warehouse Network,” each of which can have different inclusion and exclusion parameters based on the attributes of your location and product data.
* In the second step, you may want to set up “Network C,” naming it “Domestic Selling,” and making it a “Multiple Network” type which is created by selecting the store inventory and warehouse inventory through the Multiple Network setup process. Now, you have a way to combine inventory pools for Domestic, while simply relying on the “Warehouse Network” for International selling. For both networks, you can call the Inventory API to look up inventory in real-time on the storefront, such as the Product Display Page (PDP) and other use cases, by passing the network code in the request object.
Before utilizing Complex Aggregation to use product data in fabric’s Network rule-setting interface, you must decide whether to use fabric's Product Catalog or a third-party product information management system. If you are using a third-party system, you must provide product details to fabric’s Catalog Connector.
To use product data in the Network rule-setting interface, decide whether you are using fabric’s Product Catalog or a third-party product information management system. If using a third-party system, you need to provide product details to the Catalog Connector.
Also, define your location details using the Locations service through either [Copilot](/docs/orders-location) or the [APIs](/reference/location). You may also configure custom attributes on the location model if you want to extend the JSON data model to support more fields.
**Note:** Custom attributes only support key-value data in a single “attributes” object of the service collection response format. Once a custom attribute is configured, it will apply for all data in the service collection.
#### What are the advanced configurations and features of fabric’s Inventory service?
**1. Backorder and Preorder**
Managing backorder and preorder inventory follows the same workflows as regular inventory, allowing seamless management through both [Copilot](/docs/orders-pre-order-and-backorder) and [API interfaces](/v3/api-reference/orders/backorders-preorders/overview). In the fabric Inventory module, the primary feature of Backorder and Preorder is the ability to reduce the available quantity of backorder or preorder products so that the inventory remains balanced even when orders are placed, and the inventory is marked as `OnHand` for availability.
**2. Safety Stock and Low Stock Setting**
In addition to the import-inventory and network features, you may configure values for `safetyStock` and `lowStock` fields while creating or updating either networks or inventory.
**3. Infinite Inventory Flag**
If you want to represent an inventory in unlimited quantities, you may set `infiniteInventory` to 'true' and reference that attribute on the storefront and other downstream systems consuming inventory from fabric.
#### Can I use fabric Inventory without using the fabric Orders module. If so, how?
Yes, fabric provides the flexibility of using only Inventory service independently without implementing the whole of fabric’s order management system into your business.
If you're not using the fabric Orders module, you must manually update the 'allocated' and 'shipped' counters using the [adjust inventory endpoint](/v3/api-reference/inventory/inventory/adjust-inventory-counters) every time an order is created, allocated, and shipped. Similarly, you will have to update inventory records using the [update inventory endpoint](/v3/api-reference/inventory/inventory/update-inventory-by-adding-new-property). When updating the `onHand` counter, remember that the 'availableToPurchase' quantity is calculated based on the default formula `onHand - allocated - shipped - safetyStock`. Note that the `availableToPurchase` quantity can be customized based on requirement. Contact fabric Support to customize `availableToPurchase`.
#### How can I upload inventory data from multiple sources?
To upload inventory data from multiple sources, you must create an upload URL by using the bulk operation endpoint. Prepare a .csv file with all the inventory details from your POS, WMS, or other sources, then upload this file to the URL you have created.
# Adjust inventory counters
inventory.openapi post /inventories/actions/find-and-adjust-inventory-counters
With this endpoint, you can modify inventory counters (also known as inventory positions) to maintain accurate inventory records. These counters are adjusted when new inventory is received or when an item is shipped. If the inventory does not exist, an error message will be displayed. An inventory can have multiple counters, and all counters will be updated when this endpoint is used.
# Create inventory
inventory.openapi post /inventories
Create inventory based on the combination of location number, channel ID, and item ID or SKU.
# Find inventories of specific items
inventory.openapi post /inventories/actions/find
Search for inventories of specific items by SKUs, itemIds, location numbers, and other parameters as specified in the request body. This endpoint retrieves the exact available quantity of the searched inventory.
# Find inventory of specific items in a specific region
inventory.openapi post /inventories/actions/find-by-geography
Search for list of inventories of specific items in a specific region based on SKUs, postal code, latitude, longitude, and other details of the location as specified in the request body.
# Getting Started with Inventory
Inventory Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Inventory** API lets organizations use *Inventory* as a standalone service, which functions as the repository of product availability for order fulfillment. Typically, Storefront Websites use the Inventory service to retrieve data, while Warehouse Management Systems (WMS) use it to create and update inventory details. fabric's Inventory API includes high-performance endpoints built on highly scalable architecture, and includes a configurable data model to orchestrate the inventory lifecycle events.
# Search for inventories
inventory.openapi post /inventories/search
Search for inventories based on filter criteria.
# Update inventory by adding new property
inventory.openapi post /inventories/actions/find-and-update
Add a new property to existing inventory. **Note:** This endpoint does not override all the existing properties; rather it updates inventory by adding new properties or by updating the existing inventory properties that are specified in the request body. Inventory is identified based on the combination of location number, channel ID, and item ID or SKU.
# Cancel an outage using outageNumber
locations.openapi post /location-outages/outage-number/{outageNumber}/actions/cancel
Using the location outages cancel endpoint you can cancel a location outage by providing the `outageNumber`.
# Cancel an outage using outageID
locations.openapi post /location-outages/{outageId}/actions/cancel
The location outages cancel endpoint is used to cancel an outage by providing the `outageId`.
# Create a location
locations.openapi post /locations
Create a location to use for managing inventory and orders.
# Create Outage
locations.openapi post /location-outages
The location outages endpoint is used to create a location outage.
# Delete a location
locations.openapi delete /locations/{locationNumber}
Delete a location by location number.
# Get LocationOutages by query
locations.openapi post /location-outages/search
Get a filtered list of LocationOutages.
# Get a specific location
locations.openapi get /locations/{locationNumber}
Get a specific location by location number.
# Get locations by query
locations.openapi post /locations/search
Get a list of locations by specified filter criteria.
# Getting Started with Locations
Inventory Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Locations** API provides location endpoints that support multi-tenant services. This location data is used for both inventory management and order management. When an order is created, it's allocated to the nearest location according to the Order Fulfillment Logic.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/inventoryLocations.json)
# Search for nearby locations
locations.openapi post /locations/geography-search
Search for nearby locations based on city name, state, postal code, and other geographical details as mentioned in the request body.
# Update a specific location
locations.openapi put /locations/{locationNumber}
Update details of a specific location by location number.
# Update an outage by outageNumber
locations.openapi put /location-outages/outage-number/{outageNumber}
You can use the location outages outage number endpoint to update the details of a specific location outage by providing its outageNumber.
# Update an outage using outageID
locations.openapi put /location-outages/{outageId}
Update the details of a specified location outage by providing the `outageId`.
# Create inventory network
inventory.openapi post /inventory-networks
Create a network using conditional rules to add locations and SKU to the network.
# Delete network by code
inventory.openapi delete /inventory-networks/{networkCode}
Delete a specific network, with all of its details, by specified network code. Once deleted, it cannot be undone.
# Get all networks
inventory.openapi get /inventory-networks
Get a paginated list of all the created networks.
# Get network by code
inventory.openapi get /inventory-networks/{networkCode}
Get details of a specific network by code.
# Update network by code
inventory.openapi put /inventory-networks/{networkCode}
Update details of a specific inventory network by specified network code.
# Get allocation by ID
allocations.openapi get /allocations/{allocationId}
Get allocation details by allocation ID. The allocation ID can be obtained using the `/allocations/search` endpoint or stored externally, for example, in the WMS order database.
# Getting Started with Allocations
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Allocations** API lets retailers manage allocation for existing orders. Allocations serve as records of the locations from which an order is fulfilled. The user of the Allocation service is a Warehouse Management Service (WMS) or Point of Sale Service (POS).
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersAllocations.json)
# Search for allocations by query
allocations.openapi post /allocations/search
Search for inventory allocations based on the matching filter criteria.
# Update allocation or initiate reallocation
allocations.openapi put /allocations/allocation-request-id/{allocationRequestId}
Update allocation or initiate reallocation of the order by `allocationRequestId`.
# Update allocation attributes
allocations.openapi post /allocations/{allocationId}/actions/update-attributes
Update allocation attributes by `allocationId`.
# Create appeasement by order ID
orders.openapi post /orders/{orderId}/actions/create-appeasement
When customer is dissatisfied with their shopping experience, you may want to offer an appeasements amount such as partial refund to keep them happy. This endpoint is used to create appeasement request by order ID
. **Note**: If you do not have an order ID, but have an order number, use the order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/create-appeasement`.
# Create appeasement by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/create-appeasement
When customer is dissatisfied with their shopping experience, you may want to offer an appeasement amount to keep them happy. This endpoint is used to create appeasement request by order number.
**Note**: If you don't have order number, use the corresponding order ID-based endpoint - `POST /orders/{orderId}/actions/create-appeasement`
# Getting Started with Appeasements
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Appeasements** API endpoints help create appeasements.
# Get backorder or preorder details by ID
backorders-preorders.openapi get /backorders-preorders/{id}
Get backorder or preorder reservation details by ID.
# Getting Started with Backorders & Preorders
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Backorders and Preorders** API refer to orders placed for products not currently available for shipment or sale. Backorders are orders for out-of-stock products that will be shipped to customers as soon as they're available for shipment. Preorders are orders for products that aren't yet available in the market, but will be launched for sale. Customers can preorder products, and the products will be shipped when they're available for sale. fabric's Backorders & Preorders API supports multi-tenant service.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersBackorders.json)
# Record customer agreement to delay shipment
backorders-preorders.openapi post /backorders-preorders/{id}/actions/save-delay-consent
Record customer's agreement to delay the shipment.
# Search for backorders or preorders by query
backorders-preorders.openapi post /backorders-preorders/search
Search for the backorder or preorder reservations based on filter criteria.
# Cancel order by order ID
orders.openapi post /orders/{orderId}/actions/cancel
When customer's order cancellation request is determined to be eligible, this endpoint processes the cancellation by order ID. **Note**: If you do not have the order number, use the corresponding order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/cancel`.
# Cancel order by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/cancel
When customer's order cancellation request is determined to be eligible, this endpoint processes the cancellation by order number. **Note**: If you do not have order number, use the corresponding order ID-based endpoint - `POST /orders/{orderId}/actions/cancel`.
# Get order cancellation eligibility by order ID
orders.openapi post /orders/{orderId}/actions/check-cancel-eligibility
Either customer may initiate cancellation due to an incorrect order placement or as a merchant, you may initiate cancellation due to product unavailability, pricing errors, payment failure, or shipping restrictions. Before processing cancellation, it's crucial to determine the eligibility of the cancellation request. This endpoint gets the eligibility of order cancellation by order ID. You can additionally specify `lineItemIds` to get the eligibility of specific line items.
**Note**: If you do not have order ID, use the corresponding order number-based endpoint -`POST /orders/order-number/{orderNumber}/actions/check-exchange-eligibility`.
# Get order cancellation eligibility by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/check-cancel-eligibility
Either customer may initiate cancellation due to an incorrect order placement or as a merchant, you may initiate cancellation due to product unavailability, pricing errors, payment failure, or shipping restrictions. Before processing cancellation, it's crucial to determine the eligibility of the cancellation request. This endpoint gets the eligibility of the cancellation request by order number. You can additionally specify `lineItemIds` to get the eligibility of specific line items.
**Note**: If you do not have order number, use the corresponding order ID-based endpoint - `/orders/{orderId}/actions/check-cancel-eligibility`.
# Getting Started with Cancellations
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Cancellations** API endpoints check eligibility of order cancellation requests and if eligible, processes order cancellation.
# Check credits eligibility by order ID
orders.openapi post /orders/{orderId}/actions/check-credits-eligibility
In case of refund scenarios, credits such as gift card may be offered to customers for various reasons such as damaged products, later deliveries, or other qualifying factors as per your policy. This endpoint checks the credits eligibility by order ID, allowing businesses to manage credits effectively and provide appropriate compensation to eligible customers.
# Create credits by order ID
orders.openapi post /orders/{orderId}/actions/create-credits
Use this endpoint to create credits by order ID.
# Create credits by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/create-credits
The following endpoint is used to create credits using an order number.
# Update credit status by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/update-credit-status
The update credit status endpoint is used to update the credits status, notes, and additional credit attributes.
# Update credits by order ID
orders.openapi post /orders/{orderId}/actions/update-credit-status
Use this endpoint to update the credit status, as well as to add any associated notes and additional attributes.
# null
shipments.openapi post /shipments/inventory-transfer/{transferShipmentId}/action/cancel
# null
shipments.openapi post /shipments/inventory-transfer
# null
shipments.openapi get /shipments/inventory-transfer/{transferShipmentId}
# null
shipments.openapi post /shipments/inventory-transfer/query
# null
shipments.openapi post /shipments/inventory-transfer/search
# null
shipments.openapi post /shipments/inventory-transfer/{transferShipmentId}/actions/package-tracking-acknowledge
# null
shipments.openapi post /shipments/inventory-transfer/pack-unpack
# null
shipments.openapi post /shipments/inventory-transfer/{transferShipmentId}/action/receiving
# null
shipments.openapi post /shipments/inventory-transfer/actions/update-tracking
# Acknowledge financial transaction
invoices.openapi post /invoices/{invoiceId}/acknowledge
When an order is created or processed, fabric generates invoice and sends it to merchants or third-party systems for further financial processing of the order. This endpoint lets merchants acknowledge that they have received the invoice with payment information.
# Get invoice by ID
invoices.openapi get /invoices/{invoiceId}
Get details of an invoice by invoice ID.
# Getting Started with Invoices
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Invoices** API helps in generating invoices that can be used by any third party system for order fulfillment operation.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersInvoices.json)
# Search for invoices
invoices.openapi post /invoices/search
Search for invoices by matching filter criteria.
# Get acknowledgment receipt for notification
notifications.openapi post /oms-notifications/acknowledge
This endpoint gets notification acknowledgment from external service.
# Resend notifications
notifications.openapi post /oms-notifications/actions/resend
When an order is placed, the first notification is automatically sent to shopper. If the first notification isn't delivered for reasons such as incorrect email or server issues, this endpoint resends notification for specific events.
# Authorize order payments
orders.openapi post /orders/actions/authorize-payments
This endpoint is used synchronously or asynchronously for authorizing order payments pending for authorization.
# Getting Started with Order Payments
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Order Payments** API endpoints update payment status.
# Update order payment status by order ID
orders.openapi post /orders/{orderId}/actions/update-payment-status
This endpoint is used sync order payments when transactions happen externally. Additionally, used for updating order payment status and the amount, whether it is captured, refunded or void amount. If you don't have order ID, use the corresponding order number-based endpoint - POST /orders/order-number/{orderNumber}/actions/update-payment-status.
# Update status of order payment by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/update-payment-status
This endpoint is used sync order payments when transactions happen externally. Additionally, used for updating order payment status and the amount, whether it is captured, refunded or void amount. If you don't have order number, use the corresponding order ID-based endpoint - POST /orders/{orderId}/actions/update-payment-status.
# Get eligibility of returns for items in an order by order ID
orders.openapi post /orders/{orderId}/actions/check-return-eligibility
Customers may want to return one or more items because they do not meet the expectations or customer has changed their mind. Before processing return, it's crucial to verify whether the items are eligible for return as per your policy This endpoint gets the eligibility of your return by order number. You can additionally specify `lineItemId` to get the eligibility of a single line item.
**Note**: If you do not have the order ID, use the corresponding order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/check-return-eligibility`.
# Get order exchange eligibility by order ID
orders.openapi post /orders/{orderId}/actions/check-exchange-eligibility
Customers may want exchange an item because of size, color, or style preferences. Before processing exchange, it's crucial to verify whether the item is eligible for exchange as per your policy. This endpoint gets the eligibility of exchange request by order number. You can additionally specify `lineItemId` to get eligibility of a specific item.
**Note**: If you do not have the order ID, but have the order number, use the order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/check-exchange-eligibility`.
# Get order exchange eligibility by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/check-exchange-eligibility
Customers may want exchange an item because of size, fit, color, or style preferences. Before processing exchange, it's crucial to verify whether the item is eligible for exchange as per your policy. This endpoint gets the exchange eligibility by order number. You can additionally specify `lineItemId` to get eligibility for a specific item.
**Note**: If you do not have the order number, but have the order ID, use the order ID-based endpoint - `POST /orders/{orderId}/actions/check-exchange-eligibility`.
# Get return eligibility by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/check-return-eligibility
Customers may want to return one or more items because they do not meet the expectations or customer has changed their mind. Before processing return, it's crucial to verify whether the items are eligible for return as per your policy This endpoint gets the eligibility of return by order number. You can additionally specify `lineItemId` to get the eligibility of a single line item.
**Note**: If you do not have the order number, use the corresponding order ID-based endpoint - `POST /orders/{orderId}/actions/check-return-eligibility`.
# Order return by order ID
orders.openapi post /orders/{orderId}/actions/submit-return-request
When customer's return request is found to be eligible, this endpoint submits the return request by order ID. **Note**: If you do not have order ID, use the corresponding order number-based endpoint- `POST /orders/order-number/{orderNumber}/actions/submit-return-request`.
# Order return by order number
orders.openapi post /orders/order-number/{orderNumber}/actions/submit-return-request
When the customer's return request is determined to be eligible, this endpoint is used to process the return request. **Note**: If you do not have the order number, but have order ID, use Return order by order ID endpoint - `POST /orders/{orderId}/actions/submit-return-request`.
# Getting Started with Returns
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Returns** API endpoints check eligibility of order return or exchanges requests and, if eligible, processes order return or exchanges.
# Acknowledge shipment
shipments.openapi post /shipments/{shipmentId}/acknowledge
For users of fabric Webhook Service, Shipment related events can trigger HTTP callbacks to notify web clients through a merchant-defined URL/URI, typically an API Gateway for a middleware. While the response to fabric Webhook service HTTP call-back may occur, a secondary call-back can use this Acknowledge Shipment endpoint to indicate that a secondary external system has acknowledged this shipment event. Middleware receives the event, transforms it in a suitable format, and sends a success response back to fabric, confirming it received the event. It also sends the transformed event to an external merchant system (typically in XML or JSON).With this endpoint, middleware immediately sends an asynchronous acknowledgement to fabric, based on shipping ID, to indicate whether the call was successful. This acknowledgement is used for learning, auditing, and taking any necessary action.
# Create new shipment
shipments.openapi post /shipments
To use this endpoint an “allocation” must exist for the order that's being shipped. When an order is placed, fabric sends allocation details to external merchant system to create order fulfillment requirement details in an external system. With reference to the allocation that's being shipped, users of this POST API can create shipment details for allocations. **Note**: Shipment ID generated as part of the response is required for subsequent calls such as Acknowledge shipment (`POST /shipments/{shipmentId}/acknowledge`) and Get shipment (`GET /shipments/{shipmentId}`).
# Create re-shipment
shipments.openapi post /shipments/actions/re-ship
Orders may go missing before they're delivered to customers for reasons such as incorrect address, theft, labelling issues, or other reasons. This endpoint triggers reshipment in such cases for the existing location. **Note**: Shipment ID generated as part of the response is required for subsequent calls such as Acknowledge shipment (POST /shipments/{shipmentId}/acknowledge) and Get shipment (GET /shipments/{shipmentId}).
# Find shipments
shipments.openapi post /shipments/search
As merchants, you may want to view shipments of specific statuses, monitor progress of deliveries, and proactively manage situations to ensure timely deliveries. This endpoint enables you to easily search for shipments based on the specified criteria in the request body. You can refine your search by specifying `limit` and `offset`. When they're not specified, by default you will get up to 10 records. In addition, you can `sort` results.
# Get shipment by ID
shipments.openapi get /shipments/{shipmentId}
As merchants, you may want to resolve customer queries related to shipment or track a specific shipment to manage customer expectations with timely communication. This endpoint gets details of a single shipment by ID. You will get `shipmentId` by using the search endpoint, or by referencing a `shipmentId` on a file such as the Invoice.
# Getting Started with Shipments
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Shipments** API is a multi-tenant service that enables you to manage shipments for existing 'Allocations.' Shipments serve as records of the locations from which an order was fulfilled. Typical user of fabric Shipment service is a Warehouse management service or Point of Sale service.
**Note**: Shipment API relies on the Allocation service to send allocation details to external merchant systems after an order is placed. Allocation is the prerequisite for using Shipment API.
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/ordersShipments.json)
# Update gift card activation status
shipments.openapi post /shipments/{shipmentId}/actions/update-gift-cards-status
This endpoint is used to activate gift cards before they're delivered to the customer. Typically used by “adapters” or external web services integrated with gift card applications, so that gift cards can be activated as part of the fabric fulfillment workflow.
# Update shipment tracking
shipments.openapi post /shipments/actions/update-tracking
The update tracking endpoint creates a new tracking log that can be used to update the order status. The most common application of this endpoint is to connect to external web services or 'adapters' that have been integrated with carrier tracking applications. With this endpoint, fabric Shipment service gets information from carrier tracking applications, and in turn, updates customers about their shipment status.
# Get acknowledgement for package tracking by order number
orders.openapi put /orders/order-number/{orderNumber}/actions/package-tracking-acknowledge
This endpoint gets acknowledgement of package tracking by order number. **Note**: If you do not have order number, use the corresponding order ID-based endpoint - `PUT /orders/{orderId}/actions/package-tracking-acknowledge`.
# Get package tracking acknowledgement by order ID
orders.openapi put /orders/{orderId}/actions/package-tracking-acknowledge
This endpoint gets acknowledgement of package tracking by order ID. **Note**: If you do not have order ID, use the corresponding order number-based endpoint - `PUT /orders/order-number/{orderNumber}/actions/package-tracking-acknowledge`.
# Getting Started with Tracking
Orders Support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new) | URL: [https://www.fabric.inc](https://www.fabric.inc) | License: [fabric API License](https://fabric.inc/api-license)
fabric **Tracking** API endpoints track orders.
# Create a file object and retrieve the file upload URL
cc.openapi post /catalog-connector-files
Use this endpoint to retrieve the URL of the AWS S3 location to upload the file that you want to import to the Catalog Connector.
# Download a file by ID
cc.openapi get /catalog-connector-files/actions/download
Use this endpoint to retrieve the URL used to download a previously processed file. You can then make a GET request with this URL to retrieve the products data in CSV or JSONL format.
The download link is valid for five minutes.
# Retrieve import and export history
cc.openapi get /catalog-connector-files
Use this endpoint to access files previously imported to or exported from the Catalog Connector, sorted in chronological order. You can refine the search results by using the following query parameters:
- `ids`: Provide a comma-separated list of file IDs to retrieve multiple files by their IDs. Note that pagination isn't supported when using this parameter.
- Format type (`formatType`) : Specify the format of the file to filter files by format. The options are **CSV** or **JSONL**.
- Operation type (`type`): Use this parameter to specify whether you want imported or exported files.
- Pagination (`offset`, `limit`): Use offset and limit parameters to refine the number of results returned.
- `sort`: Use this parameter to view results in ascending or descending order.
If no query parameters are specified, the endpoint returns up to 10 records.
# Retrieve an import template
cc.openapi post /catalog-connector-templates/actions/generate
Use this endpoint to retrieve the product import template for Catalog Connector in either CSV or JSONL format, based on your preferred data handling method. You can open CSV template in applications, such as Excel or Google Sheets and JSONL template in text editors compatible with JSONL, such as Visual Studio Code. After filling in product data, save the template file with a unique name on your local system.
# Export products
cc.openapi post /catalog-connector-jobs/actions/export
Use this endpoint to start an internal job to export products from Catalog Connector.
Specify the `formatType` query parameter to export data in either CSV or JSONL format. In the request body, provide the `ids` of all products to be exported, the product type, and the locale.
# Retrieve jobs
cc.openapi get /catalog-connector-jobs
Use this endpoint to retrieve a paginated list of import and export jobs related to Catalog Connector.
The following constraints apply when using the query parameters:
- The query parameter job `ids` can't be combined with any other query parameters.
- The query parameter `inputFileIds` can only be combined with the query parameter `lastJobOnly`.
- Pagination isn't supported when `ids` or `inputFileIds` is specified.
# Delete a product by Item ID
cc.openapi delete /catalog-connector/products/itemIds/{itemId}
Use this endpoint to delete a single product by its `itemId`.
If you don't have the `itemId`, use one of the the endpoints to delete the product:
- [Delete a product by SKU](/v3/api-reference/catalog-connector/operations/sku-operations/delete-with-sku).
- [Delete a product by product ID](/v3/api-reference/catalog-connector/operations/product-operations/delete-by-product).
# Retrieve a product or a variant by Item ID
cc.openapi get /catalog-connector/products/itemIds/{itemId}
Use this endpoint to retrieve a single product by its `itemId`. You must specify the query parameters `itemId` and `locale`. Optionally, you can set the following query parameters to `true` to refine the search results:
You must specify the query parameters `itemId` and `locale`.
Optionally, you can set the following query parameters to `true` to refine the search results:
- `excludeBundleProducts`: Exclude bundled products from the response.
- `excludeCollections`: Exclude collections from the response.
- `excludeCategories`: Exclude categories from the response.
- `excludeAttributes`: Exclude attributes from the response.
- `excludeVariants`: Exclude variants from the response.
If you don't have the `itemId`, use one of the endpoints to retrieve the product:
- [Update a product by SKU](/v3/api-reference/catalog-connector/operations/sku-operations/update-with-sku).
- [Update a product by product ID](/v3/api-reference/catalog-connector/operations/product-operations/update-by-product).
# Update a product by the Item ID.
cc.openapi put /catalog-connector/products/itemIds/{itemId}
Use this endpoint to update a single product by using its `itemId`. You can update the product's details, such as its name, category details, product images, attributes, and collections. However, you can't update the `itemId`. The new data completely replaces the existing data.
You can update the product's details, such as its name, category details, product images, attributes, and collections. However, you can't update the itemId. The new data completely replaces the existing data.
If you don't have the `itemId`, use the one of the endpoints to delete the product:
- [Update a product by SKU](/v3/api-reference/catalog-connector/operations/sku-operations/update-with-sku).
- [Update a product by product ID](/v3/api-reference/catalog-connector/operations/product-operations/update-by-product).
# Add a product
cc.openapi post /catalog-connector/products
Use this endpoint to add a single product to Catalog Connector. You must specify the `locale` in the query parameter and the product data in the request body. Only `sku` is mandatory for product data. Optionally, you can specify the `type` as item, variant, or bundle. The default setting for `type` is item.
# Delete a product by product ID
cc.openapi delete /catalog-connector/products/{productId}
Use this endpoint to delete a single product by its `productId`.
If you don't have the `productId`, use one of the endpoints to delete the product:
- [Delete a product by SKU](/v3/api-reference/catalog-connector/operations/sku-operations/delete-with-sku).
- [Delete a product by item ID](/v3/api-reference/catalog-connector/operations/item-operations/delete-by-item).
# Retrieve a product by product ID
cc.openapi get /catalog-connector/products/{productId}
Use this endpoint to retrieve a single product by its `productId`.
You must specify the query parameters `productId` and `locale`.
Optionally, you can set the following query parameters to `true` to refine the search results:
- `excludeBundleProducts`: Exclude bundled products from the response.
- `excludeCollections`: Exclude collections from the response.
- `excludeCategories`: Exclude categories from the response.
- `excludeAttributes`: Exclude attributes from the response.
- `excludeVariants`: Exclude variants from the response.
If you don't have the `productId`, use one of the endpoints to retrieve the product:
- [Retrieve a product by SKU](/v3/api-reference/catalog-connector/operations/sku-operations/update-with-sku).
- [Retrieve a product by item ID](/v3/api-reference/catalog-connector/operations/item-operations/update-by-item).
# Update a product by product ID
cc.openapi put /catalog-connector/products/{productId}
Use this endpoint to update a single product by its `productId`.
You can update the product's details, such as its name, category details, product images, attributes, and collections. However, you can't update the productId.
The new data completely replaces the existing data.
If you don't have the `productId`, use one of the corresponding endpoints:
- [Update a product by SKU](/v3/api-reference/catalog-connector/operations/product-operations/update-by-product).
- [Update a product by item ID](/v3/api-reference/catalog-connector/operations/item-operations/update-by-item).
# Find products
cc.openapi post /catalog-connector/products/search
Use this endpoint to search for products based on names, IDs, SKUs, image URLs, and more. By specifying the appropriate query parameters, you can exclude one or more types of data, such as collections, categories, variants, attributes, and products within a bundle.
- Use the `CONTAINS` search operation to search for products based on keywords of SKU, name, and more.
- Use the `IN` search operation to search for products based on one or more values, such as IDs, names, SKUs, image URLs, attributes, and types.
- Use the less than or equals to, `LTE`, greater than or equals to, `GTE`, less than, `LT`, greater than, `GT` and equals `EQ` operations to search for date-specific values, such as time of creation or modification.
# Delete a product by SKU
cc.openapi delete /catalog-connector/products/skus/{skuId}
Use this endpoint to delete a single product by using its SKU.
If you don't have the product SKU, use one of the endpoints to delete the product:
- [Delete a product by product ID](/v3/api-reference/catalog-connector/operations/product-operations/delete-by-product).
- [Delete a product by item ID](/v3/api-reference/catalog-connector/operations/item-operations/delete-by-item).
# Retrieve a product by SKU
cc.openapi get /catalog-connector/products/skus/{skuId}
Use this endpoint to retrieve a single product by its SKU. You must specify the query parameters `sku` and `locale` to corresponding to the product. Optionally, you can set the following query parameters to `true` to refine the search results:
- `excludeBundleProducts`: Exclude bundled products from the response.
- `excludeCollections`: Exclude collections from the response.
- `excludeCategories`: Exclude categories from the response.
- `excludeAttributes`: Exclude attributes from the response.
- `excludeVariants`: Exclude variants from the response.
If you don't have the product SKU, use one of the endpoints to retrieve the product:
- [Retrieve a product by product ID](/v3/api-reference/catalog-connector/operations/product-operations/retrieve-by-product).
- [Retrieve a product by item ID](/v3/api-reference/catalog-connector/operations/item-operations/retrieve-by-item).
# Update a product by SKU
cc.openapi put /catalog-connector/products/skus/{skuId}
Use this endpoint to update details of a product by its SKU. You can update details of the product, such as the product name, category details, product images, attributes, and collections. The new data replaces the existing data. Note that you can't update the SKU.
If you don't have the product SKU, use one of the endpoints update the product details:
- [Update a product by product ID](/v3/api-reference/catalog-connector/operations/product-operations/update-by-product).
- [Update a product by item ID](/v3/api-reference/catalog-connector/operations/item-operations/update-by-item).
# Catalog Connector Overview
Catalog Connector is a denormalized data organization tool that enables merchants to link information from their third-party product information management system to their fabric account, making it accessible across fabric modules such as Offers, Orders, and Inventory.
This data can include technical specifications, such as size and weight, design attributes, such as color and material, and generic product details such as name, description, and ID.
Catalog Connector provides out-of-the-box integrations with fabric services, such as Orders and Offers, that enable merchants to apply base prices and promotions to any products available within the Catalog Connector.
Key Catalog Connector capabilities include:
* **Bulk Management:** Import product information in a CSV or JSONL file.
* **Catalog Management:** Manage product create, update, and delete actions, including parent, variant, and bundle products.
Catalog Connector is available exclusively to fabric users who don't have fabric’s proprietary Product Catalog service. Setting up Catalog Connector involves importing products, bundles, and their properties using a CSV or JSONL file.
Catalog Connector setup involves importing products and bundles and their properties in a CSV or JSONL file.
# Algolia standard integration
Use Algolia's search suite to enhance applications with search, recommendation, and browsing features by uploading product, pricing, and inventory data to Algolia. This integration enhances storefront functionalities including search, recommendations, and browsing based on your Algolia account settings. fabric aggregates product, pricing, and inventory data and sends it to Algolia SDKs for indexing.
fabrics Algolia integration supports the following key operations:
* Define index settings during customer onboarding process.
* Retrieve an index instance.
* Save index records.
* Delete index records.
### Setting up the Algolia Connector
1. Complete the setup and activation for your [Algolia](https://dashboard.algolia.com/users/sign%5Fup?ssnav=start) account.
2. Submit a support request to [fabric customer success](https://support.fabric.inc/hc/en-us/requests/new) with the following details and search configurations:
* [Algolia App Id](https://support.algolia.com/hc/en-us/articles/11040113398673-Where-can-I-find-my-application-ID-and-the-index-name)
* [Algolia Admin key](https://support.algolia.com/hc/en-us/articles/11972559809681-How-do-I-find-my-Admin-API-key)
* **Should Save Zero Price Item**: Setting this configuration to `true` checks for records with prices equal to zero and determines whether these items are indexed. The default value is `false`.
* **Should Save Variants**: Setting this configuration to `true` publishes variant records. The default value is `false`.
* **Should Index Alternate Categories**: Setting this configuration to `true` indexes product categories. The default value is `false`.
* **Should Use I18N Service** (Localization): Setting this configuration to `true` localizes indexed data. The default value is `false`.
* **Price Lists**: Setting this configuration to `Enabled` determines the list of `priceListIds` to be requested when calling fabric Offers APIs. This is used when an item has many currencies associated with the price. The default value is `null`.
### Next steps
After you have completed the initial setup, you must use the Algolia dashboard to make changes to your index settings.
# Avalara standard integration
Use Avalara's cloud solution to manage tax compliance such as calculating tax rates, returns, and documents. This integration connects to your fabric account and is used by the fabric storefront to calculate taxes during checkout using Avalara SDKs.
fabric's Avalara integration supports the following key operations:
* Creating an Avalara Tax Estimate
### Setting up the Avalara Connector
1. Complete the setup for your [Avalara account](https://home.avalara.com).
2. Submit a support request to [fabric customer success](https://support.fabric.inc/hc/en-us/requests/new) with the following details:
* **Avalara account ID**: Your unique Avalara account ID. For example, `110034662`.
* **Avalara API Key**: Your Avalara API Key used to make calls to the AvaTax API. For example, `C12EER1422IU76`.
* **Avalara company code**: Avalara assigns each company a unique code. For example, `NBF`.
* **Avalara customer code**: Avalara uses the customer code to calculate tax transactions. For example, `DEFAULT`.
* **Avalara environment**: Avalara supports multiple environments such as `Sandbox` and `Production` environments. Specify which environment you want to connect with fabric storefront.
# Constructor.io standard integration
Use the Constructor.io search suite to enhance search for product, pricing, recommendation, storefront, and inventory data. Constructor.io syncs with fabrics product information such as titles, colors, and SKUs. When an item is updated in Product Catalog, the event is captured and also sent to Constructor.io where it's processed using the Constructor.io SDK.
fabrics Constructor.io integration supports the following key operations:
* Creating an item in Constructor.io
* Deleting an item in Constructor.io
* Updating an item in Constructor.io
### Setting up the Constructor.io Connector
1. Complete the setup and activation for your [Constructor.io](https://constructor.io/) account.
2. Submit a support request to [fabric customer success](https://support.fabric.inc/hc/en-us/requests/new) with the following details:
* **Constructor.io API Key**: To find your API Key, go to the **API Integration** section of your Constructor.io account dashboard. The API Key field is labeled **Sample Collection**.
* **Constructor.io API Token**: To generate an API Token, click **Generate API Token** in the **API Integration** section of your Constructor.io account dashboard.
# Overview
fabric supports integrations with many of its core applications such as Product Catalog, Orders, Inventory, Cart, Checkout, and more. Integrations make working with your choice of a technical vendor easy without the need for custom code.
### Standard integrations
fabric has a set of pre-built standard integrations. These standardized integrations cover common use cases making them easy to set up. The following standard integrations are currently supported:
* [Stripe Connector](/v3/api-reference/integrations/stripe-standard-integration)
* [Algolia Connector](/v3/api-reference/integrations/algolia-standard-integration)
* [Constructor.io Connector](/v3/api-reference/integrations/constructor-io-standard-integration)
* [Avalara connector](/v3/api-reference/integrations/avalara-standard-integration)
Custom integrations aren't supported at this time.
### Security
fabric takes security seriously and always follows the recommended security standards. AWS secret manager handles all the values passing between the standard integrations and keeps everything encrypted. Additionally, fabric uses each integrations official SDK to send and receive encrypted data.
### Monitoring
Currently, fabric monitors all the standard integrations internally by a number of metrics such as latency. It's encouraged to use a standard integrations respective dashboard to receive more direct monitoring metrics. For example, to confirm a standard integration connector is working as intended, you can check the respective connectors dashboard. The dashboard displays changes that should be happening such as streaming product information updates or processing payments.
### Contact and support
If you have any additional questions, please reach out to [fabric customer success](https://support.fabric.inc/hc/en-us/requests/new).
# Stripe standard integration
Stripe connects to your fabric account and is used by the fabric storefront to process payments during checkout. The fabric checkout experience calls Stripe SDKs to authorize, process, refund, or void payments.
fabrics Stripe integration supports the following key operations:
* Create a payment
* Authorize payments
* Get a payment
* Capture a payment
* Refund a payment
* Void a payment
* Create a customer
* Get a customer
* Generate a client token
### Setting up the Stripe Connector
1. Complete the setup and activation for your [Stripe](https://stripe.com/) account.
2. Submit a support request to [fabric customer success](https://support.fabric.inc/hc/en-us/requests/new) with the following details and configuration settings:
* [Stripe Secret Key](https://stripe.com/docs/keys)
* [Stripe Public Key](https://stripe.com/docs/keys)
* **Auto capture authorization**: This configuration determines if the capture should be performed in the authorization request. The auto capture default is `false`.
* **Payment method deleted after authorization**: This configuration determines if the payment token should be kept or invalidated for later uses. The default value is set to `true` to perform token invalidation. This is so guest users can be handled for this integration.
# Search for inventory hard reservations
inventory.openapi post /inventories/actions/hard-reserve-search
Search for hard reservations based on filter criteria.
# Release soft reservation
inventory.openapi post /inventory-networks/actions/soft-release
Release soft reservation.
# Soft reservation
inventory.openapi post /inventory-networks/actions/soft-reserve
Soft reserve quantity.
# Create attribute
attributes.openapi post /attributes
Use this endpoint to create a new attribute. Attributes can be used as part of the qualifications for promotions or coupons.
# Get attribute
attributes.openapi get /attributes/{attributeId}
Using this endpoint, you can get details of an attribute by its ID.
# Bulk update coupon codes
coupon-codes.openapi put /coupon-codes/batch
Use this endpoint to update multiple coupon codes using identifiers. Identifiers are a unique combination of a coupon code and a promotion ID. You can update up to 25 codes at a time.
# Get all coupon codes
coupon-codes.openapi get /coupon-codes
This endpoint provides coupon code lists. Use parameters to filter results, for example, set `status` as 'ACTIVE' for active coupons, or add `userId` for user-specific coupon codes. Navigate the results using the query parameters `size` and `startCursor`.
# Create coupon
coupons.openapi post /coupons
Create a coupon with the requested conditions.
# Delete a specific coupon
coupons.openapi delete /coupons/{couponId}
Delete a specific coupon by ID
# Enable or disable a coupon
coupons.openapi post /coupons/{couponId}/actions/toggle
Change coupon status by ID. **Enable a coupon:** Only *disabled* coupons can be enabled. **Disable a coupon:** Only *not expired* coupons can be disabled.
# Generate coupon codes
coupons.openapi post /coupons/actions/generate-codes
Generate coupon codes based on the given parameter.
# Get all coupons
coupons.openapi get /coupons
Get a paginated list of coupons.
# Coupons
Coupons are discounts on items, carts, or shipping that are applied to qualified purchases when shoppers provide a valid coupon code during the checkout process. You can use the `coupon` endpoints to create and manage coupons and their codes.
# Retrieve a coupon
coupons.openapi get /coupons/{couponId}
Use this endpoint to retrieve the details of a coupon by its ID.
# Search for coupons
coupons.openapi post /coupons/search
Use this endpoint to search for coupons based on filter conditions.
# Update a specific coupon
coupons.openapi put /coupons/{couponId}
Update a specific coupon by ID.
# Exporting Offers CSV
This topic provides developers with step-by-step instructions for exporting product pricing data in CSV format using Offers export API endpoints. It includes initiating an export request and downloading a CSV file containing product prices, enabling seamless integration with pricing analytics, inventory management, or external reporting tools.
Exporting product pricing data as a CSV file involves three main steps:
1. [Initiate an export request](/v3/api-reference/offers/exports/initiate-export-request): Send a request to generate an `exportId` and configure filters to target specific data.
2. [Retrieve the export details](/v3/api-reference/offers/exports/get-export-request-by-id): Use the `exportId` to check the progress and retrieve the `fileId` after the export is complete.
3. [Download the CSV File](/v3/api-reference/offers/exports/download-exported-csv-file): With the `fileId`, obtain a download link to retrieve the CSV file.
## Export parameters
You can the refine the data included in your export by specifying filters in the `filters` array. If you leave the array empty, all data is included. The following table describes the parameters for filtering and the functions of each parameter:
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field` | Specifies the data type used to search. Use `priceType` to set it as the search criteria. |
| `value` | Specifies the exact value for the selected `field`. If `priceType` is used as `field`, you must enter the corresponding `priceType` value for this parameter. |
| `operator` | Specifies how the `value` is applied to the `field`. If the field is `priceType` and the operator is set to `EQUAL`, all products with the specified `value` are included in the search result. |
The following table provides detailed information for the two different data types:
* `CALCULATED_PRICE`: If the data type you want to export is `CALCULATED_PRICE`, use the following `field`, `operator`, and `value`:
| `field` | `operator` | `value` |
| ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `priceType` | `EQUAL` | Filter your data by `BASE` or `SALE` price. If the `filters` array in the request body is empty, both prices are included in the CSV export. |
| `priceListIds` | `IN` | Filter your data by a list of `priceListIds` by including them in an array in the request body. If the `filters` array is empty, the data is based on the default `priceList`. |
| `calculationTime` | `EQUAL` | Filter your data by an ISO timestamp to specify when the price should be calculated. The provided timestamp is used for price determination. If the `filters` array is empty, the price is based on the CSV execution time. |
* `REDEMPTION`: If the data type you want to export is `REDEMPTION`, use the following `field`, `operator`, and `value`:
| `field` | `operator` | `value` |
| ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `promoCode` | `EQUAL` | Filter your data by redeemed promotion code. |
| `userId` | `EQUAL` | Filter your data by provided user ID. |
| `email` | `EQUAL` | Filter your data by provided email. |
| `orderId` | `EQUAL` | Filter your data by provided order ID. |
| `redeemedAt` | - `EQUAL`
- `GREATER_THAN_OR_EQUAL_TO`
- `LESS_THAN`
| Filter data based on the provided redemption date. If the operator is: - `EQUAL`: Redemptions on the provided date.
- `GREATER_THAN_OR_EQUAL_TO`: Redemptions on and after the provided date.
- `LESS_THAN`: Redemptions before the provided date.
|
| `storeId` | `EQUAL` | Filter data based on case-insensitive promotion titles. |
| `promotionStatus` | `EQUAL` | Filter data based on the specified promotion status: - `ACTIVE`
- `EXPIRED`
- `DISABLED`
|
We recommend not to seach for all the `REDEMPTION` data by leaving the `filters` array empty.
## Prerequisites
* Ensure that you have Offers editor or administrator privileges to fabric Offers. For more information, see the [Role-Based Access Control](/v3/guides/settings/rbac/role-based-access-control-offers-roles) section.
* Ensure that you have added one or more products using one of the following methods:
* [Copilot](/v3/guides/product-catalog/list/items/adding-an-item)
* [API endpoints](/v3/api-reference/product-catalog/product-operations-by-id/add-product)
* Ensure that you have added price to the products using one of the following methods:
* [Copilot](/v3/guides/offers/pricing)
* [API endpoints](/v3/api-reference/offers/prices/create-price)
* Ensure that you have created a redemption for the products using the [create a redemption](/v3/api-reference/offers/redemptions/create-redemption) endpoint.
## Procedure
### Step 1: Initiating an export request
1. Submit a POST request including the `type`, such as `CALCULATED_PRICE` or `REDEMPTION` with any required `filters`.
The duration for this process increases with the amount of data being exported. The [initiate offers export](/v3/api-reference/offers/exports/initiate-export-request) endpoint initiates a CSV export request and generates an `exportId`. The following example shows a POST request with the request body set to `type` as `REDEMPTION`, searching for `storeId` with the value `store001`:
```bash
curl --request POST \
--url https://api.fabric.inc/v3/offers-exports \
--header 'Authorization: Bearer exampleToken123' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: exampleTenantID456' \
--data '{
"type": "REDEMPTION",
"filters": [
{
"field": "storeId",
"value": "store001",
"operator": "EQUAL"
}
]
}'
```
A successful request returns the following response:
```json
{
"exportId": "ab50fe48-5da0-4e77-92d1-bb629eedf19e",
"startedAt": "2023-05-17T21:24:52.398Z",
"endedAt": "null",
"totalDataExported": 0,
"status": "IN_PROGRESS",
"errors": [],
"type": "REDEMPTION",
"filters": [
{
"field": "storeId",
"value": "store001",
"operator": "EQUAL"
}
]
}
```
### Step 2: Retrieve the `fileId`
After initiating the export request, use the `exportId` generated in [step 1](#step-1-initiate-export-request) to [retrieve details of the request](/v3/api-reference/offers/exports/get-export-request-by-id). You can view the export details, such as `startedAt` and `endedAt` times, as well as the `totalDataExported`. The export request might take up to 10 hours.
1.[Submit a GET request using the `exportId`](/v3/api-reference/offers/exports/get-export-request-by-id) endpoint to check the export status to retrieve the `fileId`.
1. When the `status` is `COMPLETE`, use the `fileId` in the [download the exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) step to download the CSV file.
Use the following GET request to retrieve the details of an export request, including its status and `fileId`:
```bash
curl --request GET \
--url https://api.fabric.inc/v3/offers-exports/ab50fe48-5da0-4e77-92d1-bb629eedf19e \
--header 'Authorization: Bearer exampleToken123' \
--header 'x-fabric-tenant-id: exampleTenantID456'
```
A successful request returns the following response:
```json
{
"exportId": "ab50fe48-5da0-4e77-92d1-bb629eedf19e",
"startedAt": "2023-05-17T21:24:52.398Z",
"endedAt": "null",
"totalDataExported": 0,
"status": "IN_PROGRESS",
"errors": [],
"type": "REDEMPTION",
"filters": [
{
"field": "storeId",
"value": "store001",
"operator": "EQUAL"
}
],
"fileId": "redemption/tenantId/1687472977242-redemption-export.csv"
}
```
Wait until you receive a response with `status: COMPLETED` before moving to the next step. If you don't receive a `status` of `COMPLETED`, [you won't get a complete export file](#exported-file-is-incomplete).
### Step 3: Downloading the exported CSV file
1. After retrieving `fileId` from [step 2](#step-2-retrieve-the-fileid), include it in the request body of the [download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) endpoint to generate a temporary URL for downloading the file as shown in the following request:
```bash
curl --request POST \
--url https://api.fabric.inc/v3/offers-exports/actions/download-export-file \
--header 'Authorization: Bearer exampleToken123' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: exampleTenantID456' \
--data '{
"fileId": "redemption/tenantId/1687472972-redemption-export.csv"
}'
```
A successful request returns the following response with a URL used to download your file:
```json
{
"url": {Your Download URL},
"fileId": "redemption/tenantId/1687472972-redemption-export.csv"
}
```
You can copy and paste the URL from the response into your browser's address bar to download your file.
This URL is valid for 5 minutes. If you exceeded this duration, repeat [step 3](#step-3-download-exported-csv-file) to generate another URL.
## Common Variations
### Searching with multiple fields
You can include more than one `field` in the `filters` array as long as you are filtering single data type. Using more than one `field` allows you to refine the search results to meet all of the specified search conditions.
You can expand the following example of a POST request to initiate an export request with more than one `field`. In the following example, the request filters `CALCULATED_PRICE` by both `priceType` and `priceListIds`:
```bash
curl --request POST \
--url https://api.fabric.inc/v3/offers-exports \
--header 'Authorization: Bearer exampleToken123' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: exampleTenantID456' \
--data '{
"type": "CALCULATED_PRICE",
"filters": [
{
"field": "priceType",
"value": "BASE",
"operator": "EQUAL"
},
{
"field": "priceListIds",
"value": [
1000003,
1000004
],
"operator": "IN"
}
]
}'
```
A successful request returns the following response:
```json
{
"exportId": "4a73a9a9-b8c3-4dc1-a467-c528a1b2dfe7",
"startedAt": "2023-12-01T10:33:33.638Z",
"endedAt": "null",
"totalDataExported": 0,
"status": "IN_PROGRESS",
"errors": [],
"type": "CALCULATED_PRICE",
"filters": [
{
"field": "priceType",
"value": "BASE",
"operator": "EQUAL"
},
{
"field": "priceListIds",
"value": [
1000003,
1000004
],
"operator": "IN"
}
]
}
```
### Retrieving all export requests
If you have initiated multiple export requests, you can retrieve details of all export requests using the [Get all export requests](/v3/api-reference/offers/exports/get-all-export-requests) endpoint. A successful request returns an array containing details of all export request details, including the respective `fieldId` values. You can expand the following example to see the GET response:
```json
{
"query": {
"size": 10,
"offset": 10,
"count": 50
},
"data": [
{
"exportId": "ab50fe48-5da0-4e77-92d1-bb629eedf19e",
"startedAt": "2023-05-17T21:24:52.398Z",
"endedAt": "null",
"status": "IN_PROGRESS",
"type": "REDEMPTION",
"totalDataExported": 0,
"fileId": "redemption/tenantId/1687294954996-redemption-export.csv"
},
{
"exportId": "4a73a9a9-b8c3-4dc1-a467-c528a1b2dfe7",
"startedAt": "2023-12-01T10:33:33.638Z",
"endedAt": "null",
"status": "IN_PROGRESS",
"type": "CALCULATED_PRICE",
"totalDataExported": 0,
"fileId": "redemption/tenantId/5900139542278-calculated-price-export.csv"
}
]
}
```
## Troubleshooting
### `EXPORT_CALCULATED_PRICE_ERROR`
If you get the `EXPORT_CALCULATED_PRICE_ERROR` error after initiating an export request, resubmit the request. If the problem persists, contact [fabric support](https://support.fabric.inc/hc/en-us/requests/new).
### Exported file is incomplete
If your exported CSV is incomplete, use the [get export request](/v3/api-reference/offers/exports/get-export-request-by-id) endpoint and ensure that the `status` is marked as `COMPLETE`. If the `status` remains `IN_PROGRESS` after the 10-hours, try the request again or contact [fabric support](https://support.fabric.inc/hc/en-us/requests/new).
### CSV file download link not working
The download link is valid for only 5 minutes. If the link has expired, generate the link again using the [download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) endpoint. If the problem persists, contact [fabric support](https://support.fabric.inc/hc/en-us/requests/new).
## Related Topics
* [Initiate export request](/v3/api-reference/offers/exports/initiate-export-request)
* [Get export request by ID](/v3/api-reference/offers/exports/get-export-request-by-id)
* [Get all export requests](/v3/api-reference/offers/exports/get-all-export-requests)
* [Download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file)
# Offers (3.0.0)
Offers support: [fabric support](https://support.fabric.inc/hc/en-us/requests/new)| License: [fabric API License](https://fabric.inc/api-license)\
fabric Offers service supports two sets of APIs. The first set is for managing the Create, Retrieve, Update, and Delete (CRUD) operations for objects, such as prices, promotions, and coupons. The second set is our [Real-Time Pricing Engine (RTPE)](/reference/dynamic-pricing-engine) designed to power your site experiences, such as displaying prices and promotional discounts on a Product Description Page (PDP) or shopping cart.
### Related Resources
* [Offers](/v3/guides/offers/overview)
* [Prices](/v3/api-reference/offers/prices/overview)
* [Promotions](/v3/api-reference/offers/promotions/overview)
* [Coupons](/v3/api-reference/offers/coupons/overview)
[Download Postman Collection](https://github.com/FabricCommerce/public-fabric-api-postman-collections/blob/main/v3/offers.json)
# Create price list
price-lists.openapi post /price-lists
Create a price list. Based on the currency code you define for a price list, you will be able to create or update prices under the price list for the defined currency code only.
# Delete a specific price list
price-lists.openapi delete /price-lists/{id}
Delete a specific price list by ID.
# Get a specific price list
price-lists.openapi get /price-lists/{id}
Get a specific price list by ID.
# Get all price lists
price-lists.openapi get /price-lists
Get a paginated list of all price lists.
# Price Lists
A price list is a collection of items and their assigned prices. You can add the same item to multiple price lists and set different prices for that item in each of those lists. For example, for the same item, you can assign a one-time purchase price, a subscription price, or a special loyalty member price. You can set the currency and duration of the prices in each price list. If the price list expires, the prices of items within the price list will also expire.
# Update a specific price list
price-lists.openapi put /price-lists/{id}
Update a specific price list by ID.
# Create batch prices
prices.openapi post /prices/batch
Create one or more prices for items based on `itemId` and `itemSku`.
# Create price
prices.openapi post /prices
Create or update price of an item based on given `itemId` and `itemSku`
# Delete price by itemId
prices.openapi delete /prices/{itemId}
Delete price details by `itemId`. If `priceListId` isn't specified, price is deleted for the `itemId` that belongs to the default price list.
# Delete price by SKU
prices.openapi delete /prices/sku/{sku}
Delete price record for the given `sku` and `priceListId`.
# Get all active prices
prices.openapi get /prices
Get a paginated list of active and scheduled prices. Active prices have start date greater than the current date and end date is in the future.
# Get price by itemId
prices.openapi get /prices/{itemId}
Get a paginated list of price details for the given `itemId` and `priceListId`. If `priceListId` isn't specified, prices are retrieved for the `itemId` that belongs to the default price list.
# Get price by SKU
prices.openapi get /prices/sku/{sku}
Get price details for the `sku` and `priceListId`. If `priceListId` isn't specified, price is retrieved for the `sku` that belongs to the default price list.
# Prices
Pricing endpoints let you create and manage price details for one or more items. You can configure the prices endpoints to include your default price list in all requests.
# Create product exclusion list
product-exclusion-lists.openapi post /product-exclusion-lists
Create a product exclusion list with target products that will be exempted from being discounted.
# Delete a specific product exclusion list
product-exclusion-lists.openapi delete /product-exclusion-lists/{id}
Delete a specific product exclusion list by ID.
# End a product exclusion list
product-exclusion-lists.openapi post /product-exclusion-lists/{id}/actions/end
End a product exclusion list by setting the start date and end date to the same current date. When you end a product exclusion list, target products of the product exclusion list become eligible for discounts.
# Get a specific product exclusion list
product-exclusion-lists.openapi get /product-exclusion-lists/{id}
Get a specific product exclusion list by ID. The response contains a list of target products that are exempted from being discounted based on the `scopes` value.
# Get all product exclusion lists
product-exclusion-lists.openapi get /product-exclusion-lists
Get a paginated list of product exclusion lists based on the query parameters.
# Product Exclusion Lists
Product exclusion lists let you protect SKUs from being discounted by active promotions. These endpoints let you create and manage such product exclusion lists.
# Update a specific product exclusion list
product-exclusion-lists.openapi put /product-exclusion-lists/{id}
Update a specific product exclusion list record by ID.
# Create promotion
promotions.openapi post /promotions
Create a promotion that you can apply to one or more items to increase sales, or to a segment of customers to reward existing customers or attract new customers. Promotions are configured with rules that define the type of promotion, conditions, and discounts.
# Delete a specific promotion
promotions.openapi delete /promotions/{promotionId}
Delete a specific promotion by ID.
# Enable or disable a promotion
promotions.openapi post /promotions/{promotionId}/actions/toggle
Use this endpoint to change promotion status by enabling or disabling a promotion. Note that you can't change the status of a promotion that's currently _ACTIVE_. You can enable the promotions that are currently _disabled_ and disable the promotions that haven't expired yet.
# End a promotion
promotions.openapi post /promotions/{promotionId}/actions/end
End a specific promotion by ID. To end a promotion, set `status` to `EXPIRED`, and expiration date (both `startAt` and `endAt`) to the same current date.
# Get a specific promotion
promotions.openapi get /promotions/{promotionId}
Get a specific promotion by ID.
# Get all promotions
promotions.openapi get /promotions
Get a paginated list of all promotions.
# Promotions
Promotions are discounts on items, carts, or shipping that are applied automatically if the required conditions are met. Using the `promotions` endpoints, you can create and manage promotions.
# Search for promotions
promotions.openapi post /promotions/search
Use this endpoint to search for promotions based on filter conditions.
# Update a specific promotion
promotions.openapi put /promotions/{promotionId}
Update a specific promotion by ID.
# Calculate prices for products by IDs
price-engine.openapi post /price-engine/actions/evaluate-products-by-id
Use this endpoint to calculate prices for one or more products in a specific price list based on product IDs. Note that the `itemId` is the default identifier of a product. If you want to set SKUs as the identifier of a product identifiers, reach out to the fabric support at support@fabric.inc.
# Calculate prices for products by SKUs
price-engine.openapi post /price-engine/actions/evaluate-products-by-sku
Use this endpoint to calculate prices for one or more products in a specific price list by product SKUs. Note that the `itemId` is used as the default identifier for a product. If you want to set SKUs as product identifiers, you must contact fabric support at support@fabric.inc.
# Evaluate cart promotions
price-engine.openapi post /price-engine/actions/evaluate-cart
Evaluate cart's total cost instantly, after applying all applicable promotions and discount coupons. Using this endpoint, submit a range of data that will be referenced against the conditions that are set earlier using the promotions, coupons or prices APIs. The response includes the details of the promotions and discounts applied. These promotions and discounts can be displayed on your website to help shoppers know that they're getting their expected discounts.
# Real-time Pricing Engine
fabric’s Real-time Pricing Engine (RTPE) endpoints calculate prices and evaluate discounts for individual products and carts.
* The endpoints `Get prices by item ID` and `Get prices by product SKUs` are used to power product description pages.
* The endpoint `Evaluate cart promotions` is used to determine prices and returns cart-level promotions.
* Both the base price and sales prices are included.
* Use segments to target specific customer groups with particular promotions.
* Settings specific to stacking influence how RTPE applies promotions, determining which can be combined and in what order.
RTPE relies on cached information rather than getting product offers from the database. This approach is useful for immediate evaluation of promotions and price calculations. It's designed for speed, supports intricate promotional strategies, and handles millions of pricing requests daily.
# Bulk update redemptions
redemptions.openapi put /redemptions/batch
Use this endpoint to update multiple redemptions. You can update up to 25 redemptions at a time.
# Create redemption
redemptions.openapi post /coupons/{couponId}/redemptions
Create redemption for a specific coupon by coupon ID.
# Create redemption
redemptions.openapi post /redemptions
Create a redemption record for a specific promotion.
# Delete redemption by ID
redemptions.openapi delete /coupons/{couponId}/redemptions/{redemptionId}
Delete a specific redemption by redemption ID.
# Delete redemption by ID
redemptions.openapi delete /redemptions/{redemptionId}
Delete a specific redemption by redemption ID.
# Get all redemption details
redemptions.openapi get /redemptions
Use this endpoint to get a list of redemption records. You can also filter the records by using different parameters, such as coupon code, user ID, email address, order ID, store ID, and more.
# Get redemption by ID
redemptions.openapi get /redemptions/{redemptionId}
Get a specific redemption by redemption ID.
# Redemptions
Redemptions are used to track the usage of coupons or promotions by shoppers. The redemption records are used to keep track of [coupon limits](/docs/offers-coupons#coupon-limits) across the site or per customer.
# Update redemption by ID
redemptions.openapi put /redemptions/{redemptionId}
Update a specific redemption by redemption ID.
# Create segment
segments.openapi post /segments
Create a segment to group a specific set of customers. By segmenting customers, you can gain insight into which products are popular among different customer segments, and can create targeted retention strategies. You can also create targeted marketing campaigns that can result in higher conversion rates and increased sales.
# Delete a specific segment
segments.openapi delete /segments/{segmentId}
Delete a specific segment by ID.
# Get a specific segment
segments.openapi get /segments/{segmentId}
Get details of a specific segment by ID.
# Get all segments
segments.openapi get /segments
Get a paginated list of all the created segments.
# Segments
Segmentation is a way of grouping customers that share similar characteristics, such as loyalty status, demographics, location, or device type. Using the `segment` endpoints, merchants can create and manage segments. After creating a segment of customers, merchants can target promotions to a specific customer segment by linking the promotion to a segment identifier.
# Update a specific segment
segments.openapi put /segments/{segmentId}
Update a specific segment by ID.
# Coupon
### Overview
Coupons are used to apply discounts on items, carts, or shipping during the checkout process. By subscribing to coupon-related events, as merchants, you can get event-specific information, including coupon ID, event name, and event status.
The following table details various coupon-related events along with the example responses:
### Events
| Event Type | Description | Example Response |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offers:coupon:created | The event is triggered when a coupon is created. | `{ "specversion": "v1", "type": "offers:coupon:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "CREATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:coupon:deleted | The event is triggered when a coupon is deleted. | `{ "specversion": "v1", "type": "offers:coupon:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "DELETED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:coupon:updated | The event is triggered when a coupon is updated. | `{ "specversion": "v1", "type": "offers:coupon:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "UPDATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:coupon:enabled | The event is triggered when a coupon is enabled. Only disabled coupons can be enabled. When a coupon is enabled, shoppers can use them to get a discount on eligible products. | `{ "specversion": "v1", "type": "offers:coupon:enabled", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "ENABLED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:coupon:disabled | The event is triggered when a coupon is disabled. When a coupon is disabled, shoppers can't use them to get a discount on their purchases. | `{ "specversion": "v1", "type": "offers:coupon:disabled", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "DISABLED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:coupon:activated | The event is triggered when a coupon becomes active and is available for use. | `{ "specversion": "v1", "type": "offers:coupon:activated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "ACTIVATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:coupon:deactivated | The event is triggered when a coupon is deactivated and is no longer available for use. | `{ "specversion": "v1", "type": "offers:coupon:deactivated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON", "status": "DEACTIVATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:couponCode:created | The event is triggered when a coupon code is created. | `{ "specversion": "v1", "type": "offers:couponCode:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON-CODE", "status": "CREATED", "promotionId": "642babcd3ebd250008455701","couponCode":"ABC-123" "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:couponCode:updated | The event is triggered when a coupon code is updated. | `{ "specversion": "v1", "type": "offers:couponCode:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "COUPON-CODE", "status": "UPDATED", "promotionId": "642babcd3ebd250008455701","couponCode":"ABC-123" "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
# Global Exclusion
### Overview
Global exclusion refers to a list to which you can add SKUs to prevent them from being discounted by active promotions. By subscribing to global exclusion events, as merchants, you can get event-specific information, including the ID of the global exclusion list.
The following table details various global exclusion events along with the example responses:
### Events
| Event Type | Description | Example Response |
| ------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offers:globalExclusion:created | The event is triggered when a global exclusion list is created. | `{ "specversion": "v1", "type": "offers:globalExclusion:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "GlobalExclusion", "status": "CREATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:globalExclusion:deleted | The event is triggered when a global exclusion list is deleted. | `{ "specversion": "v1", "type": "offers:globalExclusion:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "GlobalExclusion", "status": "DELETED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:globalExclusion:updated | The event is triggered when a global exclusion list is updated. | `{ "specversion": "v1", "type": "offers:globalExclusion:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "GlobalExclusion", "status": "UPDATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
# Glossary
This section collects brief definitions of some of the technical terms used in the documentation for Convoy.
### Projects
Projects are used to create logical contexts or separate environments (dev, staging & production). Different projects can also be created for different teams each with its own login details on the same convoy deployment.
### Endpoints
An endpoint represents a target URL to receive events. An endpoint can be in either of these states - `active`, `inactive` or `pending`. When an endpoint is in the `inactive` state all events sent will be saved but not dispatched until the endpoint is re-enabled. These events are known set to the `Discarded` state.
### Events
An event represents a specific event triggered by your system. Convoy persists events sent to [dead endpoints](#dead-endpoints) with a status - `Discarded`. This enables users re-activate their endpoints and easily retry events without the need to re-trigger the events from your systems.
### Event delivery
An event delivery is resource that tracks successive attempts to deliver the event payload to each endpoint. Multiple event deliveries can be created for a single event, this is influenced by the number of subscriptions that are matched to it.
### Event Types
Events are sent to an endpoint depending on the event type, which is defined when creating the endpoint defaulting to `"*"` if not set, which is a catch all for all events. An endpoint can define multiple event types, as such it will receive an event from all those events. Event types are matched using direct string comparison and are case sensitive. Support for regex event matching is planned.
### Delivery Attempts
A delivery attempt represents a single attempt to dispatch an event to an endpoint. Specifically, it contains two things - Request Headers & Payload, Response Headers & Payload. Convoy records this information for every retry attempt sent. The UI currently shows only the last delivery attempt. The number of delivery attempts and retry strategy can be configured per group.
### Dead Endpoints
A dead endpoint is an endpoint that failed consecutively to acknowledge events. Currently, we define consecutively failures as at least one event as maxed out it's retry limit to the maximum configured. In the future, we should support different consecutive failure strategies.
### Secrets
Secrets are used to sign the payload when sending events to an endpoint. If you don't supply a secret convoy will generate one for you.
### Hash Functions
We've found out that most implementations use `SHA256` or `SHA512`. However, Convoy also supports the following hash functions:
* `MD5`
* `SHA1`
* `SHA224`
* `SHA256`
* `SHA384`
* `SHA512`
* `SHA3_224`
* `SHA3_256`
* `SHA3_384`
* `SHA3_512`
* `SHA512_224`
* `SHA512_256`
### Replay Attacks
A replay attack occurs when an attacker intercepts a valid network payload with the intent of fraudulently re-transmitting the payload. Convoy supports replay attack prevention by including a timestamp in the request header under the key `Convoy-Timestamp`. This timestamp is also included in the signature-header and is signed together with the request body using the endpoint secret. Therefore, an attacker can't change the timestamp without invalidating the signature. Take the following steps to verify your signature and prevent replay attacks;
* Extract the timestamp and the signed signature-header from the request header, extract the request body.
* Prepare a string by concatenating the timestamp followed by a `,` and the request body.
* Generate a signature of the concatenated string using the endpoint secret and your hashing algorithm (e.g `SHA256`)
* Compare the newly generated signature with the value in the signature-header, if the signatures match, check the time interval between the timestamp and the current time. In your system, set a tolerance on this time interval to prevent replay attacks.
### Rate Limiting Endpoints
While you are guaranteed you'll be able to receive events as fast as possible using convoy, your customers might not be able to handle events coming to their systems at the same rate which might cause a disruption of service on their end. You can control the number events you want to send to an endpoint by setting a rate limit and a rate limit duration on each endpoint. The default is `5000` in `1m` or 5,000 requests per minute.
### Retry Schedule
When an endpoint is experiencing temporary disruption of service, events sent to them might fail to require you to retry them. Convoy allow you to set the number of attempts to a particular endpoint and how to initiate the retry. Convoy supports two retry strategies
* `default`: retries are done in linear time. It's best to set a reasonable number of attempts if the duration is short.
* `exponential-backoff`: retries events while progressively increasing the time before the next attempt. The default schedule looks like this:
* 10 seconds
* 30 seconds
* 1 minute
* 3 minutes
* 5 minutes
* 10 minutes
* 15 minutes Retry strategies are configured per group
# Price
### Overview
Price represents the cost of an item or [Stock Keeping Unit (SKU)](/v3/api-reference/offers/webhook-events/glossary)webhook-events-glossary#sku). By subscribing to price-based events, as merchants, you can get event-specific information, including the `itemId`, `SKU`, and price list `id`.
The following table details various pricing events along with the example responses:
### Events
| Event Type | Description | Example Response |
| ------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offers:price:created | The event is triggered when a price is created. | `{ "specversion": "v1", "type": "offers:price:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICE", "status": "CREATED", "itemId": 1684471584, "itemSku": "DS SD S", "priceListId": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/price/DS SD S/priceList/100001?type=itemSku" \] } } \] }` |
| offers:price:deleted | The event is triggered when a price is deleted. | `{ "specversion": "v1", "type": "offers:price:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICE", "status": "DELETED", "itemId": 1684471584, "itemSku": "DS SD S", "priceListId": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/price/DS SD S/priceList/100001?type=itemSku" \] } } \] }` |
| offers:price:activated | The event is triggered when a price becomes operational. | `{ "specversion": "v1", "type": "offers:price:activated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICE-ACTIVATION", "status": "ACTIVATED", "itemId": 1684471584, "itemSku": "DS SD S", "priceListId": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/price/DS SD S/priceList/100001?type=itemSku" \] } } \] }` |
| offers:price:deactivated | The event is triggered when a price is no longer valid. | `{ "specversion": "v1", "type": "offers:price:deactivated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICE-ACTIVATION", "status": "DEACTIVATED", "itemId": 1684471584, "itemSku": "DS SD S", "priceListId": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/price/DS SD S/priceList/100001?type=itemSku" \] } } \] }` |
# Price List
### Overview
A price list is a collection of items and their assigned prices. By subscribing to `priceList` events, as merchants, you can get event-specific information, including the price list ID.\
The following table details the various `priceList` events along with the example responses:
### Events
| Event Type | Description | Example Response |
| ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offers:priceList:created | The event is triggered when a price list is created. | `{ "specversion": "v1", "type": "offers:priceList:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICELIST", "status": "CREATED", "id": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:priceList:deleted | The event is triggered when a price list is deleted. | `{ "specversion": "v1", "type": "offers:priceList:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICELIST", "status": "DELETED", "id": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:priceList:updated | The event is triggered when a price list is updated. | `{ "specversion": "v1", "type": "offers:priceList:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PRICELIST", "status": "UPDATED", "itemId": 1684471584, "itemSku": "DS SD S", "priceListId": 100001, "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/price/DS SD S/priceList/100001?type=itemSku" \] } } \] }` |
# Promotion
### Overview
Promotions are discounts on items, carts, or shipping that are automatically applied when the required conditions are met. By subscribing to promotion events, as merchants, you can receive event-specific information, including promotion ID, event name, and event status.
The following table details various promotion events along with the example responses:
### Events
| Event Type | Description | Example Response |
| ------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offers:promo:created | The event is triggered when a promotion is created. | `{ "specversion": "v1", "type": "offers:promo:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PROMOTION", "status": "CREATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:promo:deleted | The event is triggered when a promotion is deleted. | `{ "specversion": "v1", "type": "offers:promo:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PROMOTION", "status": "DELETED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:promo:updated | The event is triggered when a promotion is updated. | `{ "specversion": "v1", "type": "offers:promo:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PROMOTOION", "status": "UPDATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:promo:activated | The event is triggered when a promotion becomes active and is available for use. | `{ "specversion": "v1", "type": "offers:promo:activated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PROMOTION", "status": "ACTIVATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] } ` |
| offers:promo:deactivated | The event is triggered when a promotion is deactivated and is no longer available for use. | `{ "specversion": "v1", "type": "offers:promo:deactivated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "PROMOTION", "status": "DEACTIVATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
# Redemption
### Overview
Redemption refers to instances when coupons or promotions are applied to an order. By subscribing to redemption events, as merchants, you can get event-specific information, including redemption ID, event name, and event status.
The following table details various redemption events along with the example responses:
### Events
| Event Type | Description | Example Response |
| ----------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offers:redemption:promotion:created | The event is triggered when redemption details for a promotion are created. | `{ "specversion": "v1", "type": "offers:redemption:promotion:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "REDEMPTION", "status": "CREATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:redemption:promotion:deleted | The event is triggered when redemption details for a promotion are deleted. | `{ "specversion": "v1", "type": "offers:redemption:promotion:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "REDEMPTION", "status": "DELETED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:redemption:promotion:updated | The event is triggered when redemption details for a promotion are updated. | `{ "specversion": "v1", "type": "offers:redemption:promotion:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "REDEMPTION", "status": "UPDATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:redemption:coupon:created | The event is triggered when redemption details of a coupon are created. | `{ "specversion": "v1", "type": "offers:redemption:coupon:created", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "REDEMPTION", "status": "CREATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:redemption:coupon:updated | The event is triggered when the redemption details of a coupon are updated. | `{ "specversion": "v1", "type": "offers:redemption:coupon:updated", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "REDEMPTION", "status": "UPDATED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
| offers:redemption:coupon:deleted | The event is triggered when the redemption details of a coupon are deleted. | `{ "specversion": "v1", "type": "offers:redemption:coupon:deleted", "tenantid": "63a123070cf218e178efda30", "events": \[ { "id": "0076064a-695e-43ac-b004-17802ed186ac", "time": "2023-06-01T13:29:40.000Z", "source": "offers:business-layer", "subject": null, "data": { "eventName": "REDEMPTION", "status": "DELETED", "id": "642babcd3ebd250008455701", "callbackUrls": \[ "https://stg02.copilot.fabric.inc/api-offers/priceList/100001" \] } } \] }` |
# Ship To
Ship To APIs
**Note:** These are the legacy Ship To APIs. To view fabric's new Shipping APIs, navigate to *Cart API > Shipping* from the left side navigation pane.
# Subscribing Events
### Overview
As a merchant, you can subscribe to one or more Offers events to get asynchronous event notifications without calling the individual REST API endpoints.
### Procedure
To subscribe to Offers events, you must either [raise a support ticket](https://support.fabric.inc/hc/en-us) with the following details or share the details with your customer success manager:
1. Webhook URL or API that you want fabric to send notifications to.
2. Webhook call method(POST, GET) associated with the Webhook URL or API.
3. API key.
4. Stage for which you want to receive notifications when the event takes place in that stage. For example, sandbox or production.
5. Tenant ID, which is the 24-character Copilot account ID.
6. Event types that you want to subscribe to.
# Webhook Events
### Overview
An event is a specific action within a system, such as updating price, generating a coupon code, or deleting a promotion. Through Webhooks, you can get automated, real-time notifications when an event is initiated. You can subscribe to one or more webhook events to receive event-specific information without making individual REST API calls. For example, if you subscribe to a `price update` event, you will be notified whenever a new price becomes active. This enables you to update your Product Description Page (PDP) promptly, ensuring your website reflects the latest prices accurately. Similarly, by subscribing to new promotions event, you are notified whenever a new promotion becomes active, enabling you to display the new promotion on your website as soon as the promotion is available. For using the event-driven notifications, you must [subscribe to the relevant webhook events](/v3/api-reference/offers/webhook-events/subscribing-events).
## fabric Offer Events
You can subscribe to one or more Offers events in each of the following objects to get event-specific information in real-time:
* [Price](https://developer.fabric.inc/v3/reference/offers-webhook-events-price)
* [Promotion](https://developer.fabric.inc/v3/reference/offers-webhook-events-promotion)
* [Coupon](https://developer.fabric.inc/v3/reference/offers-webhook-events-coupon)
* [Price list](https://developer.fabric.inc/v3/reference/offers-webhook-events-price-list)
* [Global exclusion](https://developer.fabric.inc/v3/reference/offers-webhook-events-global-exclusion)
* [Redemption](https://developer.fabric.inc/v3/reference/offers-webhook-events-redemption)
For example, by subscribing to `offers:price:created` event, you can get notified whenever a new price is created for a specific item. If you want more information about an event, you can make an API call to the `callBackUrl` available in the sample response. The following is a sample cURL request to get an event-related information from a specific URL:
```javascript
curl --location 'https://api-stg02.admin.offers.fabric.inc/v3/prices/1000072889?priceListId=100000' \\ Replace this URL with the event-specific callBackUrl
--header 'x-fabric-tenant-id: 64a86ebb0cf29efc89cd2d9d' \
--header 'x-fabric-channel-id: 12' \
--header 'x-fabric-source: copilot' \
--header 'x-fabric-request-id: 73068ccf-d359-4292-bbc9-6b31e865587b' \
--header 'x-fabric-stage: stg02' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJqbXE2bFNUTTZEZTRfcGhveTQ4eVFjb1dLLWFnLWo3RktVbkhaUG5vbmhRIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULm5KQ0tvMzRtNjFUUHZqU1NmeHN4VlB1allEMUdiZENfRjU5NGc0YU05b0UiLCJpc3MiOiJodHRwczovL2NvcGlsb3QubG9naW4tc2J4LmZhYnJpYy5pbmMvb2F1dGgyL2F1c29wYm85c3JPUndIY001Njk2IiwiYXVkIjoiYXBpOi8vc2VydmljZSIsInN1YiI6IjBvYTFqb2s0OGR6YWZLZEZsNjk3IiwiaWF0IjoxNjkzMzc5ODM2LCJleHAiOjE2OTMzODE2MzYsImNpZCI6IjBvYTFqb2s0OGR6YWZLZEZsNjk3Iiwic2NwIjpbInMycyJdLCJhY2NvdW50cyI6IntcImZhYnJpY1wiOntcInJvbGVzXCI6W1wiNWU5YmNhYmItYWFhOC00MTgwLWE3ZjctNzQ0MjQxMzI2MmZkXCIsXCJmODJkOGIyMC1lMjZmLTQxZjYtYWRhNi0xMWI3YWU5YjMxNDFcIixcIjkwYWM0OWExLTdhYTQtNGQ0OS1hMmM3LTE2MGQxY2Y0NWYzOVwiXSxcImlkXCI6XCJmYWJyaWNcIixcIm5hbWVcIjpcImZhYnJpY1wiLFwidGVuYW50SWRcIjpcImZhYnJpY1wifX0iLCJpZGVudGl0eVZlcnNpb24iOiJ2MiJ9.Tcl9I9Z76t0rj_L49cW7h7VzSNbhl7tzqZjQv1CUkDZ1aNw6DgXDIuwp-XsKP4_zTsAJ7CtHMDBt00usRPJYvUAKmi5C6I19rB5bw9t4wrqg-3hqItg_vVEmMTMUq9LryVfuc42NDoA29BvQ6bWfQ43B66e4c5yK77HqRULJegrESB9jXNGbMAXiQtMcv1IBMtK5uMHWfGnffMEvJpsl5lJq9QW0Lfn5PUQo5Gkm7YZMKXNYfneWROwuYqaY6cCykcas2rRVP5sx0pmnBSRYISoBGGe6o4m-k2k07oVxnI_vg4yAcraqxyFw1Qxu7wyBd0nJkWxogm3-tc2UnAmKhw' \
--data ''
```
# Create address
modular-cart post /carts/{cartId}/addresses
Adds a billing address to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete address
modular-cart delete /carts/{cartId}/addresses/{addressId}
Removes the billing address associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Address ID from the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint is used in the path parameter.
# Get address
modular-cart get /carts/{cartId}/addresses/{addressId}
Gets the billing address associated the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Address ID from the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint is used in the path parameter.
# Update address
modular-cart patch /carts/{cartId}/addresses/{addressId}
Updates the billing address associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Address ID from the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint is used in the path parameter.
# Add cart attributes
modular-cart post /carts/{cartId}/actions/add-attributes
Partially updates attributes of your choice in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete cart attributes
modular-cart post /carts/{cartId}/actions/delete-attributes
Partially deletes attributes of your choice associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Merge carts
modular-cart post /carts/{cartId}/actions/merge
This endpoint merges two carts together. Specify one cart in the path parameter and the second cart in the request body.
To learn more about merge cart behaviors, you can check out the [Merge Cart Behaviors](/v3/api-reference/carts-v3/merge-carts-behaviors) page.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Create adjustment
modular-cart post /carts/{cartId}/adjustments
Creates adjustments to the corresponding cart. This is useful when a price needs to be adjusted by a CSR agent.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Remove adjustment
modular-cart delete /carts/{cartId}/adjustments/{adjustmentId}
Removes an adjustment made to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Adjustment ID from the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint is used in the path parameter.
# Update adjustment
modular-cart patch /carts/{cartId}/adjustments/{adjustmentId}
Updates the adjustments made to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Adjustment ID from the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint is used in the path parameter.
# Create an empty cart
modular-cart post /carts
Use this endpoint to create a new cart.
**Default Configurations**: To create a cart with default configurations, send a request with an empty body.
**Provided Configurations**: To create a cart with provided configurations, include the configurations in the request body. To learn more about configuration behaviors, visit the [Configuration Behaviors](/v3/api-reference/carts-v3/configuration-behaviors) page.
# Delete cart
modular-cart delete /carts/{cartId}
Removes the cart corresponding to the provided cart ID.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Get the provided cart
modular-cart get /carts/{cartId}
Retrieves the cart information corresponding to the provided cart ID.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Search for multiple carts
modular-cart post /carts/search
Returns a list of carts based on the search criteria.
# Sequence calling
modular-cart post /carts/{cartId}/sequence
Use this endpoint to execute multiple cart-related operations with a single request. This allows you to perform various actions such as creating a cart, adding items, and checking out in a single API call.
**Note:** The order of operations matters since IDs are carried over from call to call.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Update cart
modular-cart patch /carts/{cartId}
Updates the cart information corresponding to the provided cart ID.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Configuration Behaviors
The Configuration Behaviors page provides an overview of the configuration settings and their associated functionalities.
To ensure your cart functions as intended, you must specify which configurations to activate when making a [Create a cart](/v3/api-reference/carts-v3/carts/carts) request.
When setting a cache expiry, the minimum duration is 1 second and the maximum duration is 7,776,000 seconds, which is 3 months.
| Configuration | Description |
| ------------- | -------------------------------------------------------- |
| WARN | Executes the action, and the state object is updated. |
| REJECT | Rejects the action and a detailed exception is returned. |
| DROP | Drops the action and resource is removed from the cart. |
| NONE | Accepts the action. |
| BLOCK | Blocks the action and returns an exception. |
## Related Topics
* [Create a cart](/v3/api-reference/carts-v3/carts/carts)
# Configuring Adjustment
This feature in Carts API provides you the flexibility to apply adjustments at the cart, item, or fulfillment level. Adjustments are deductible elements that modify the total amount and are non-taxable.
## Prerequisites
The following prerequisites must be completed sequentially to configure an adjustment.
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Create a fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) to add a fulfillment adjustment.
3. [Create an item](/v3/api-reference/carts-v3/items/items) to add an item adjustment.
## Adjustment Initialization
You can apply adjustments at multiple levels, including the cart, individual items, or fulfillment. The adjustment maintains a consistent structure across all levels.
The following code sample provides the structure of an adjustment object:
```json
{
"id": "6964b984-49fd-4754-b979-a260e944320c",
"price": {
"amount": 10
},
"reason": "DelayedOrder",
"attributes": {
"reasonDescription": "Price Adjustment due to delayed shipping"
},
"updatedAt": "2024-06-20T08:09:58.951Z",
"createdAt": "2024-06-20T08:09:58.951Z"
}
```
As multiple adjustments can be applied to a single cart, item, or fulfillment, adjustments are displayed as a collection.
The following code sample provides the structure of an adjustment object in a collection:
```json
"adjustments": {
"total": 10,
"collection": [
{
"id": "6964b984-49fd-4754-b979-a260e944320c",
"price": {
"amount": 10
},
"reason": "DelayedOrder",
"attributes": {
"reasonDescription": "Price Adjustment due to delayed shipping"
},
"updatedAt": "2024-06-20T08:09:58.951Z",
"createdAt": "2024-06-20T08:09:58.951Z"
}
]
}
```
## Examples
### Making adjustments at the cart level
Use the [create cart adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint to make adjustments at the cart level and credit points available for discounts as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/adjustments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"price": {
"amount":10
},
"reason":"Avail 1000 Credit Points"
}'
```
### Using adjustments at the item level
Use the [create item adjustment](/v3/api-reference/carts-v3/item-adjustments/create-item-adjustments) endpoint to make adjustments at the item level and apply the sale price as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/items/806d6671-801d-4554-976d-0d38e525a852/adjustments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"price": {
"amount":"10"
},
"reason":"Item was a sale item 2 days ago",
"attributes": {
"type": "retail"
}
}'
```
# Configuring Fees
The fees feature in Carts API allows you to add, update, or remove additional fees beyond the resource price, such as gifting fees, platform fees, and service fees. These fees can be applied at various levels, including the cart, individual items, or fulfillment, providing flexibility in customizing the total cost structure. Optionally, the fees may be taxable.
## Prerequisites
The following prerequisites must be completed sequentially to configure a fee.
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Create a fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) to apply the fulfillment fee.
3. [Create an item](/v3/api-reference/carts-v3/items/items) to add the item fee.
## Fee Initialization
You can apply fees at multiple levels, including the cart, individual items, or fulfillment. The fee resource maintains a consistent structure across all levels. Taxes on fees is controlled by the `taxable` attribute in the request payload, which defaults to `true`. This means fees are taxed unless specifically set to `false`.
The following code sample provides the structure of a fee object:
```json
{
"id": "188514cb-f36b-4835-a8b3-df75164325d7",
"name": "cart v3 fees",
"price": {
"amount": 10
},
"taxable": true,
"attributes": {
"message": "gifting-fee"
},
"updatedAt": "2024-06-20T07:55:49.021Z",
"createdAt": "2024-06-20T07:55:49.021Z"
}
```
The resource is displayed as a collection of fees for the associated resource as multiple fees can be applied to a single resource.
The following code sample provides the structure of a fee object in a collection:
```json
"fees": {
"total": 10,
"collection": [
{
"id": "188514cb-f36b-4835-a8b3-df75164325d7",
"name": "cart v3 fees",
"price": {
"amount": 10
},
"taxable": true,
"attributes": {
"message": "gifting-fee"
},
"updatedAt": "2024-06-20T07:55:49.021Z",
"createdAt": "2024-06-20T07:55:49.021Z"
}
]
}
```
## Examples
### Adding shipping fees, including shipping fee tax
The following steps outline how a fulfillment fee is configured:
1. [Create fulfillment fee.](/v3/api-reference/carts-v3/fulfillment/create-fulfillments)
```curl
curl --location '{{modular_cart}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fulfillments/65879f42-edfb-46de-bf57-77835dec3d60/fees' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"name": "Shipping fee",
"price": {
"amount": 10
},
"taxable": true,
"attributes": {
"displayMsg": "Shipping Off for orders over $100"
}
}'
```
2. Add tax for the fulfillment fee using the [replace tax date](/v3/api-reference/carts-v3/validations/add-tax) endpoint.
```curl
curl --location --request PUT 'https://dev.cart.fabric.inc/beta/v3/modular/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/tax' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--data '{
"fulfillments": [
{
"id": "65879f42-edfb-46de-bf57-77835dec3d60",
"tax": [
{
"amount": 2,
"attributes": {
"rate": 1
}
}
],
"fees": [
{
"id": "026b9bd1-2e96-4016-93a3-674da01aa29e",
"tax": [
{
"amount": 1,
"attributes": {
"rate": 1
}
}
]
}
]
}
]
}'
```
Tax here includes fulfillment tax and fulfillment the fee tax as provided in the payload.
Response:
```json
"price": {
"total": 343,
"subtotal": 310,
"tax": 3,
"fulfillments": 30,
"discounts": 0,
"fees": 110,
"adjustments": 0
}
```
### Applying a gifting fee to items that are gift-wrapped
Use the [create item fees](/v3/api-reference/carts-v3/item-fees/create-item-fees) endpoint to apply the gifting fees to the items that are gift wrapped.
The following curl example provides how the request is structured when creating an item fee:
```curl
curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/items/806d6671-801d-4554-976d-0d38e525a852/fees' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"name": "Gift wrap",
"price": {
"amount": 10
},
"taxable": false,
"attributes": {
"message": "Happy Birthday John Doe"
}
}'
```
### Adding a platform fee at the cart level
Use the [create cart fees](/v3/api-reference/carts-v3/fees/create-fees) endpoint to add a platform fee at the cart level.
The following curl example provides how the request is structured when creating fee at the cart level:
```curl
curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fees' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"name": "Platform-fee",
"price": {
"amount": 100
},
"taxable": true,
"attributes": {
"reason": "added as an example"
}
}'
```
# Configuring Fulfillment
This feature in Carts API allows you to add, update, or remove fulfillment information in the cart and associate it with individual items. The cart supports multiple fulfillment options.
## Prerequisites
The following prerequisites must be completed sequentially to configure a fulfillment.
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Create a destination address](/v3/api-reference/carts-v3/addresses/create-addresses) if the fulfillment type is `SHIP_TO`.
3. [Create an origin address](/v3/api-reference/carts-v3/addresses/create-addresses) if the fulfillment type is `BOPIS` or `ROPIS`.
## Fulfillment Initialization
After you create a cart with [Create a cart](/v3/api-reference/carts-v3/carts/carts), you will see the fulfillment resource in the cart response.
The following code sample provides the structure of fulfillment object in a cart response:
```json
{
"id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",
"type": "SHIP_TO",
"refId": "6425279f661bf878448465b4",
"originAddress": "{{originAddressId}}",
"destinationAddress": "{{destinationAddressId}}",
"price": {
"amount": 10
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0,
"collection": []
}
}
```
The fulfillment resource can be associated with an item using the `fulfillmentId` by making POST request to the `{cartId}/fulfillments` endpoint.
The following code sample provides how the request is structured in a request payload:
### POST Response
```curl
curl --location '{{cartV3_domain}}/carts/{{cartId}}/items' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data
'{
"sku": "5",
"refId": "19",
"quantity": 10,
"price":
{
"type": "UNIT",
"amount": 100
},
"fulfillment":
{
"id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f", // fulfillmentId
"inventory":
{
"channels":
{"networkCode": "ShipToHome"},
"type": "preOrder"
}
}
}'
```
The cart has a fulfillment object that stores all the fulfillments added to it.
You can check your fulfillment information by making a GET request to `carts/{cartId}/fulfillments/{fulfillmentId}` endpoint.
The following code sample provides the structure of fulfillment object in the response:
```json
{
"fulfillments":
{
"a7f51053-6fbd-42a6-8fbc-303bfc16c13f":{
"id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",
"type": "SHIP_TO",
"refId": "6425279f661bf878448465b4",
"attributes": {},
"originAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
"destinationAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
"price": {
"amount": 10
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0,
"collection": []
}
},
"b326819-6fbd-42a6-8fbc-303bfc16e222": {
"id": "b326819-6fbd-42a6-8fbc-303bfc16e222",
"type": "SHIP_TO",
"refId": "632479f661bf87844846534",
"attributes": {},
"originAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
"destinationAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
"price": {
"amount": 10
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0,
"collection": []
}
}
}
}
```
## Examples
### Adding a fulfillment with a single cost to multiple items
1. [Create a fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) curl.
```curl
curl --location '{{modular_cart_domain}}/carts/07618f2d-8559-479a-80ed-5ed7259cbd25/fulfillments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"type": "SHIP_TO",
"refId": "6622d50d2eee4e4e124c7467",
"destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
"price": {
"amount": 10.0
}
}'
```
**Response**
```json
{
"id": "e4d68b36-8902-4427-a244-9eb65290855c",
"type": "SHIP_TO",
"refId": "6622d50d2eee4e4e124c7467",
"destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
"price": {
"amount": 10.0
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0,
"collection": []
}
}
```
2. Create multiple items with same fulfillment using the [add items](/v3/api-reference/carts-v3/orchestrator/line-items/add-items) endpoint.
```curl
curl --location '{{orchestrator_domain}}/orchestrator/carts/07618f2d-8559-479a-80ed-5ed7259cbd25/items' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'x-fabric-request-id: 1' \
--header 'x-fabric-channel-id: 12' \
--header 'Authorization: {authToken}' \
--header 'customer-id: 1234' \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"quantity": 4,
"itemId": "41",
"sku": "SKU2",
"priceListId": "100000",
"price": {
"type": "UNIT",
"amount": 10
},
"fulfillment": {
"id": "e4d68b36-8902-4427-a244-9eb65290855c",
"inventory": {
"channels": {
"type": "WEB_PICKUP",
"locationNumber": "15",
"channelId": "12"
},
"type": "availableToPurchase"
}
}
},
{
"quantity": 5,
"itemId": "44",
"sku": "SKU3",
"priceListId": "100000",
"price": {
"type": "UNIT",
"amount": 100
},
"fulfillment": {
"id": "e4d68b36-8902-4427-a244-9eb65290855c",
"inventory": {
"channels": {
"type": "WEB_SHIP",
"networkCode": "ShipToHome",
"channelId": "12"
},
"type": "availablePreorder"
}
}
}
]
}'
```
### Adding a fulfillment with a custom cost to an item
1. [Create a fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) curl.
```curl
curl --location '{{modular_cart_domain}}/carts/07618f2d-8559-479a-80ed-5ed7259cbd25/fulfillments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"type": "SHIP_TO",
"refId": "6622d50d2eee4e4e124c7467",
"destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
"price": {
"amount": 10.0
}
}'
```
Response:
```json
{
"id": "e4d68b36-8902-4427-a244-9eb65290855c",
"type": "SHIP_TO",
"refId": "6622d50d2eee4e4e124c7467",
"destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
"price": {
"amount": 10.0
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0,
"collection": []
}
}
```
2. Add a custom cost to the item using the [add item](/v3/api-reference/carts-v3/items/items) endpoint.
The example shows adding an additional \$5.00 as the fulfillment cost for the item.
```curl
curl --location 'https:{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/items' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--data '{
"sku": "5",
"refId": "1",
"quantity": 1,
"priceListId": "100000",
"price": {
"type": "UNIT",
"amount": 100
},
"fulfillment": {
"id": "e4d68b36-8902-4427-a244-9eb65290855c",
"inventory": {
"channels": {
"networkCode": "ShipToHome"
},
"type": "backOrder"
},
"price": {
"amount": 5
}
}
}'
```
`price.fulfillments` accepts both the fulfillment cost and any additional fulfillment amount added to the item.
Response:
```json
{
"lineItems": {
"total": 100,
"collection": [
{
"id": "806d6671-801d-4554-976d-0d38e525a852",
"sku": "5",
"refId": "1",
"quantity": 1,
"priceListId": "100000",
"position": 1,
"price": {
"unit": 100,
"amount": 100
},
"fees": {
"total": 0,
"collection": []
},
"promotions": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"fulfillment": {
"id": "cda19e15-ab04-419e-8fc1-61fa7874beb0",
"price": {
"amount": 5
},
"inventory": {
"type": "backOrder",
"channels": {
"networkCode": "ShipToHome"
}
},
"tax": {
"total": 0,
"collection": []
}
},
"attributes": {},
"tax": {
"total": 0,
"collection": []
},
"updatedAt": "2024-08-31T15:17:20.584Z",
"createdAt": "2024-08-31T15:17:20.584Z"
}
]
},
"id": "7d403833-8e0c-43f5-aded-72d6a2eaf062",
"attributes": {
"key": "value"
},
"configuration": {
"order": {
"validate": {
"paymentsRemaining": "BLOCK",
"taxRemaining": "BLOCK",
"invalidItem": "BLOCK",
"itemOutOfStock": "BLOCK"
}
},
"product": {
"cacheExpiry": 1,
"behaviors": {
"add": "NONE",
"update": "NONE",
"get": "NONE",
"cacheExpiry": "NONE"
},
"maxQuantity": {
"behaviors": {
"add": "NONE",
"update": "NONE",
"get": "NONE"
}
}
},
"inventory": {
"cacheExpiry": 1,
"behaviors": {
"add": "NONE",
"update": "NONE",
"get": "NONE",
"cacheExpiry": "NONE"
},
"check": "SKU"
},
"tax": {
"cacheExpiry": 5,
"behaviors": {
"cacheExpiry": "NONE"
}
},
"promotions": {
"cacheExpiry": 5,
"behaviors": {
"cacheExpiry": "WARN"
}
},
"maxQuantity": {
"limit": 10,
"behaviors": {
"add": "NONE",
"update": "NONE",
"get": "NONE"
}
}
},
"customerContext": {},
"status": "ACTIVE",
"state": [
{
"resource": "CART",
"resourceId": "",
"key": "MISSING_PAYMENT_DETAILS",
"description": "No payment details have been added to this Cart"
},
{
"resource": "CART",
"resourceId": "",
"key": "MISSING_TAX",
"description": "No tax has been added to this Cart"
}
],
"price": {
"total": 115,
"subtotal": 100,
"tax": 0,
"fulfillments": 15,
"discounts": 0,
"fees": 0,
"adjustments": 0
},
"promotions": {
"total": 0,
"collection": null
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"addresses": {
"702009a6-fc56-4df7-a1b4-c73cf916d9fc": {
"id": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
"name": {
"first": "Pat",
"last": "E"
},
"email": "samiksha@gmail.com",
"phone": {
"number": "9050123102",
"type": "MOBILE"
},
"addressLine1": "Princeton",
"addressLine2": "Street 2",
"addressLine3": "Stars Hollow",
"city": "Phillidelphia",
"region": "Pennsylvania",
"country": "US",
"postalCode": "1-21-12",
"updatedAt": "2024-08-31T15:17:17.312Z",
"createdAt": "2024-08-31T15:17:17.312Z"
}
},
"summary": {
"totalItems": 1,
"totalUniqueItems": 1
},
"fulfillments": {
"cda19e15-ab04-419e-8fc1-61fa7874beb0": {
"id": "cda19e15-ab04-419e-8fc1-61fa7874beb0",
"type": "SHIP_TO",
"refId": "1",
"attributes": {
"test1": {},
"channelId": [
"12"
]
},
"originAddress": "",
"destinationAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
"price": {
"amount": 10
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0,
"collection": []
}
}
},
"coupons": [],
"appliedCoupons": [],
"notAppliedCoupons": [],
"validations": {
"promotions": null,
"lineItems": [],
"product": null,
"tax": null
},
"payments": {
"authorized": 0,
"collection": []
},
"channelId": "13",
"currency": "USD",
"updatedAt": "2024-08-31T15:17:18.982Z",
"createdAt": "2024-08-31T15:17:07.865Z"
}
```
### Adding a fulfillment with the type `BOPIS` or `ROPIS` requires a `locationId`
Use the [add fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint to add a location when creating a fulfillment as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fulfillments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"type": "BOPIS",
"refId": "1",
"originAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
"locationId": "1",
"attributes": {
"channelId": [
"12"
],
"test1": 123
},
"price": {
"amount": 10
},
"pickupPerson": {
"primary": {
"name": {
"firstName": "BOB"
},
"email": "123",
"phone": {
"type": "MOBILE",
"number": "1231231234"
},
"addressId": "702009a6-fc56-4df7-a1b4-c73cf916d9fc"
}
}
}'
```
### Adding the same destination address to different fulfillments for multiple items
Use the [add fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint to create multiple fulfillment with the same addresses as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fulfillments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--data '{
"type": "BOPIS",
"refId": "1",
"originAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
"destinationAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
"locationId": "1",
"attributes": {
"channelId": [
"12"
],
"test1": 123
},
"price": {
"amount": 10
},
"pickupPerson": {
"primary": {
"name": {
"firstName": "BOB"
},
"email": "123",
"phone": {
"type": "MOBILE",
"number": "1231231234"
},
"addressId": "702009a6-fc56-4df7-a1b4-c73cf916d9fc"
}
}
}'
```
# Configuring Order Drafts
This feature in Carts API enables the cart to be transformed into a schema ready for submission to the **Order Management System (OMS)**, representing the **order draft** stage before the order is officially created.
At this stage, the cart contains all necessary data, including items, fulfillment details, fees, taxes, and payment information. This transformation ensures that the cart aligns with OMS requirements, allowing for final review and confirmation of the order before proceeding to fulfillment.
## Prerequisites
There are two types prerequisites, depending on your cart configurations.
One of the following prerequisites must be completed sequentially to configure an order draft.
```json
"configuration": {
"order": {
"validate": {
"paymentsRemaining": "BLOCK",
"taxRemaining": "BLOCK",
"invalidItem": "BLOCK",
"itemOutOfStock": "BLOCK"
}
}
}
```
**Prerequisites**
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Add item](/v3/api-reference/carts-v3/items/items) to the cart.
3. [Add taxes](/v3/api-reference/carts-v3/validations/add-tax) to the resources in the cart.
4. [Add payments to the cart](/v3/api-reference/carts-v3/payments/create-payments), ensuring they match the cart total.
5. Ensure that the items added to the cart are valid and in stock.
```json
"configuration": {
"order": {
"validate": {
"paymentsRemaining": "BLOCK",
"taxRemaining": "BLOCK",
"invalidItem": "BLOCK",
"itemOutOfStock": "BLOCK"
}
}
}
```
**Prerequisites**
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Add item](/v3/api-reference/carts-v3/items/items) to the cart.
## Order Drafts Initialization
The order draft captures a snapshot of the cart, which can then be converted into an order. The ability to create an order draft is controlled by [cart configurations](/v3/api-reference/carts-v3/configuration-behaviors). Cart offers users the flexibility to prevent order draft creation if:
* Payments haven't been added to the cart.
* Taxes are missing for resources in the cart.
* Items are invalid.
* Items are out of stock.
The following code sample provides the structure of order draft settings that block creation in the response:
### Cart configuration
```json
"configuration": {
"order": {
"validate": {
"paymentsRemaining": "BLOCK",
"taxRemaining": "BLOCK",
"invalidItem": "BLOCK",
"itemOutOfStock": "BLOCK"
}
}
}
```
## Examples
### Creating an order draft to send to an Order Management System (OMS)
Use the [create an order draft](/v3/api-reference/carts-v3/orchestrator/carts/order-drafts) endpoint to create an order draft and send it to OMS as in the following example:
```curl
curl --location '{{orchestrator_domain}}/carts/{{cartId}}/order-draft' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'x-fabric-request-id: {{requestId}}' \
--header 'x-fabric-channel-id: {{channelId}}' \
--header 'Authorization: {authToken}' \
--header 'Content-Type: application/json'
--data '{
"orderNumber": "W0013"
}'
```
**Response**
```json
{
"order": {
"number": "W0013",
"currency": "USD",
"createdAt": "2024-06-24T09:22:40.979+00:00",
"attributes": {}
},
"cartId": "39ea2154-7160-4feb-ae42-1506223efd95",
"attributes": {
"name": "cart test",
"description": "This cart is created by cart v2 service"
},
"customerContext": {
"id": "C01",
"segments": [
{
"name": "membership",
"value": [
"premium"
]
},
{
"name": "customer-type",
"value": [
"high"
]
}
],
"attributes": {
"returnRate": "high",
"city": "london",
"type": "regular"
}
},
"status": "ACTIVE",
"state": [
{
"resource": "VALIDATION",
"resourceId": "",
"key": "PROMOTION_REFRESH",
"description": "Promotions require a refresh in the Cart"
},
{
"resource": "CART",
"resourceId": "HAPPY10",
"key": "COUPON_NOT_APPLIED",
"description": "Coupon HAPPY10 has no associated promotion"
}
],
"price": {
"total": 1180.19,
"subtotal": 1043,
"tax": 97.19,
"fulfillments": 40,
"discounts": 0,
"fees": 25,
"adjustments": 12
},
"promotions": {
"total": 0,
"collection": [
{
"id": "6626c179627d450008a5b202",
"title": "SXP Cart Promotion Fixed Price",
"type": "QUANTITY",
"value": 10,
"attributes": {}
},
{
"id": "64959a4b2341cd00080ca746",
"title": "happy10 coupon",
"code": "HAPPY10",
"type": "PRODUCT",
"value": 103,
"attributes": {}
},
{
"id": "662a7a5c65c3c7000cff7c4a",
"title": "SXP Cart Promotion Item Free",
"type": "BUYGET",
"value": 3.9,
"attributes": {}
},
{
"id": "6626e327fc29c3000858c6e6",
"title": "SXP Cart Promotion Percentage Off",
"type": "QUANTITY",
"value": 515,
"attributes": {}
}
]
},
"fees": {
"total": 15,
"collection": [
{
"id": "9db3ed22-9a71-47c7-844e-bd42e28319c2",
"name": "cart v3 fees",
"price": {
"amount": 15
},
"taxable": true,
"attributes": {
"message": "gifting-fee"
},
"tax": {
"total": 1.33,
"collection": [
{
"amount": 0.6,
"attributes": {
"taxRate": 0.04,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "STATE",
"jurisdictionId": "24354"
}
}
},
{
"amount": 0.67,
"attributes": {
"taxRate": 0.045,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "CITY",
"jurisdictionId": "25353"
}
}
},
{
"amount": 0.06,
"attributes": {
"taxRate": 0.00375,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
"jurisdictionType": "DISTRICT",
"jurisdictionId": "79774"
}
}
}
]
},
"updatedAt": "2024-06-24T09:07:50.155Z",
"createdAt": "2024-06-24T09:07:50.155Z"
}
]
},
"adjustments": {
"total": 7,
"collection": [
{
"id": "c18aa476-97a7-4f31-a2ae-528adb3d6e84",
"price": {
"amount": 7
},
"reason": "DelayedOrder",
"attributes": {
"reasonDescription": "Price Adjustment due to delayed shipping"
},
"updatedAt": "2024-06-24T09:07:51.960Z",
"createdAt": "2024-06-24T09:07:51.960Z"
}
]
},
"addresses": {
"476e673c-10c1-4bd6-b83d-26d403b5a735": {
"id": "476e673c-10c1-4bd6-b83d-26d403b5a735",
"name": {
"first": "Jane",
"last": "Doe"
},
"email": "jane.doe@gmail.com",
"phone": {
"number": "9050123102",
"type": "MOBILE"
},
"addressLine1": "888 Broadway",
"addressLine2": "Street 2",
"addressLine3": "Stars Hollow",
"city": "New York",
"region": "NY",
"country": "US",
"postalCode": "10003",
"updatedAt": "2024-06-24T09:07:41.463Z",
"createdAt": "2024-06-24T09:07:41.463Z"
},
"9f615749-35ef-43e7-adfc-3369eb3b05e8": {
"id": "9f615749-35ef-43e7-adfc-3369eb3b05e8",
"name": {
"first": "Joe",
"last": "Cooper"
},
"email": "joe.cooper@mail.com",
"phone": {
"number": "+1-5807769338",
"type": "MOBILE"
},
"addressLine1": "92 Landon",
"addressLine2": "Street 1",
"addressLine3": "5th Avenue",
"city": "New York",
"region": "NY",
"country": "US",
"postalCode": "10006",
"updatedAt": "2024-06-24T09:07:43.138Z",
"createdAt": "2024-06-24T09:07:43.138Z"
}
},
"lineItems": {
"total": 1035,
"collection": [
{
"id": "75c41689-7bc5-4775-8d72-c7821d38ed9c",
"sku": "SKU2",
"refId": "41",
"quantity": 2,
"priceListId": "100000",
"position": 1,
"price": {
"unit": 500,
"amount": 1000
},
"fees": {
"total": 10,
"collection": [
{
"id": "e3a734c6-d496-43e2-8912-881b44d5f083",
"name": "giftingFee",
"price": {
"amount": 10
},
"taxable": true,
"attributes": {
"message": "regular"
},
"tax": {
"total": 0.89,
"collection": [
{
"amount": 0.4,
"attributes": {
"taxRate": 0.04,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "STATE",
"jurisdictionId": "24354"
}
}
},
{
"amount": 0.45,
"attributes": {
"taxRate": 0.045,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "CITY",
"jurisdictionId": "25353"
}
}
},
{
"amount": 0.04,
"attributes": {
"taxRate": 0.00375,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
"jurisdictionType": "DISTRICT",
"jurisdictionId": "79774"
}
}
}
]
},
"updatedAt": "2024-06-24T09:07:53.712Z",
"createdAt": "2024-06-24T09:07:53.712Z"
}
]
},
"adjustments": {
"total": 5,
"collection": [
{
"id": "b36d4bf0-3e10-40fb-b629-7f7760bbadcc",
"price": {
"amount": 5
},
"reason": "Item was a sale item 2 days ago",
"attributes": {
"type": "retail"
},
"updatedAt": "2024-06-24T09:07:55.423Z",
"createdAt": "2024-06-24T09:07:55.423Z"
}
]
},
"fulfillment": {
"id": "e8d9d243-80cf-48a3-bf3d-765b55c2bca9",
"inventory": {
"type": "availableToPurchase",
"channels": {
"type": "WEB_PICKUP",
"locationNumber": "15",
"channelId": "12"
}
}
},
"attributes": {},
"tax": {
"total": 88.75,
"collection": [
{
"amount": 40,
"attributes": {
"taxRate": 0.04,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "STATE",
"jurisdictionId": "24354"
}
}
},
{
"amount": 45,
"attributes": {
"taxRate": 0.045,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "CITY",
"jurisdictionId": "25353"
}
}
},
{
"amount": 3.75,
"attributes": {
"taxRate": 0.00375,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
"jurisdictionType": "DISTRICT",
"jurisdictionId": "79774"
}
}
}
]
},
"updatedAt": "2024-06-24T09:07:53.712Z",
"createdAt": "2024-06-24T09:07:48.783Z"
},
{
"id": "9a45a494-0cc5-49aa-b339-88e4659ede8b",
"sku": "SKU3",
"refId": "44",
"quantity": 3,
"priceListId": "100000",
"position": 2,
"price": {
"unit": 10,
"amount": 30
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"fulfillment": {
"id": "94b538bb-713f-464d-aa2e-d23ae6fd3115",
"inventory": {
"type": "availablePreorder",
"channels": {
"networkCode": "ShipToHome",
"type": "WEB_SHIP",
"channelId": "12"
}
}
},
"attributes": {},
"tax": {
"total": 2.66,
"collection": [
{
"amount": 1.2,
"attributes": {
"taxRate": 0.04,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "STATE",
"jurisdictionId": "24354"
}
}
},
{
"amount": 1.35,
"attributes": {
"taxRate": 0.045,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "CITY",
"jurisdictionId": "25353"
}
}
},
{
"amount": 0.11,
"attributes": {
"taxRate": 0.00375,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
"jurisdictionType": "DISTRICT",
"jurisdictionId": "79774"
}
}
}
]
},
"updatedAt": "2024-06-24T09:07:48.783Z",
"createdAt": "2024-06-24T09:07:48.783Z"
}
]
},
"summary": {
"totalItems": 5,
"totalUniqueItems": 2
},
"fulfillments": {
"e8d9d243-80cf-48a3-bf3d-765b55c2bca9": {
"type": "SHIP_TO",
"refId": "6622d50d2eee4e4e124c7467",
"attributes": {
"dropOffMethod": false,
"WEB_CARRIER_MODE": "2DAY",
"proOrderShipDays": 2,
"shipmentInstructions": "Ring doorbell for 2nd Floor",
"radialShippingID": "ANY_2 DAY",
"promisedShipDate": "2023-02-10T18:31:31.784Z",
"taxCode": "FR1000",
"WEB_CARRIER_CODE": "ANY",
"storePickupEnabled": false
},
"originAddress": "",
"destinationAddress": "476e673c-10c1-4bd6-b83d-26d403b5a735",
"price": {
"amount": 10
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 0.89,
"collection": [
{
"amount": 0.4,
"attributes": {
"taxRate": 0.04,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "STATE",
"jurisdictionId": "24354"
}
}
},
{
"amount": 0.45,
"attributes": {
"taxRate": 0.045,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "CITY",
"jurisdictionId": "25353"
}
}
},
{
"amount": 0.04,
"attributes": {
"taxRate": 0.00375,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
"jurisdictionType": "DISTRICT",
"jurisdictionId": "79774"
}
}
}
]
}
},
"94b538bb-713f-464d-aa2e-d23ae6fd3115": {
"type": "BOPIS",
"refId": "64b985ef9e16365c4d2b0083",
"attributes": {
"warehouseId": "6126819ec326fe0009f473ba",
"isPickup": true,
"taxCode": "FR1000"
},
"originAddress": "9f615749-35ef-43e7-adfc-3369eb3b05e8",
"destinationAddress": "476e673c-10c1-4bd6-b83d-26d403b5a735",
"locationId": "15",
"pickupPerson": {
"primary": {
"name": {
"first": "Jay",
"last": "Cooper"
},
"email": "jay.cooper@gmail.com",
"phone": {
"number": "+1-1153202801",
"type": "MOBILE"
}
}
},
"price": {
"amount": 30
},
"fees": {
"total": 0,
"collection": []
},
"adjustments": {
"total": 0,
"collection": []
},
"tax": {
"total": 2.67,
"collection": [
{
"amount": 1.2,
"attributes": {
"taxRate": 0.04,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "STATE",
"jurisdictionId": "24354"
}
}
},
{
"amount": 1.35,
"attributes": {
"taxRate": 0.045,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "NEW YORK",
"jurisdictionType": "CITY",
"jurisdictionId": "25353"
}
}
},
{
"amount": 0.12,
"attributes": {
"taxRate": 0.00375,
"taxType": "SALES",
"taxJurisdiction": {
"jurisdictionValue": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
"jurisdictionType": "DISTRICT",
"jurisdictionId": "79774"
}
}
}
]
}
}
},
"coupons": [
{
"code": "HAPPY10",
"updatedAt": "2024-06-24T09:07:57.295Z"
}
],
"appliedCoupons": [
{
"code": "HAPPY10",
"updatedAt": "2024-06-24T09:07:57.295Z"
}
],
"notAppliedCoupons": [],
"payments": {
"authorized": 1180.19,
"collection": [
{
"id": "43eaf31a-2ef6-403a-ace7-0cca0dee9d97",
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "AUTHORIZED",
"authorization": {
"amount": 1180.19,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "123"
}
},
"billToAddress": "476e673c-10c1-4bd6-b83d-26d403b5a735",
"cardDetails": {},
"attributes": {}
}
]
},
"channelId": "12",
"updatedAt": "2024-06-24T09:22:40.907Z",
"createdAt": "2024-06-24T09:07:37.140Z",
"errors": []
}
```
# Configuring Payment
This feature in Carts API allows users to add, update, and delete payment details. The cart maintains the state of each payment—pending, authorized, captured, and failed—as provided by the user, but it doesn't store tokens, which are expected from the System Integrator (SI).
## Prerequisites
The following prerequisites must be completed sequentially to configure a payment.
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Add an item](/v3/api-reference/carts-v3/items/items) to the cart.
## Payments Initialization
The cart displays authorized amounts and allows updates or removals of payments. Payments can be purged or held when the cart changes such as, price changes. The cart also verifies the authorized payment amount against the cart total.
The following code sample provides an example of the structure of payment information and status in the response:
```json
{
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "PENDING",
"authorization": {
"amount": 520.0,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "{{payment_token}}"
}
},
"billToAddress": "{{addressId}}",
"cardDetails": null,
"attributes":{
"orderSource": "ecommerce",
"expirationDate": "0224",
"requestedDate": "2022-01-27T16:15:58-05:00",
"paymentDate": "2022-01-27T16:15:58-05:00",
"billToId": "213321"
}
}
```
As the cart can contain multiple payments, they are shown as a collection. The authorized amount is the sum of all payments with the **AUTHORIZED** state added to the cart as in the following example:
```json
"payments": {
"authorized": 0,
"collection": [
{
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "PENDING",
"authorization": {
"amount": 520.0,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "{{payment_token}}"
}
},
"billToAddress": "{{addressId}}",
"cardDetails": null,
"attributes":{
"orderSource": "ecommerce",
"expirationDate": "0224",
"requestedDate": "2022-01-27T16:15:58-05:00",
"paymentDate": "2022-01-27T16:15:58-05:00",
"billToId": "213321"
}
}
]
}
```
## Examples
### Adding payments with the `CAPTURED` status to the cart
Use the [create a payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint to add a `CAPTURED` payment method to the cart as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/ba0e93f5-e47f-4b0d-bac8-6233b67ef65f/payments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Authorization: {authToken}' \
--data '{
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "CAPTURED",
"authorization": {
"amount": 500.0,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "{{payment_token}}"
}
},
"billToAddress": "46622c9c-604c-4f8c-8bcf-2a393a572839",
"cardDetails": null,
"attributes": {
"orderSource": "ecommerce",
"expirationDate": "0224",
"requestedDate": "2022-01-27T16:15:58-05:00",
"paymentDate": "2022-01-27T16:15:58-05:00",
"billToId": "213321"
}
}
'
```
A successful response to `carts/{cartId}/payments` provides a payments object as the following example:
```json
"payments": {
"authorized": 0,
"collection": [
{
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "CAPTURED",
"authorization": {
"amount": 500.0,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "{{payment_token}}"
}
}
},
"billToAddress": "46622c9c-604c-4f8c-8bcf-2a393a572839",
"cardDetails": null,
"attributes":{
"orderSource": "ecommerce",
"expirationDate": "0224",
"requestedDate": "2022-01-27T16:15:58-05:00",
"paymentDate": "2022-01-27T16:15:58-05:00",
"billToId": "213321"
}
]
}
```
### Adding payments with the `AUTHORIZED` status to the cart
Use the [create a payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint to add `AUHTORIZED` payments to the cart as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/ba0e93f5-e47f-4b0d-bac8-6233b67ef65f/payments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Authorization: {authToken}' \
--data '{
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "AUTHORIZED",
"authorization": {
"amount": 500.0,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "{{payment_token}}"
}
},
"billToAddress": "46622c9c-604c-4f8c-8bcf-2a393a572839",
"cardDetails": null,
"attributes": {
"orderSource": "ecommerce",
"expirationDate": "0224",
"requestedDate": "2022-01-27T16:15:58-05:00",
"paymentDate": "2022-01-27T16:15:58-05:00",
"billToId": "213321"
}
}
'
```
A successful response to `carts/{cartId}/payments` provides a payments object as in the following example:
```json
"payments": {
"authorized": 500.0,
"collection": [
{
"provider": "fabricmock",
"processor": "fabricmock",
"method": "CREDIT_CARD",
"methodType": "VISA",
"state": "AUTHORIZED",
"authorization": {
"amount": 500.0,
"expiry": "",
"verifier": {
"type": "PAYMENT_TOKEN",
"key": "{{payment_token}}"
}
}
},
"billToAddress": "46622c9c-604c-4f8c-8bcf-2a393a572839",
"cardDetails": null,
"attributes":{
"orderSource": "ecommerce",
"expirationDate": "0224",
"requestedDate": "2022-01-27T16:15:58-05:00",
"paymentDate": "2022-01-27T16:15:58-05:00",
"billToId": "213321"
}
]
}
```
# Configuring Search Cart
This feature in Carts API allows the user to search the cart by the following parameters:
* Cart Status
* Order Number
* Customer Information
* Promotion Codes
* Created/Updated Date Range
* Channel ID
## Prerequisites
* A cart that needs to be searched is created with the required parameters using the [create a cart](/v3/api-reference/carts-v3/carts/carts) endpoint.
## Search Cart Initialization
The search endpoint returns a paginated response, displaying the first 10 search results by default. The `total` field in the response indicates the number of results found for the search query, capped at 10,000 results.
For queries that exceed this `limit`, use an `offset`. Querying many carts through this endpoint isn't recommended, as it's intended for basic use cases to retrieve a limited number of carts rather than for analytics purposes.
The following code sample provides the structure of `limit`, `offset`, and `total` in the response when searching for a cart:
```json
{
"query": {
"limit": 20,
"offset": 0,
"total": 3
},
"data": [
{
...
}
]
}
```
## Examples
### Retrieving a cart with an order number
Use the [search for multiple carts](/v3/api-reference/carts-v3/carts/search) endpoint and include the order number in the request body as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/search' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
"offset": 0,
"limit": 20,
"filter": {
"orderNumber": "O1232",
"updatedAt": {
"start": "2024-03-27T06:06:53.709Z",
"end": "2024-06-29T06:06:53.709Z"
}
}
}'
```
### Retrieving a cart with the date range and the `customerId`
Use the [search for multiple carts](/v3/api-reference/carts-v3/carts/search) endpoint and include the date range and the `customerId` in the request body as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/search' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
"offset": 0,
"limit": 20,
"filter": {
"customer": {
"id": "testCustomerId",
"sessionId": "testSessionId"
},
"createdAt": {
"start": "2024-03-27T06:06:53.709Z",
"end": "2024-06-29T06:06:53.709Z"
}
}
}'
```
### Retrieving a cart with the `customerId` and `promotionTitles`
Use the [search for multiple carts](/v3/api-reference/carts-v3/carts/search) endpoint and include `customerId` and promotionTitles\` in the request body as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/search' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
"offset": 0,
"limit": 20,
"filter": {
"promotionTitles": [
"FREE_SHIPPING"
],
"customer": {
"id": "testCustomerId",
"sessionId": "testSessionId"
}
}
}'
```
# Configuring Split Line Items
Splitting line items allows the user to split a single line item into multiple line items based on quantity.
## Prerequisites
The following prerequisites must be completed sequentially to configure splitting line items.
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Add an item to the cart](/v3/api-reference/carts-v3/items/items) that needs to be split.
The sum of the quantities of the split items must not exceed the total quantity of the line item.
## Split Line Items Initialization
All information from the original item is copied to the split items except for the item ID, quantity, `createdAt`, and `updatedAt` timestamps. Adjustments, fees, and fulfillment can be copied to split items based on configuration. The default setting is `NONE`, meaning these elements aren't copied to split items unless specified.
The following code sample provides an example for split line items request payload:
```json
{
"quantities": [2,1],
"adjustmentsBehaviour": "COPY",
"feesBehaviour": "COPY",
"fulfillmentBehaviour": "COPY"
}
```
The `quantities` array allows users to specify the number and quantity of split items. The total number of split items is `quantities.size + 1`.\
In this example, a line item with `6` units and `quantities` set to `[2, 1]` splits into `3` items with `quantities [2, 1, 3]`, where the last quantity represents the remainder. With `adjustmentsBehaviour`, `feesBehaviour`, and `fulfillmentBehaviour` set to `COPY`, adjustments, fees, and fulfillment details from the original item are copied to each split item.
The quantities array lets users specify the number and quantity of split items. The total number of split items will be `quantities.size` plus 1.
For example, if a line item has 6 units and quantities is `[2, 1]`, it will be split into 3 items with quantities `[2, 1, 3]`, where the last quantity is the remainder.
The following code sample provides an example for split line items request payload with the `quantities`:
### Split line items request payload
```json
{
"quantities": [2,1],
"adjustmentsBehaviour": "COPY",
"feesBehaviour": "COPY",
"fulfillmentBehaviour": "COPY"
}
```
## Examples
### The item is available in limited quantities at multiple warehouses
Use the [split line items](/v3/api-reference/carts-v3/item-actions/split) endpoint to split and ship items from different locations as in the following example:
In this example, 4 units are available in Warehouse A, and the remaining units are in Warehouse B.
```curl
curl --location '{{modular_cart_domain}}/carts/9877b7ab-092d-4d67-ad42-b070ac778df8/items/806d6671-801d-4554-976d-0d38e525a852/actions/split' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--data '{
"quantities": [4,5],
"adjustmentsBehaviour": "COPY",
"feesBehaviour": "COPY",
"fulfillmentBehaviour": "COPY"
}'
```
### Sending individual items in the order to different addresses as gifts
Use the [split line items](/v3/api-reference/carts-v3/item-actions/split) endpoint to split items in the cart and send them to different addresses as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/9877b7ab-092d-4d67-ad42-b070ac778df8/items/806d6671-801d-4554-976d-0d38e525a852/actions/split' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--data '{
"quantities": [4,5],
"adjustmentsBehaviour": "COPY",
"feesBehaviour": "COPY",
"fulfillmentBehaviour": "COPY"
}'
```
### Splitting items for promotional bundles or discounts
Use the [split line items](/v3/api-reference/carts-v3/item-actions/split) endpoint to split the items in the cart and item prices will adjust appropriately as in the following example:
```curl
curl --location '{{modular_cart_domain}}/carts/9877b7ab-092d-4d67-ad42-b070ac778df8/items/806d6671-801d-4554-976d-0d38e525a852/actions/split' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--data '{
"quantities": [4,5],
"adjustmentsBehaviour": "COPY",
"feesBehaviour": "COPY",
"fulfillmentBehaviour": "COPY"
}'
```
# Configuring Taxes
This feature in Carts API allows users to levy taxes on resources such as items, fulfillment, and fees. Fees are optionally taxable.
### Prerequisites
The following prerequisites must be completed sequentially to configure a fulfillment.
1. [Create a cart](/v3/api-reference/carts-v3/carts/carts).
2. [Create a fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) to add fulfillment taxes.
3. [Create an item](/v3/api-reference/carts-v3/items/items) to add item taxes.
4. Create either [item](/v3/api-reference/carts-v3/item-fees/create-item-fees), [fulfillment](/v3/api-reference/carts-v3/fulfillment-fees/add-fulfillment), or [cart fees](/v3/api-reference/carts-v3/fees/create-fees) to add fee taxes.
### Tax Initialization
You can add taxes on the cart, cart fees, cart fulfillment, items, item fees, item fulfillment, and fulfillment fees through a single request. To ensure that fees are subject to tax, the fees should be marked as taxable.
You can apply taxes at multiple levels, including individual items, fulfillment, or fees. The tax resource maintains a consistent structure across all levels.
The following code sample provides an example of tax object structure in request payload:
### Tax resource
```json
{
"amount": 4.0,
"attributes": {
"rate": 5,
"message": "5% tax"
}
}
```
For accurate tax calculation, address information is required. While items, fulfillment, and their fees already have associated addresses from the fulfillment information, the cart fee requires a separate field for the address to be provided.
The following code sample provides an example tax object structure in a request payload with the `destinationAddress` and `originAddress`:
### Tax fee resource with addresses
```json
{
"amount": 4.0,
"attributes": {
"rate": 5,
"message": "5% tax"
},
"taxDetails":{
"destinationAddress": "{{destinationAddressId}}",
"originAddress": "{{originAddressId}}"
}
}
```
## Examples
### Applying sales taxes on items and fulfillments
Use the [replace tax data](/v3/api-reference/carts-v3/validations/add-tax) endpoint to create sales taxes on items and fulfillments as in the following example:
```curl
curl --location --request PUT '{{modular_cart_domain}}/carts/ba0e93f5-e47f-4b0d-bac8-6233b67ef65f/tax' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
"items": [
{
"id": "c0f1c36d-35e6-4098-94a7-3b92fba089d7",
"tax": [
{
"amount": 10,
"attributes": {
"rate": 8
}
},
{
"amount": 2,
"attributes": {
"rate": 3
}
}
]
}
],
"fulfillments": [
{
"id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",
"tax": [
{
"amount": 10,
"attributes": {
"rate": 1
}
},
{
"amount": 4,
"attributes": {
"VAT": "enabled"
}
}
]
}
]
}'
```
### Applying sales taxes on items, fulfillments and the service charge
Use the [replace tax data](/v3/api-reference/carts-v3/validations/add-tax) endpoint to create sales taxes on items and fulfillments, and service charge which are also taxable as in the following example:
Ensure that fulfillment fees are set to taxable.
```json
{
"id": "d4e9f8dc-c0ae-4ef3-be8b-bd23579a4dd3", // feeId
"name": "fulfillment-fee",
"price": {
"amount": 5.0
},
"taxable": true,
"attributes": {
"message": "Shipping fee"
},
"tax": {
"total": 0,
"collection": []
},
"updatedAt": "2024-09-02T15:21:19.874Z",
"createdAt": "2024-09-02T15:21:19.874Z"
}
```
Add tax to the cart `curl`.
```curl
curl --location --request PUT 'https://dev.cart.fabric.inc/beta/v3/modular/carts/ba0e93f5-e47f-4b0d-bac8-6233b67ef65f/tax' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
"items": [
{
"id": "2c51a3da-e3ff-40ef-bb5b-3e191892293c",
"tax": [
{
"amount": 10,
"attributes": {
"rate": 8
}
},
{
"amount": 2,
"attributes": {
"rate": 3
}
}
]
}
],
"fulfillments": [
{
"id": "131b9a58-8ee5-41dc-a79e-736ca934b435",
"tax": [
{
"amount": 10,
"attributes": {
"rate": 1
}
},
{
"amount": 4,
"attributes": {
"VAT": "enabled"
}
}
],
"fees": [
{
"id": "d4e9f8dc-c0ae-4ef3-be8b-bd23579a4dd3",
"tax": [
{
"amount": 1,
"attributes": {
"rate": 1
}
}
]
}
]
}
]
}'
```
# Getting Started with fabric Carts API
This guide provides instructions to help you get started with fabric Carts API, from initial setup to basic usage.
## Target Audience
* Third-party developers who set up Carts on behalf of merchants.
* The fabric developers who work with Carts.
### Knowledge and Skill Requirements
The target audience should:
* Understand [REST APIs](https://fabric.inc/blog/developer/api-endpoint), in the context of e-commerce.
* Get familiar with [fabric APIs](/v3/api-reference/getting-started/getting-started-with-fabric-apis).
* Know the cart [configuration](/v3/api-reference/carts-v3/configuration-behaviors) and [merge](/v3/api-reference/carts-v3/merge-carts-behaviors) behaviors.
* Have access to development tools capable of interacting with HTTP-based APIs, such as Postman or cURL for testing.
## Workflow
The following steps outline the Carts process, from creating a cart to generating an order draft:
1. [Create an empty cart](/v3/api-reference/carts-v3/carts/carts) for shoppers to add products for purchase.
You can customize the cart settings by sending configuration details in the request body. Otherwise, the default settings apply. For more information about cart configuration behaviors, see [Configuration Behaviors](/v3/api-reference/carts-v3/configuration-behaviors) section. If the initial request is successful, a response body containing cart information, such as `cartId` and configurations is returned.
2. [Create a destination address](/v3/api-reference/carts-v3/addresses/create-addresses) to fulfill the order in the cart.
You can [delete](/v3/api-reference/carts-v3/addresses/delete-addresses) or [update](/v3/api-reference/carts-v3/addresses/update-addresses) the address. If the initial request is successful, a response body that contains the address information is returned.
3. [Create all the necessary fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) information for the cart.
You can [partially update](/v3/api-reference/carts-v3/fulfillment/add-fulfillments-attribute) or [delete](/v3/api-reference/carts-v3/fulfillment/delete-fulfillments-attribute) fulfillment attributes, [fully update](/v3/api-reference/carts-v3/fulfillment/update-fulfillments) fulfillments, or [delete them entirely](/v3/api-reference/carts-v3/fulfillment/delete-fulfillments) if needed. If the initial request is successful, a response body containing fulfillment information is returned.
4. [Add items](/v3/api-reference/carts-v3/items/items) to the cart.
You can [update](/v3/api-reference/carts-v3/items/update-items) or [delete](/v3/api-reference/carts-v3/items/delete-items) items in the cart. If the initial request is successful, a response body that contains the cart information, including the items that are added, is returned.
5. (Optional) [Apply any eligible coupons](/v3/api-reference/carts-v3/coupons/add-coupons) for the cart.
Use [remove the coupon](/v3/api-reference/carts-v3/coupons/remove-coupons) endpoint to remove coupons if necessary. If the initial request is successful, a response body that contains the cart information, including the coupon information, is returned.
6. [Add tax rules](/v3/api-reference/carts-v3/validations/add-tax) for the cart. Look up the usage as tax rates vary by location. You must apply the appropriate taxes for each area.
If the initial request is successful, a response body that contains cart information with the updated tax rates is returned.
7. [Add a payment method](/v3/api-reference/carts-v3/payments/add-payment-attributes) for the cart.
You can [partially update](/v3/api-reference/carts-v3/payments/add-payment-attributes) or [delete payment attributes](/v3/api-reference/carts-v3/payments/delete-payment-attributes) and [fully update](/v3/api-reference/carts-v3/payments/update-payments) or [delete payment methods entirely](/v3/api-reference/carts-v3/payments/delete-payments). If the initial request is successful, a response body containing payment information is returned.
8. [Create an order draft](/v3/api-reference/carts-v3/order-drafts/create-order-drafts). If the payment is authorized, then the order is shipped.
If the initial request is successful, the response containing all the necessary information for an order to ship is returned. Before submitting the order details, ensure that all the information for the order is correct.
# Create fee
modular-cart post /carts/{cartId}/fees
Creates a fee that is applied to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete fee
modular-cart delete /carts/{cartId}/fees/{feeId}
Removes a fee from the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fee ID from the [Create fee](/v3/api-reference/carts-v3/fees/delete-fees) endpoint is used in the path parameter.
# Update fee
modular-cart patch /carts/{cartId}/fees/{feeId}
Updates a fee in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fee ID from the [Create fee](/v3/api-reference/carts-v3/fees/delete-fees) endpoint is used in the path parameter.
# Create fulfillment adjustment
modular-cart post /carts/{cartId}/fulfillments/{fulfillmentId}/adjustments
Creates an adjustment to the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Delete fulfillment adjustment
modular-cart delete /carts/{cartId}/fulfillments/{fulfillmentId}/adjustments/{adjustmentId}
Removes the adjustment from the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
The Adjustment ID from the [Create fulfillment adjustment](/v3/api-reference/carts-v3/fulfillment-adjustments/create-fulfillment-adjustments) endpoint is used in the path parameter.
# Update fulfillment adjustment
modular-cart patch /carts/{cartId}/fulfillments/{fulfillmentId}/adjustments/{adjustmentId}
Updates the adjustment to the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
The Adjustment ID from the [Create fulfillment adjustment](/v3/api-reference/carts-v3/fulfillment-adjustments/create-fulfillment-adjustments) endpoint is used in the path parameter.
# Create fulfillment fee
modular-cart post /carts/{cartId}/fulfillments/{fulfillmentId}/fees
Creates a fee associated the fulfillment.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Delete fulfillment fee
modular-cart delete /carts/{cartId}/fulfillments/{fulfillmentId}/fees/{feeId}
Removes the fee from associated with the fulfillment.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
The Fee ID from the [Create fulfillment fee](/v3/api-reference/carts-v3/fulfillment-fees/add-fulfillment) endpoint is used in the path parameter.
# Update fulfillment fee
modular-cart patch /carts/{cartId}/fulfillments/{fulfillmentId}/fees/{feeId}
Updates the fee associated with the fulfillment.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fee ID from the [Create fulfillment fee](/v3/api-reference/carts-v3/fulfillment-fees/add-fulfillment) endpoint is used in the path parameter.
# Add fulfillment attributes
modular-cart post /carts/{cartId}/fulfillments/{fulfillmentId}/actions/add-attributes
Partially updates the attributes of the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Create fulfillment
modular-cart post /carts/{cartId}/fulfillments
Creates a fulfillment to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete fulfillment
modular-cart delete /carts/{cartId}/fulfillments/{fulfillmentId}
Removes the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Delete fulfillment attributes
modular-cart post /carts/{cartId}/fulfillments/{fulfillmentId}/actions/delete-attributes
Partially deletes attributes of your choice in the fulfillment object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Get fulfillment
modular-cart get /carts/{cartId}/fulfillments/{fulfillmentId}
Returns the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Update fulfillment
modular-cart put /carts/{cartId}/fulfillments/{fulfillmentId}
Updates the fulfillment associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Fulfillment ID from the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint is used in the path parameter.
# Update item attributes
modular-cart post /carts/{cartId}/items/{itemId}/actions/add-attributes
Partially updates the attributes of your choice in the item object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Delete item attributes
modular-cart post /carts/{cartId}/items/{itemId}/actions/delete-attributes
Partially deletes attributes of your choice in the item object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Split line items
modular-cart post /carts/{cartId}/items/{itemId}/actions/split
Splits the item associated with the corresponding cart into multiple line items based on quantity.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Create item adjustment
modular-cart post /carts/{cartId}/items/{itemId}/adjustments
Creates an adjustment for the item in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Delete item adjustment
modular-cart delete /carts/{cartId}/items/{itemId}/adjustments/{adjustmentId}
Deletes the adjustment from the item associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
The Adjustment ID from the [Create item adjustment](/v3/api-reference/carts-v3/item-adjustments/create-item-adjustments) endpoint is used in the path parameter.
# Update item adjustment
modular-cart patch /carts/{cartId}/items/{itemId}/adjustments/{adjustmentId}
Updates the adjustment to the item associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
The Adjustment ID from the [Create item adjustment](/v3/api-reference/carts-v3/item-adjustments/create-item-adjustments) endpoint is used in the path parameter.
# Create item fee
modular-cart post /carts/{cartId}/items/{itemId}/fees
Creates a fee for the item.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Delete item fee
modular-cart delete /carts/{cartId}/items/{itemId}/fees/{feeId}
Deletes the fee that is applied to the item.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
The Fee ID from the [Create item fee](/v3/api-reference/carts-v3/item-fees/create-item-fees) endpoint is used in the path parameter.
# Update item fee
modular-cart patch /carts/{cartId}/items/{itemId}/fees/{feeId}
Updates the fee that is applied to the item.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
The Fee ID from the [Create item fee](/v3/api-reference/carts-v3/item-fees/create-item-fees) endpoint is used in the path parameter.
# Delete item
modular-cart delete /carts/{cartId}/items/{itemId}
Deletes the item from the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Get item
modular-cart get /carts/{cartId}/items/{itemId}
Returns the item from the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Create item
modular-cart post /carts/{cartId}/items
Creates the item in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Update item
modular-cart patch /carts/{cartId}/items/{itemId}
Updates the item in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Merge Cart Behaviors
The Merge Cart Behaviors page provides an overview of the configuration settings and the associated functionalities.
To ensure your merged cart functions as intended, you must specify which configurations to activate when making a [Merge carts](/v3/api-reference/carts-v3/cart-actions/merge) request.
| Merge Cart Behavior | Represents |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MERGE | Include both primary and secondary resources, and in case of a conflict, override secondary data with primary data. For example, a coupon can be merged between carts. If one cart has no coupon and the other does, the merged cart will retain the coupon. However, if one cart has a 10% discount and the other has a 20% discount, the merge cannot happen exactly due to conflicting coupon functions. In this case, the 20% discount from the second cart will be discarded, and the merged cart will have the 10% discount. |
| ALL | Include both primary and secondary resources together without checking for conflicts. This is mostly applicable for list resources. |
| PRIMARY | Only include primary resources. |
| SECONDARY | Only include secondary resources. |
| PURGE | Remove both primary and secondary resources. |
| REFERENCED | Add primary resources and retain only the secondary resources that are referred to in the merged cart. |
## Merge Results
### Validations merge
* **Behavior for lineItems validation**: Inherited from [`mergeBehavior.item.behavior`](/v3/api-reference/carts-v3/cart-actions/merge).
* **Behavior for product catalog validation**: Inherited from [`mergeBehavior.item.behavior`](/v3/api-reference/carts-v3/cart-actions/merge).
When carts are merged, promotions are cleared due to updated items, quantities, taxes, or fulfillments in the cart. Additionally, a state is added to refresh the promotions.
### Taxes
Taxes follow the same rules as the parent item. For example, if the item merge rule is set to secondary, the respective taxes are included accordingly.
When the item merge rule is set to `MERGE`, taxes are cleared, and a state is added to the cart indicating that the item is missing taxes. This adjustment is necessary because changes in quantities may require tax updates.
### Item quantity behavior
Item merge behaviors are:
* **Default (SUM)**: Quantities of items with the same SKU are summed.
* **MAX**: The highest quantity of items with the same SKU is selected.
### States
You must fully re-evaluate the state object for the merged cart from the response body to ensure the merged cart is configured with the intended settings.
## Related Topics
* [Merge carts](/v3/api-reference/carts-v3/cart-actions/merge)
# Create an order draft
modular-cart post /order-drafts
Create an order using the cart ID of the cart that contains the order.
# Get the order draft by the customer ID
modular-cart get /order-drafts/customer/{customerId}
Retrieves the order draft using the customer ID associated with it from [Create an order draft](/v3/api-reference/carts-v3/order-drafts/create-order-drafts) endpoint.
# Get the order draft by the order draft ID
modular-cart get /order-drafts/{orderDraftId}
Retrieves the order draft using the order ID associated with it from [Create an order draft](/v3/api-reference/carts-v3/order-drafts/create-order-drafts) endpoint.
# Get the order draft by the order draft number
modular-cart get /order-drafts/order-number/{orderNumber}
Retrieves the order draft using the order number associated with it from [Create an order draft](/v3/api-reference/carts-v3/order-drafts/create-order-drafts) endpoint.
# Overview
### Carts 3.0
fabric's Cart API is used to add, update, and remove items from your Storefront cart, either as a guest or logged-in user. It also supports merging carts when transitioning from a guest to a logged-in user, and applying coupons and other attributes, such as gift wrapping, to line items. The API supports advanced features like using multiple carts within a B2B organization, sharing carts, and providing a unified cart experience for multi-region and multi-brand businesses.
The Cart API supports configurability for end-to-end order processing actions by adding items to the cart, handling pre-checkout tasks like billing, shipping, and payment details, and proceeding to checkout, where orders are processed and confirmed by fabric's Order Management System (OMS).
Cart 3.0 is modular, enabling users to select only the necessary endpoints. It integrates seamlessly with both fabric and non-fabric services.
### Cart orchestrator
If you're using other fabric services, you can leverage the Cart Orchestrator endpoints for seamless integration with those services.
### Contact and support
If you have any additional questions, please reach out to the Cart support team at [support.cnc@fabric.inc](mailto:support.cnc@fabric.inc).
# Add payment attributes
modular-cart post /carts/{cartId}/payments/{id}/actions/add-attributes
Partially updates attributes of your choice in the payment.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
# Create payment
modular-cart post /carts/{cartId}/payments
Adds a payment method to the corresponding cart to process a transaction.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete payment attributes
modular-cart post /carts/{cartId}/payments/{id}/actions/delete-attributes
Partially deletes attributes of your choice in the payment object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
# Delete payment
modular-cart delete /carts/{cartId}/payments/{id}
Removes the payment from the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
# Update payment
modular-cart patch /carts/{cartId}/payments/{id}
Updates the payment in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
# Create add-on
addons.openapi post /addons
Create an add-on with its price and currency details. By creating add-ons, you can enhance customer experience by allowing them to choose personalized products while placing an order.
# Delete a specific add-on
addons.openapi delete /addons/{id}
Delete an add-on by ID.
# Get a specific add-on
addons.openapi get /addons/{id}
Get a specific add-on by ID.
# Get all add-ons
addons.openapi get /addons
Get a paginated list of all the created add-ons.
# Add-ons
Add-ons are additional items that shoppers can buy while placing an order. These endpoints let you create, update, and delete details of add-ons, including their prices and currency types.
# Update a specific add-on
addons.openapi put /addons/{id}
Update a specific add-on by ID.
# Delete attribute
attributes.openapi delete /attributes/{attributeId}
Using this endpoint, you can delete an attribute by its ID.
# Get all attributes
attributes.openapi get /attributes
Using this endpoint, you can get a paginated list of attributes. You can narrow down the search results by specifying pagination criteria, and you can also sort the results.
# Update attribute
attributes.openapi put /attributes/{attributeId}
Using this endpoint, you can update an attribute by its ID. You can primarily update attribute and its value.
# Download exported CSV file
exports-offers.openapi post /offers-exports/actions/download-export-file
This endpoint lets you generate a URL, using fileId, from which you can download the exported CSV file. The generated URL expires in five mins.
# Get all export requests
exports-offers.openapi get /offers-exports
Get a paginated list of all the export requests.
# Get export request by ID
exports-offers.openapi get /offers-exports/{exportId}
Get details of a specific export request by its ID.
# Initiate export request
exports-offers.openapi post /offers-exports
Initiate an export request based on specified filter criteria.
# Generate URL to import a CSV file
imports-offers.openapi post /offers-imports/actions/generate-upload-url
Use this endpoint to create a secured S3 URL to import a CSV file, allowing for bulk data updates from the information within the file. For example, if the data in the file is price type, then only the price related data will be updated. Note that an error will be shown if the type of data included in the file doesn't match with the data type mentioned in the request body. You must upload only one single file, specifically in the CSV format, to the generated URL.
# Get import job by ID
imports-offers.openapi get /offers-imports-jobs/{jobId}
Get details of a specific import job by job ID.
# Get import jobs
imports-offers.openapi get /offers-imports-jobs
Get a paginated list of import jobs.
# Retrieve the download URL for an error file
imports-offers.openapi post /offers-imports/actions/generate-error-file-download-url
Use this endpoint to retrieve an AWS S3 URL to access the error data of a previously imported file. The URL is valid for five minutes. Make a GET request with this URL to download the error data in a CSV format.
# Create price control
price-controls.openapi post /price-controls
Create a price control record that contains various price types other than the elemental prices such as base price, sale price, and sale price.
# Delete price controls by itemId
price-controls.openapi delete /price-controls/{itemId}
Delete price controls of a specific item by `itemId`
# Get all price controls
price-controls.openapi get /price-controls
Get a paginated list of all the created price controls.
# Get price controls by itemId
price-controls.openapi get /price-controls/{itemId}
Get price control records of an item by `itemId` and `priceListId`. If `priceListId` isn't specified, price controls of the item will be retrieved under the default price list.
# Get price controls by SKU
price-controls.openapi get /price-controls/sku/{sku}
Get price controls of a specific product by `sku`.
# Price Controls
With price control endpoints, merchants can create and manage more diversified prices, such as Manufacturer Recommended Retail Price (MSRP), Minimum Advertised Price (MAP), floor price, and ceiling price, for an item. These endpoints restrict any accidental changes to the base and sale prices.
# Update price controls by itemId
price-controls.openapi put /price-controls/{itemId}
Update price controls of a specific item by `itemId` and `piceListId`. If `priceListId` isn't specified, price controls of the item will be updated under the default price list.
# Create price method
price-methods.openapi post /price-methods
Create a price method that you can use to set up the SKU price. Price method can be created based on SKU quantity, dimension of the SKU, or any other strategy that aligns with the business.
# Delete a specific price method
price-methods.openapi delete /price-methods/{id}
Delete a specific price method by ID.
# Get all price methods
price-methods.openapi get /price-methods
Get a paginated list of all price methods of SKUs.
# Price Methods
Price methods are the different approaches or strategies used in calculating prices. These endpoints let you set up the SKU price by choosing a defined price method.
# Update a specific price method
price-methods.openapi put /price-methods/{id}
Update a specific price method by ID.
# Get price types
price-types.openapi get /price-types
Get a paginated list of all price types.
# Price Types
Using the price type endpoints, you can get the following price types:
* **Base price:** The regular amount that merchants charge shoppers to purchase an item.
* **Sale price:** The lowest amount that merchants charge shoppers to purchase an item without a promotion or coupon.
# Get priced products
priced-products.openapi get /priced-products
Get a paginated list of products and prices for the specified price list ID.
# Get product and price details by product item ID
priced-products.openapi get /priced-products/{itemId}
Get product and price details by product item ID
# Get product and price details by SKU
priced-products.openapi get /priced-products/sku/{sku}
Retrieves the details of a product and its associated prices using the SKU, including the details for the variants of the product, if any.
# Get SKUs in price list
priced-products.openapi get /priced-products-identifiers
Retrieve SKUs and product item IDs that have a price entry in the given price list.
# Add Coupon
modular-cart post /carts/{cartId}/coupons/{couponId}
Adds a coupon to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Coupon ID, which is the coupon code generated when [creating a custom coupon](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) in Copilot, is used in the path parameter.
# Removes Coupon
modular-cart delete /carts/{cartId}/coupons/{couponId}
Removes the existing coupon from the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Coupon ID is a coupon code generated when [creating a custom coupon](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) in Copilot and is used in the path parameter.
# Add customer attributes
modular-cart post /carts/{cartId}/customer/actions/add-attributes
Partially updates attributes of your choice in the customer object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete customer attributes
modular-cart post /carts/{cartId}/customer/actions/delete-attributes
Partially deletes attributes of your choice in the customer object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Update customer
modular-cart patch /carts/{cartId}/customer
Updates the customer information in the cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Apply coupon
ShopperXP post /orchestrator/carts/{cartId}/coupons/{couponCode}
Apply a coupon code to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The coupon code generated when [creating a custom coupon](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) in Copilot is used in the path parameter.
# Delete cart
ShopperXP delete /orchestrator/carts/{cartId}
Removes the cart corresponding to the provided cart ID.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Removes coupon
ShopperXP delete /orchestrator/carts/{cartId}/coupons/{couponCode}
Removes the coupon from the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Get the cart
ShopperXP get /orchestrator/carts/{cartId}
Retrieves the cart information corresponding to the provided cart ID.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Create an order draft
ShopperXP post /orchestrator/carts/{cartId}/order-drafts
Creates an order from the current cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Add items
ShopperXP post /orchestrator/carts/{cartId}/items
Add items to the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Delete items
ShopperXP delete /orchestrator/carts/{cartId}/items
Removes the items from the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Split line items
ShopperXP post /orchestrator/carts/{cartId}/items/{itemId}/actions/split
Splits the item associated with the corresponding cart into multiple line items based on quantity.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
# Update items
ShopperXP patch /orchestrator/carts/{cartId}/items
Updates the item information in the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Authorize payments
ShopperXP post /orchestrator/carts/{cartId}/payments/actions/authorize
Authorize payments made within the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Void payments
ShopperXP post /orchestrator/carts/{cartId}/payments/actions/void
Void payments made within the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Replace inventory data
modular-cart put /carts/{cartId}/inventory
Replaces inventory data associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Replace product data
modular-cart put /carts/{cartId}/product
Replaces product data associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Replace promotions
modular-cart put /carts/{cartId}/promotions
Replaces promotions associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Replace tax data
modular-cart put /carts/{cartId}/tax
Replaces tax data associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Updates inventory data
modular-cart patch /carts/{cartId}/inventory
Partially updates inventory data associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Updates product data
modular-cart patch /carts/{cartId}/product
Partially updates product data associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
# Add a new address
customers.openapi post /customers/{customerId}/customer-address
Using this endpoint, you can add a new address for the customer by `customerId`.
# Delete customer's address
customers.openapi delete /customers/{customerId}/customer-address/{addressId}
Using this endpoint, you can delete an existing address of a customer based on the `customerId` and `addressId`.
# Get customer's address
customers.openapi get /customers/{customerId}/customer-address/{addressId}
Using this endpoint, you can get a single address of a customer based on the `customerId` and `addressId`.
# Get customer's addresses
customers.openapi get /customers/{customerId}/customer-address
Using this endpoint, you can get all addresses of a customer.
By specifying the query parameters `offset` and `limit`, you can narrow down the search results. You can also `sort` the results in an ascending or descending order. Additionally, with the `isDeleted` query parameter, you can filter for either deleted or non-deleted customers. When no query parameter is specified, by default, you get up to 10 records.
# Customer Address
These endpoints provide the features for store admins to create and manage customers' addresses.
# Partially update customer's address
customers.openapi patch /customers/{customerId}/customer-address/{addressId}
Using this endpoint, you can partially update a customer's address based on the `customerId` and `addressId`. To fully replace an existing address, use the `PUT /customers/{customerId}/customer-address/{addressId}` endpoint.
# Search for customer's addresses
customers.openapi post /customers/{customerId}/customer-address/search
With this endpoint, you can search for customer's addresses based on the specified filter conditions. In addition, you can tailor the search results by including or excluding the deleted addresses and the default addresses.
**Note**:A customer can have a default address for both billing and shipping.
# Update customer's address
customers.openapi put /customers/{customerId}/customer-address/{addressId}
Using this endpoint, you can update a customer's address based on the `customerId` and `addressId`. This replaces the existing address with the new one. If you want to make only a partial update, use the `PATCH /customers/{customerId}/customer-address/{addressId}` endpoint.
# Add a new customer
customers.openapi post /Customers
Using this endpoint, you can add a new customer to the system. The response includes an `id` which is required in subsequent calls, such as `GET /customers/{customerId}`, `PUT /customers/{customerId}`, `PATCH /customers/{customerId}`, and more.
When `externalId` is specified, the customers have the ability to manage their own details through the storefront UI.
# Delete customer
customers.openapi delete /customers/{customerId}
With this endpoint, you can delete an existing customer data by `customerId`.
# Get customer details
customers.openapi get /customers/{customerId}
Using this endpoint, you can get details of a single customer by `customerId`.
# Get customers
customers.openapi get /Customers
Use this endpoint to get a paginated list of customers.
By specifying the query parameters `offset` and `limit`, you can narrow down the search results. You can also `sort` the results in an ascending or descending order. Additionally, with the `isDeleted` query parameter, you can filter for either deleted or non-deleted customers. When no query parameter is specified, by default, you get up to 10 records.
# Partially update customer details
customers.openapi patch /customers/{customerId}
Using this endpoint, you can partially update details of a customer by `customerId`. To fully replace the details of an existing customer, use the `PUT /customers/{customerId}` endpoint.
# Search for customer
customers.openapi post /customers/search
Using this endpoint, you can search for customers based on filter conditions. By specifying `offset` and `limit`, you can narrow down your search results. In addition, using the `isDelete` property in the request body, you can filter for either deleted or non-deleted customers.
# Update customer details
customers.openapi put /customers/{customerId}
Using this endpoint, you can update details of an existing customer by `customerId`.
This endpoint replaces the existing details of the customer. If you want to make only a partial update, without replacing the entire details, use the `PATCH /customers/{customerId}` endpoint.
# Update customer status
customers.openapi post /customers/{customerId}/actions/update-status
With this endpoint, you can update the account status of an existing customer by `customerId`.
# Add address - customer context.
customers.openapi post /customers/self/customer-address
Using this endpoint, a customer can add their address through a storefront UI.
# Delete address - customer context
customers.openapi delete /customers/self/customer-address/{addressId}
Using this endpoint, a customer can delete their own address through the storefront UI based on `addressId`.
# Get customer details - customer context
customers.openapi get /customers/self
Using this endpoint, a customer can view their details through the storefront UI.
# Customer Self
These endpoints provide the feature for customers or shoppers to independently manage their details in the storefront.
# Update address - customer context
customers.openapi put /customers/self/customer-address/{addressId}
Using this endpoint, a customer can update their own address through the storefront UI based on `addressId`.
# Update customer details - customer context
customers.openapi put /customers/self
Using this endpoint, customers can update their own details through the storefront UI.
# View address - customer context
customers.openapi get /customers/self/customer-address/{addressId}
Using this endpoint, a customer can view their own address through the storefront UI based on the `addressId`.
# View addresses - customer context
customers.openapi get /customers/self/customer-address
Using this endpoint, a customer can view their own addresses through the storefront UI.
# Feedback and Contact
We value your feedback and suggestions. For any feedback, questions, or support, reach out to our [support team](https://support.fabric.inc/hc/en-us/requests/new).
# Commerce Platform
## New Features
### Operational alerts subscription management (Admin Feature)
Copilot Admins can subscribe or unsubscribe users to an alert, view the subscribers to an alert, and manage their alert subscription status.
[fabric Alerts guide](/v3/guides/home/alerts/alerts-overview)
### User Management: Bulk add roles to users (Admin Feature)
Copilot Admins can add new roles to users in bulk. In previous releases, the Copilot Admin could only replace a users roles.
[fabric User Management guide](/v3/guides/settings/user-management/user-management)
# Dropship
## New Features
### Enhanced compatibility check error handling
* **Ruleset Error Report:** Each proposal's compatibility check returns an error report file. This report includes all SKUs and an itemized list of errors corresponding to them.
* **Ruleset Failure Report:** A separate file is generated for items that encountered errors during the compatibility check. You can address these specific items and re-import them without re-processing the entire proposal.
### Improved import error handling
* **A List of SKUs:** For every import with one or more errors, an error report file is generated. This report includes all SKUs and provides an itemized list of errors corresponding to each SKU.
* **A Template with Only Errored Items:** A separate file is generated that includes only the items with one or more errors. This allows users to fix these specific items and re-import them without needing to handle the entire original file again.
### Fabric Integration
If you are a merchant using Dropship with other Fabric products such as Catalog or Orders, you can set up integration workflow and configurations on the UI. This enables you to create and update multiple templates for publishing products to Fabric Catalog.
* [Dropship fabric integration guide](/v3/guides/dropship-retailers/fabric-integration)
### Template Cloning
Templates can now be cloned with a single-click action on the template details screen, making it easier to duplicate existing templates.
* [Dropship templates guide](/v3/guides/dropship-retailers/settings/templates)
### Shopify Integration
* **Fraud Order Protection:** Retailers can now specify whether they want to import orders flagged as High or Medium risk by Shopify.
* **Variant-Level Metafields:** Retailers can now publish Metafields and their values at the variant level. Previously, only products could include Metafields.
* **Additional Metafield Types:** Added support for additional Metafield types such as `multi_line_text_field`, `boolean`, `URL`, and `date_time`.
* **Customizable Order Notes:** Order notes can now be customized to include the “Fulfill By” date.
* **Data Override on Publish:** Any publish to Shopify actions by retailers now override the data for products and variants in Shopify with the data in Dropship. Empty attributes aren't sent.
* [Shopify integration guide](/v3/guides/dropship-retailers/shopify-integration)
### Address fields
All countries and their provinces are now available to be added in all address fields across the platform.
### Order Bulk Utility Tool
The new bulk order utility tool allows suppliers to manage orders using a CSV import. You can cancel orders for the following use cases:
* Cancel Entire Orders by PO Number
* Cancel specific order lines by SKU
* Cancel all order lines of specific SKU
### Retailer Assets
Retailers can now make their playbook and other assets available to all supplier partners through the portal. They need to share the assets with the Fabric team, which can upload them on their account and suppliers will be able to access them on the connection details page.
* [Retailer information guide](/v3/guides/dropship-suppliers/retailer-information)
# Fulfillment
## New Features
### Order fulfillment logic rulesets
The order fulfillment feature enables you to create fulfillment rule sets. Fulfillment rule sets are used to direct orders to different fulfillment locations based on characteristics such as geo-location, warehouse location, item price, order attribute type, and more. For more information, see the [Order Fulfillment Logic Guide](/v3/guides/orders/order-fulfillment-logic/order-fulfillment-logic).
### Location capacity limits
* You can now set location specific allocation capacity limits.
* Added support for bulk uploads for special location allocation capacity planning to adjust capacity limits based on upcoming events or seasonal fluctuations. For more information, see the [Location Setup Guide](/v3/guides/inventory/locations#location-setup).
### Location Import & Export
* You can now bulk import a list of multiple locations using the import CSV file feature.
* You can now export location data, scheduled outages, and temporary capacity plans.
For more information, see the [Importing Locations Guide](/v3/guides/inventory/locations#importing-locations).
# Offers
# New Features
## Independent Price Bulk Upload
You can now import new products to Product Catalog and prices to Offers in parallel. If a new product is imported to Product Catalog at the same time as its associated pricing file is imported to Offers, Fabric automatically queues the prices that don't have an associated SKU yet created in Product Catalog and retries the SKU lookup until the product is successfully created in Product Catalog. No more file sequencing between Product Catalog and Offers.
## Calculated Price Export
Ability to export the calculated price for 1 or more products, including eligible sale and promotion discounts. The exported file will include:
* SKU
* Price list ID
* Cost
* Sale price
* Base price
* Price Start Date
* Price End Date
* Calculated price
* Promotion IDs
* Promotion message: PDP
* Promotion message: PLP
Products can be queried by:
* `calculationTime`
**Price Filters:**
* **Price list:** Users should be able to specify the price list for which the price belongs and export the calculated price accordingly.
* **PriceType:** Users should be able to specify the `priceType` with base or sale and only export the calculated price for those accordingly.
[Calculated Price Export](https://developer.fabric.inc/v3/api-reference/offers/exports/initiate-export-request)
# Orders
## New Features
### Exchanges
You can now exchange items for the same item in a different size or color, exchange one of two items for a different item, and exchange an item for a different item. The difference in cost is automatically calculated. For more information, see the [Exchange Orders Guide](/v3/guides/orders/order-management/exchange-orders).
### Order Appeasements
By creating an appeasement refund, you can issue discretionary refunds. The appeasement option for an order is enabled only after the payment process is initiated for the order. Orders with the Fraud status can't be appeased. For more information, see the [Order Management Appeasements Guide](/v3/guides/orders/order-management/appeasements).
### Order Details
* Added return metrics to the order total summary to represent the total refund amount.
* Updated the progress steps for item groups and split shipments to display shipping groups separately.
* Added the ability to preview an item's individual attributes.
For more information, see the [Viewing Details of an Order - Basic Details](/v3/guides/orders/order-management/viewing-details-of-an-order/basic-details) section.
### Order Details Shipments Tab
Added an additional order details shipment tab to display item details such as shipped quantities.
For more information, see the [Viewing Details of an Order - Shipment Details](/v3/guides/orders/order-management/viewing-details-of-an-order/shipment-details) section.
### Order Details Activity Log
Added an additional order details activity log tab to display the history of changes for an order.
For more information, see the [Viewing Details of an Order - Viewing Activity Log](/v3/guides/orders/order-management/viewing-details-of-an-order/viewing-activity-log) section.
## Copilot Enhancements
### Policies
Added the ability to mark return, exchange, and cancellation policies as default. Additionally, added the ability to apply a policy to all your configured channels.
For more information, see the [Policies Guide](/v3/guides/orders/settings/policies).
### Error Handling
Added additional error handling banners. When an order has errors such as missing customer details, an error banner appears. Clicking the banner opens a window with the error details and how to fix the errors.
### New Order Searching & Filtering
The Manage Orders page displays a list that includes every order. This list can be filtered by Order Status, Order Date, Order Total, and Channel so that the list only displays orders that match the filter parameters. Additional search and filter parameters down to the attribute level have been added.
For more information, see the [Filtering Orders Guide](/v3/guides/orders/order-management/filtering-orders).
### Added Additional Order Line Statuses
Two new order line statuses were added: `PENDING_ALLOCATION` and `PENDING_REALLOCATION`.
### Inventory Activity Log
The Inventory Activity Log can now be sorted and filtered.
# Product Catalog
## New Features
### Cancellation of Product Import Jobs
Cancel product import jobs that are scheduled or in progress. For more information, see the following documentation pages:
* [Managing Background Jobs](https://developer.fabric.inc/v3/guides/product-catalog/background-jobs/managing-background-jobs)
* [Cancel Background Jobs](https://developer.fabric.inc/v3/api-reference/product-catalog/jobs/cancel-background-jobs)
## Copilot Enhancement
### Redesigned Collections Management
We’ve done a complete overhaul of the collection management experience and it's now much easier and faster to manage your collections. For more information, see the [Collections Overview](https://developer.fabric.inc/v3/guides/product-catalog/collections/collections) section.
### Collection Node Sorting
Ability to sort collection nodes by name in Copilot. For more information, see the [Sorting Collections](https://developer.fabric.inc/v3/guides/product-catalog/collections/managing-collections#sorting-collections) section.
### Product Search Using Comma Separated Values
Ability to search for multiple products in the Product Item List Page search bar using a comma as the value separator. or more information, see the [Searching, Filtering, Sorting Items](https://developer.fabric.inc/v3/guides/product-catalog/list/items/searching-filtering-sorting-items) section.
# API Changes
## New Endpoints
* **Bulk Product Search Using “Comma” Separator**: Search for multiple products using a comma separator. For more information, see the following sections:
* [Search Products by ID](https://developer.fabric.inc/v3/api-reference/product-catalog/product-operations-by-id/get-product-by-id)
* [Search Products by SKU](https://developer.fabric.inc/v3/api-reference/product-catalog/product-operations-by-sku/get-product-by-sku)
# Release Summary
**Release Date**: July 2024
We are thrilled to introduce the latest features and enhancements designed to elevate your order management, data handling, and collection management experiences. This release brings powerful new tools and improvements aimed at optimizing your workflows, enhancing operational efficiency, and providing a more intuitive user experience:
* Order Orchestration with real time inventory and location management
* Improvements for data imports and exports
* Redesigned Collections experience with enhanced features
# Dropship
## Feature Enhancements
### Inventory Management
Negative inventory values are now skipped and not sent to external systems, including fabric OMS. When inventory is negative a zero value is sent.
### Invoice Improvements
* Invoice numbers now support up to 128 characters.
* The Invoice Export spreadsheet includes SKU information for each invoice line.
### File Transfer Protocol System Expansion (Suppliers only)\*\*
The File Transfer Protocol (FTP) system for Shipments and Inventory now supports Invoices.
### Packing Slips
Packing Slips now use attribute values from the retailer’s scope rather than the supplier’s original values.
### Compliance Scorecard
Retailers can now export the monthly compliance reports for their suppliers.
### Order Line Consolidation Options (Supplier & Retailer on EDI)
* Suppliers can now specify and receive separate order lines for the same item if a retailer opts to skip order line consolidation.
* **EDI Mapping:**
* **EDI 850:** SLN (Sub-line number) is used to store this information.
* **EDI 856:** LIN10 (Line number 10) is used to store this information.
### ShipStation Integration (Supplier only)
A link to the packing slip is now included in the notes sent to ShipStation.
### Loop Integration
Carrier information is now being fetched along with the tracking number for returns.
### fabric Products Integration
* Retailers can now create and manage templates for fabric Products directly from the UI.
* Any items published from Dropship now have attributes `“Dropship?” = TRUE` and `Vendor ID` populated by default.
### fabric Orders Integrations
Discounted Shipping cost is now being captured and passed on to suppliers if a retailer is using discounts for shipping costs in their Order Management.
## Shopify integration enhancements
### Variant Management (Retailer only)
Retailers can now edit or remove any duplicate variants in the system.
### Order Syncronization\*\*
fabric now runs a background job that audits Orders and reruns them every 24 hours to sync any missed orders.
### API Migration to GraphQL
Ahead of Shopify's deprecation of REST APIs for Products (Feb 2025), fabric product endpoints have migrated to use GraphQL. This migration supports:
* Product and collection synchronization
* Inventory syncing
* Fulfillment workflows
* Syncronization of Shopify Variant IDs
## Copilot Enhancements
### Proposal Details Page
* **Products Tab:**
* **New Sidebar View:** Displays product attributes, variants, comments, and issues.
* **Product Actions:** New "Approve/Remove" options added for each product.
* **Commenting on Products:** You can now add comments on individual products, with support for replies and reactions.
* **Issues Management:** Products can now be directly added to issues from the sidebar.
* **Items & Pricing Tab:**
* **Sidebar for Variant Attributes:** The sidebar replaces the previous window for displaying variant attributes.
* **Action Removal:** Actions have been removed; variants can no longer be added to issues or approved/removed individually or in bulk.
* **Issues:**
* **Sidebar for Products and Notes:** The sidebar now replaces the window for displaying products and notes associated with issues.
* **Comments Section:**
* **Proposal-Level Comments:** You can add comments at the proposal level, including reply and tagging capabilities.
* **Reactions:** Reactions have been added to enhance engagement on comments.
* [Dropship Proposals section](/v3/guides/dropship-retailers/proposals)
### Integrations
* Integrations for Shopify and fabric platforms are now available to be setup from the settings UI.
* [Shopify integration](/v3/guides/dropship-retailers/shopify-integration)
* [fabric integration](/v3/guides/dropship-retailers/fabric-integration)
### Templates
* Support added for internal and external platform templates for Shopify and fabric Products.
* [Templates section](/v3/guides/dropship-retailers/settings/templates)
# Fulfillment
## Feature Enhancements
* **Refresh Rate**: Increased the refresh cache default configuration from 3 hours to 24 hours. This helps to reduce failure during the allocation processing due to unready allocation.
* **Pending and Reallocation handling**: Allocation service now considers pending allocations when updating the allocation lines status. Additionally, reallocation now supersedes the cancel SLA process.
# Offers
## New Features
### Redesigned promotions management
Promotion management is easier than ever with the redesigned fabric promotions manager. Create a promotion in 4 steps with a simple guided screen. For more information, see the [Promotions Overview](/v3/guides/offers/Promotions/overview) section.
### Promotion Stacking for Exclusive and Type Exclusive
You can now select stacking priority for all types of promotions, giving marketing managers more control over margin and how promotions interact with one another. For more infomation, see the [Promotion Stacking](/v3/guides/offers/Promotions/overview#stacking-and-additional-settings) section.
# Orders
## Feature Enhancements
### Invoices and Returns
Order service now registers the original invoice shipment number for returned items.
# Product Catalog
## New Features
### Update and publish all product action
Operators now have the ability to select all products in their catalog and either update common attribute values or publish/unpublish them.There was previously a limit of 25 products for bulk updates in Copilot.
For more information, see the [Bulk Publishing](/v3/guides/product-catalog/list/items/bulk-operations-items#publishing) section.
## Copilot Enhancement
### OR condition on Collections
Users can now set more complex rules for merchandising collections using up to 5 OR conditions between attributes rules.
For more information, see the [Collections Rules and Conditions](/v3/guides/product-catalog/collections/collections#rules-and-conditions) section.
# Release Summary
**Release Date**: October 2024
We are excited to share the latest updates designed to streamline inventory management, supplier collaboration, and product data workflows. This release introduces key enhancements to improve operational efficiency and deliver a seamless user experience:
* Unified inventory management with enhanced data synchronization across systems
* Supplier onboarding improvements with new collaboration features
* Redesigned promotions management with stackable promotions for added flexibility
* Expanded bulk operations for product catalogs to update and publish at scale
# November 2023
## November 3, 2023
**Release Stage: Public Preview**
Today, we are releasing fabric Store Fulfillment to Public Preview to help retailers manage their store fulfillment operations more efficiently. With the iOS and Web Apps, retailers can offer convenient and flexible fulfillment options with pick-up in store and ship from store, increase revenue & sell-through by selling inventory from stores, and control order splitting and routing rules between stores and warehouses with fabric Order Fulfillment Logic.
### New Features
| Interface | Feature | Description |
| --------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Login | SSO Integration | The ability for a merchant to log into the app with their preferred SSO provider |
| Home | User Profile | The ability for the user to see their name, store name or location, and associate ID |
| Home | L1 Navigation | The ability for the user to see and select different logistics operation modes: Fulfillments, Pickups |
| Fulfillments | Fulfillments List Page | The ability for the user to see orders queues sorted and grouped by Service Level. |
| Pick | Pickup Shipping Method | Ability to manage Pick Up (Click and Collect or BOPIS). |
| Pick | Item Tiles | See details of each SKU during the picking process. |
| Pick | Device Camera Scan (Pick Scan) | Pick items across the store or shelves via camera scan of the barcode or any integrated hardware scanner |
| Pick | Manual Pick with SKU entry | Type barcode manually in case a barcode scan fails |
| Pick | Reject with Reason Codes (Scratch Items) | Enter different reason codes if the item isn't available. |
| Pack | Select Packaging | Display a drop-down option to select a box from a list of available boxes. |
| Pack | Device Camera Scan (Pack Scan) | Perform a secondary barcode scan at the packing station, as a validation mechanism ensuring that the right items are put in the box. |
| Pack | Gifting and Value Added Services | Ability to perform Value Added Service actions (such as Gift Wrapping or Personalized Messages). |
| Pick | Packing Slip | Ability on the app the print packing slips. |
| Ship | Shipping Label Generation and Printing | Auto-select a shipping label per order based on the Service Level of the order and supported carriers for the user. Allows for re-printing of labels. |
| Ship | Pickup label printing | Print another label type for BOPIS/Curbside orders based on the order type with a QR code (PX labels) Allows for re-printing of labels Also, prints packing slip per order at the same time (to be added to the box) |
| Order Lookup (Search) | Packing Slip Scan | Scan a barcode on packing slips to pull order details. |
| Order Lookup (Search) | Customer Order Search | Ability to search by name and order number. |
| Handoffs | Pickup signature | Confirm that the proof of identity was verified |