# Konnect API Reference Fynd Konnect is a unified platform built to streamline e-commerce and omni-channel operations by connecting seller's downstream systems (OMS, WMS, ERP, & POS) with the the top marketplaces and webstores alongside Fynd Commerce Fynd Konnect API Reference is a resource designed for quickly testing and exploring the functionality offered by Fynd Konnect. This reference provides: - **Schema Definitions**: Clear, concise data models for requests and responses to facilitate debugging and prototyping API integrations - **Try It Console**: Interactive testing directly from the documentation, enabling real-time experimentation with endpoints, response examination, and setup validation - **Endpoint Overview**: A structured catalog of Fynd Konnect APIs (Authorization, Catalog, Pricing, Inventory, Orders, Returns) for streamlined discovery and usage Dive into how Fynd Konnect can support operational and technical needs in a sandboxed, experimentation-friendly environment ## Servers Fynd Konnect [Sandbox] ``` https://fyndkonnect.konnect.uat.fyndx1.de ``` ## Security ### ApiKeyAuth Type: apiKey In: header Name: x-access-token ## Download OpenAPI description [Konnect API Reference](https://documentation.fynd.com/_bundle/konnect/apis/@1.0.0/konnect.yaml) ## Authorization - Provides endpoints for obtaining and managing authentication tokens Supports both Company-Level and Location-Level authorization modes, giving you fine-grained access control across multiple stores or warehouses - Integrate seamlessly with Fynd Konnect by exchanging your credentials for time-bound access tokens, ensuring secure interactions with all other APIs ### Generate Access Token - [GET /aggregator/v1/token](https://documentation.fynd.com/konnect/apis/konnect/authorization/generateaccesstoken.md): Exchange your credentials for an x-access-token that authorizes subsequent calls to Fynd Konnect APIs. Critical to ensure secure data exchange. Integrate this token into your request headers for endpoints like Catalog, Pricing Inventory, Orders, and Returns. > Note: The access token is valid for 24 hours from the time of generation. After expiration, you will need to generate a new token to continue making API requests with the same credentials. ## Catalog - Unified suite of APIs to manage product catalogs on Fynd Commerce Platform - Retrieve core catalog entities (brands, categories, departments, templates) and reference metadata (attributes, HS codes, tax rules) needed for product creation - Create, update, and delete products in bulk with full validation support - Fetch product listings and counts with pagination and filtering options - Track processing status for write operations via Check Product Status - Ideal for product synchronization, bulk catalog management, and validating data consistency across systems ### Departments - [GET /v3/catalog/departments](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchdepartments.md): Retrieve departments (top-level catalog groupings such as Men's Clothing, Accessories, Footwear, Grocery) > Departments help organize products and improve discovery ### Categories - [GET /v3/catalog/category](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchcategories.md): Retrieve product categories with a three-level hierarchy (L1 → L2 → L3) to improve discoverability - L1: Top level (e.g., Clothing) - L2: Sub-category (e.g., Shirts) - L3: Leaf category (e.g., Formal Shirts) > Categories are sales-channel specific: L1 and L2 remain common across channels while L3 names can vary per channel ### Brands - [GET /v3/catalog/company-brand](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchbrands.md): Retrieve the list of available brands or filter by name > Brands represent the manufacturer of a product > Each brand has a unique ID and name to help identify and differentiate products ### Templates - [GET /v3/catalog/product/template](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchtemplates.md): Retrieve the list of available product templates > Templates are predefined blueprints that enforce structure and validation for product data to ensure uniformity and compliance across listings ### Attributes By Product - [GET /v3/catalog/product-attributes](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchattributesbyproduct.md): Retrieve category-specific product attributes (mandatory and optional) > Use this API to discover which attributes are required for a given L3 category before creating products. If mandatory attributes are missing or invalid during creation, the request will fail with a validation error ### HS Code - [GET /v3/catalog/taxes/hscodes](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchhscode.md): Retrieve a company's HS/SAC codes used to classify goods and services for taxation ### Tax Rule IDs - [GET /v3/catalog/taxes/rules](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchtaxruleids.md): Retrieve available tax rules configured for the company, including rule status and version status ### Listings - [GET /ims/v3/listings](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchlistings.md): Retrieve SKUs from Fynd Commerce using flexible filters > Ideal for confirming product data, checking recently onboarded items, or auditing stock parity with Fynd. Supports pagination via page_no and page_size ### Product Count - [GET /ims/v3/listings/count](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchproductcount.md): Fetch a quick overview of the total products listed at the company level in the Fynd OMS. > Optionally include x-batch-product to check batch-based articles. Perfect for pre-sync validations or monitoring overall listing growth or discrepancy. ### Product - [GET /v3/catalog/product](https://documentation.fynd.com/konnect/apis/konnect/catalog/fetchproduct.md): Fetch the latest product details, including identifiers and size information > Supports filtering by name, slug, or item code and pagination ### Create Product - [POST /v3/catalog/product](https://documentation.fynd.com/konnect/apis/konnect/catalog/createproduct.md): Create one or more products in a single request. Each product can include multiple sizes (variants) along with traders, attributes, and global attributes > Prerequisites: Fetch and use valid values from the read APIs (Departments, Categories, Brands, Templates, Attributes, Tax Rule IDs, and HS Codes) to comply with platform validation > Note: You can create up to 100 products per API request ### Update Product - [PUT /v3/catalog/product](https://documentation.fynd.com/konnect/apis/konnect/catalog/updateproduct.md): Update details of an existing product > Immutable fields: slug, brand, brand_uid, item_code, and the top-level template must not be changed Update supports modifying name, description, media, tax rule ID, HS code, trader info, attributes, and global attributes (tags, return config, custom order, publish info) ### Delete Product - [DELETE /v3/catalog/product](https://documentation.fynd.com/konnect/apis/konnect/catalog/deleteproduct.md): Delete a whole product or a specific size (variant) > To delete an entire product, provide only the identifying fields (slug, brand, brand_uid, item_code) and the fixed template field in the request body > To delete a specific size, include the sizes array with the variant's primary identifier and GTIN details ### Check Product Status - [GET /v3/catalog/status](https://documentation.fynd.com/konnect/apis/konnect/catalog/checkproductstatus.md): Verify whether a previously submitted create/update/delete operation has completed, is pending, or failed > Supply the trace_id returned by the write API to obtain processing status and error details (if any) ## Pricing - Offers a way to set or update the MRP and ESP for your SKUs on a per-location basis, ensuring pricing uniformity across your internal systems and the Fynd platform - Supports high-volume updates (up to 500 records) in one call, streamlining real-time price adjustments for flash sales, promotions, or omni-channel pricing consistency ### Update Price - [PUT /ims/v3/price](https://documentation.fynd.com/konnect/apis/konnect/pricing/updateprice.md): Adjust or set the Maximum Retail Price (MRP) and Effective Selling Price (ESP) values for listed SKUs on a location basis. > Price updates for upto 500 SKUs can be performed in a single call, helping you keep pace with promotional events, dynamic pricing strategies, or bulk store-level changes. ## Inventory - Enables real-time stock-level management in the Fynd OMS. Update inventory quantities for each SKU across multiple locations, ensuring that Fynd accurately reflects item availability. Prevent overselling or stockouts by syncing frequently - Maximum 500 records can be updated in a single request ### Update Inventory - [PUT /ims/v3/inventory](https://documentation.fynd.com/konnect/apis/konnect/inventory/updateinventory.md): Increase or decrease stock levels for each SKU at a specific location. It enables near real-time synchronization and can help prevent overselling scenarios. > This API supports up to 500 record updates per request. ## Orders - Covers the entire end-to-end lifecycle of orders on Fynd, from initial retrieval through packing, dispatching, and final delivery. Includes: - Fetching new or updated orders - Cancellation of orders or specific items before invoicing - Confirmation of orders in bulk - Invoicing or credit note generation - Make order pack and dispatch calls - AWB and courier updates for self-ship scenarios - Order status transitions for self-ship scenarios (`bag_picked`, `delivery_done`, etc.) - Maximum 20 records can be updated in a single request ### Orders - [GET /oms/v3/shipment](https://documentation.fynd.com/konnect/apis/konnect/orders/getorders.md): - Retrieve orders filtered by Order Status, Ordering Channel, Date Range, or Location Code (when using company-level auth). - Useful to identify newly placed orders for fulfillment, manage different statuses in a consolidated environment, or Customer Returns by specifying orderStatus as RETURN_DELIVERED in parameters. - An Order can also be fetched by passing its shipment ID in parameters. ### Shipment Info - [GET /oms/v3/shipment/info](https://documentation.fynd.com/konnect/apis/konnect/orders/getshipmentinfo.md): A lightweight API specifically designed to efficiently retrieve crucial order and lock information - such as order status, order type, SLA, and lock status - without the need to poll for the entire order payload. This endpoint is ideal for quick status checks. > Either orderId or orderStatus is mandatory in the request parameters. ### Order Cancellation - [POST /oms/v3/shipment/cancel](https://documentation.fynd.com/konnect/apis/konnect/orders/cancelorder.md): Cancel entire orders or specific items before invoicing. Handles partial or full cancellations when the order is still in a pre-invoiced state. > Limits update of 20 orders per request ### Order Confirmation - [POST /oms/v3/shipment/confirm](https://documentation.fynd.com/konnect/apis/konnect/orders/confirmorder.md): This endpoint enables the finalization of the order after any required cancellations for subsequent packing, invoicing, and dispatch flows. > Limits update of 20 orders per request ### Update Invoice - [POST /oms/v3/shipment/invoiceUpdate](https://documentation.fynd.com/konnect/apis/konnect/orders/updateinvoice.md): Provide invoice details, overwrite packaging dimensions, or push IRN to Fynd Commerce for B2B invoicing using this endpoint. > Limits update of 20 orders per request Note: To generate credit note for a customer return or an RTO, pass "invoiceType": "return" ### Update AWB - [PUT /oms/v3/shipment/awb](https://documentation.fynd.com/konnect/apis/konnect/orders/updateawb.md): Add Air Waybill number and courier name for self-ship orders once they have physically shipped from the seller's warehouse. - Order: Update when the order is in the dp_assigned state on Fynd. - Fetch such orders using the GET Orders endpoint with "orderStatus = PROCESSING") - Returns: Update in the return_dp_assigned state on Fynd. - Fetch such returns using the GET Orders endpoint with "orderStatus = RETURN_PROCESSING") Note: Set autoDispatch = true for automatic state transition from dp_assigned to bag_picked on Fynd in one step. > Limits update of 20 orders per request ### Order Pack - [POST /oms/v3/shipment/pack](https://documentation.fynd.com/konnect/apis/konnect/orders/packorder.md): Marks unfulfilled orders as packed, readying them for dispatch. > Limits update of 20 orders per request ### Courier Details - [POST /oms/v3/shipment/courierDetails](https://documentation.fynd.com/konnect/apis/konnect/orders/getcourierdetails.md): Retrieve courier information for specific orders. > Limits update of 20 orders per request ### Shipping Label - [POST /oms/v3/shipment/labels](https://documentation.fynd.com/konnect/apis/konnect/orders/getshippinglabel.md): Generate and retrieve shipping label PDFs for one or more orders. Requested post Pack stage to attach shipping labels to outgoing parcels. > Limits update of 20 orders per request ### Customer Invoice - [POST /oms/v3/shipment/invoice](https://documentation.fynd.com/konnect/apis/konnect/orders/fetchcustomerinvoice.md): Generate and retrieve a customer invoice (PDF) for orders ready for dispatch. > Limits update of 20 orders per request ### Order Dispatch - [POST /oms/v3/shipment/dispatch](https://documentation.fynd.com/konnect/apis/konnect/orders/dispatchorder.md): Mark the order(s) as dispatched; indicating it has been handed over to the delivery partner. > Limits update of 20 orders per request ### Update Shipment Status - [PUT /oms/v3/shipment/status](https://documentation.fynd.com/konnect/apis/konnect/orders/updateshipmentstatus.md): Enables the updating of shipment statuses for self-ship orders post-dispatch. Allowed order status flow on Fynd for self-ship orders/returns: - Forward flow: dp_assigned → bag_picked → out_for_delivery (optional) → delivery_attempt_failed (optional) → delivery_reattempt_requested (optional) → delivery_done - Return flow: return_dp_assigned → return_bag_in_transit → return_bag_delivered - RTO flow: dp_assigned → bag_picked → rto_bag_delivered > Limits update of 20 orders per request ### Track Shipment - [POST /oms/v3/shipment/track](https://documentation.fynd.com/konnect/apis/konnect/orders/trackshipment.md): Track the real-time status and location of shipments using either shipment ID or AWB number > Either shipment_id or awb_number is mandatory; if both are provided, shipment_id takes priority. Supports tracking for both forward and return journeys ## Returns - Manages the reverse and RTO (Return to Origin) journeys for your orders: - Fetch returns by using GET Orders endpoint with `RETURN_DELIVERED` as the order status - Quality Check acceptance after items are returned to the seller - Credit Note issuance for returns or RTO using the PUT Update Inventory endpoint with `"invoiceType: return"` - All reverse processes remain in sync with Fynd OMS - Maximum 20 records can be updated in a single request ### Update Return & QC - [POST /oms/v3/shipment/return](https://documentation.fynd.com/konnect/apis/konnect/returns/updatereturnandqc.md): Accept returns/RTOs after QC checks while marking them as return_accepted on Fynd. Supports both Good QC and Bad QC acceptance. > Limits update of 20 returns per request. badQc Flag Behavior: - badQc: false (default) - Accepts returns with Good QC only - badQc: true - Accepts returns with Bad QC Quantity Handling: - The quantity field always refers to the returned quantity for the specific bag item in the request - If badQc: true, the entire quantity is treated as Bad QC quantity for that bag item - If badQc: false or omitted, the entire quantity is treated as Good QC quantity Reason Codes (Optional): Valid reason codes for returns: | Code | Description | |------|-------------| | 122 | Product looks different from image | | 118 | Wrong product delivered | | 113 | Damaged | | 106 | Stain found on product | | 110 | Looks Different | | 120 | Used product delivered | | 124 | Missing Items / Partially Received | > If reason code is omitted or invalid, an empty array will be passed to the system. For Good QC, an empty array is passed regardless of the reasonCode provided. Note: After finalizing bag items that pass inspection, the associated credit note can be generated using the Update Invoice/Credit Note endpoint where "invoiceType": "return".