# Konnect Platform API Reference The Konnect Platform APIs let custom marketplaces exchange order and inventory information with Konnect throughout the commerce lifecycle. Use this reference to: - Generate an access token for an onboarded marketplace integration. - Receive inventory delta notifications through a marketplace-hosted webhook. - Create orders with customer, shipment, item, payment, and pricing details. - Retrieve the Konnect order and shipment identifiers created for a marketplace order. - Assign courier and Air Waybill Number (AWB) details to self-ship shipments. - Send shipment-status updates for forward, return, and RTO journeys. **Authentication** Call **Generate Access Token** with the credentials issued for your marketplace integration. Send the returned JWT in the `x-access-token` header on every other Konnect-hosted endpoint in this reference. **Integration directions** - **Marketplace → Konnect:** authentication, order creation, order retrieval, courier/AWB updates, and shipment-status updates. - **Konnect → Marketplace:** inventory delta notifications sent to the webhook URL implemented and registered by the marketplace. Validate marketplace-to-Konnect calls in UAT before sending production traffic. Version: 1.0.0 ## Servers Konnect UAT environment for integration testing ``` https://gateway.konnect.uat.fyndx1.de ``` Konnect production environment ``` https://gateway.konnect.fynd.com ``` ## Security ### x-access-token JWT returned by Generate Access Token and required by all order endpoints. Type: apiKey In: header Name: x-access-token ## Download OpenAPI description [Konnect Platform API Reference](https://documentation.fynd.com/_bundle/konnect/apis/platform-api/@1.0.0/konnect.yaml) ## Authentication Generate the JWT required to authorize platform API requests. ### Generate Access Token - [GET /auth/{marketplace_slug}/token](https://documentation.fynd.com/konnect/apis/platform-api/konnect/authentication/generateaccesstoken.md): Exchanges the API username and password issued for a marketplace integration for a JWT access token. Send the returned access_token in the x-access-token request header when calling the order endpoints. Credentials are submitted as query parameters, so handle request URLs and logs as sensitive data. > The access token is valid for 24 Hours ## Inventory Receive sellable-inventory updates from Konnect through a marketplace-hosted webhook. ### Receive Inventory Delta Notification - [POST /inventory](https://documentation.fynd.com/konnect/apis/platform-api/konnect/inventory/inventorydeltawebhook.md): Defines the inventory notification endpoint that the marketplace must implement and register with Konnect. Fynd Konnect calls this marketplace-owned endpoint whenever sellable inventory changes for a seller SKU at a mapped location. The request body is an array because a notification can contain one or more inventory events. Each event provides the latest sellable quantity; it is not an increment or decrement to apply to the existing quantity. The marketplace owns the webhook URL and communicates its authentication requirements to Konnect during onboarding. This receiver does not use the Konnect x-access-token issued by Generate Access Token. ## Orders Create and retrieve orders, assign courier/AWB details, and update fulfillment statuses. ### Create Order - [POST /order/api/v1/{marketplace_slug}/create](https://documentation.fynd.com/konnect/apis/platform-api/konnect/orders/createorder.md): Creates a marketplace order in Konnect with one or more shipments. The request captures the identifiers needed to reconcile the order with the marketplace, along with addresses, fulfillment locations, line items, pricing, payments, coupon ownership, and optional delivery commitments. Use a unique external_order_id for the order, a unique external_shipment_id for each shipment, and an external_line_id for each marketplace line when one is available. Monetary values are expressed in the order's ordering_currency. The response returns the Konnect-generated fynd_order_id. Store this identifier; it is required to retrieve the order after creation. ### Fetch Order Details - [GET /order/api/v1/{marketplace_slug}/order](https://documentation.fynd.com/konnect/apis/platform-api/konnect/orders/fetchorderdetails.md): Retrieves the latest Konnect representation of an order using the fynd_order_id returned by Create Order. The response contains order-level pricing, payment and tax information, plus every associated shipment and bag. Store each shipment's shipment_id; the courier/AWB and shipment-status endpoints use that shipment identifier, not the order-level fynd_order_id. ### Update Courier Details - [PUT /order/api/v1/{marketplace_slug}/awb](https://documentation.fynd.com/konnect/apis/platform-api/konnect/orders/updatecourierdetails.md): Assigns courier and Air Waybill Number (AWB) details to one or more self-ship marketplace shipments. Use the shipment_id returned by Fetch Order Details as orderId. For custom marketplace integrations, send autoDispatch: false and isSelfShip: true for every item. With automatic dispatch disabled, update the shipment lifecycle explicitly through Update Shipment Status. ### Update Shipment Status - [PUT /order/api/v1/{marketplace_slug}/status](https://documentation.fynd.com/konnect/apis/platform-api/konnect/orders/updateshipmentstatus.md): Updates the fulfillment status of one or more self-ship marketplace shipments. Use the shipment_id returned by Fetch Order Details as order_id, and send isSelfShip: true for every item. Common lifecycle sequences are: - Forward: → dp_assigned → bag_picked → out_for_delivery → delivery_done - Delivery retry: → bag_picked → out_for_delivery → delivery_attempt_failed → delivery_reattempt_requested → out_for_delivery - Return: → return_initiated → return_bag_in_transit → return_bag_delivered - RTO: → bag_picked → rto_in_transit → rto_bag_delivered Exceptional statuses such as bag_lost, deadstock, rejected_by_customer, and cancelled_customer should be sent only when they match the shipment's current operational flow. Include the status-specific metadata required by the integration.